Documentazione API livesurf.org

Accedi o registrati per ottenere la chiave API.

Accedi o registrati

API client LiveSurf

Data di aggiornamento della documentazione: 2026-03-18

Che cos'è

API REST di LiveSurf per gestire account, gruppi, pagine, sorgenti di traffico e statistiche.

  • Base URL: https://api.livesurf.ru
  • Formato: JSON
  • Autorizzazione: header Authorization: <API_KEY>
  • Rate limit: massimo 10 richieste al secondo

Avvio rapido

Header obbligatori

Authorization: <API_KEY>
Accept: application/json
Content-Type: application/json

Esempio GET

curl -sS "https://api.livesurf.ru/user/" \
  -H "Authorization: <API_KEY>" \
  -H "Accept: application/json"

Esempio POST

curl -sS -X POST "https://api.livesurf.ru/user/manualmode/" \
  -H "Authorization: <API_KEY>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"

Esempio PATCH

curl -sS -X PATCH "https://api.livesurf.ru/group/12345/" \
  -H "Authorization: <API_KEY>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{"name":"Gruppo aggiornato"}'

Esempio PUT

curl -sS -X PUT "https://api.livesurf.ru/group/12345/" \
  -H "Authorization: <API_KEY>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{"name":"Aggiornamento completo del gruppo", "hour_limit": 100, "day_limit": 5000}'

Mappa dell'API

Elenchi di riferimento e limiti

  • GET /categories/ — elenco delle categorie disponibili
  • GET /countries/ — elenco dei Paesi disponibili
  • GET /languages/ — elenco delle lingue disponibili
  • GET /limits/ — limiti dell'account corrente e limiti di riferimento per tipo di account

Sorgenti

  • GET /sources/search/ — elenco dei motori di ricerca
  • GET /sources/ad/ — elenco delle piattaforme pubblicitarie
  • GET /sources/messengers/ — elenco delle app di messaggistica
  • GET /sources/social/ — elenco dei social network
  • GET /sources/neural/ — elenco delle sorgenti AI
  • GET /sources/recommender/ — elenco delle sorgenti da sistemi di raccomandazione

Utente

  • GET /user/ — recupera le informazioni sull'utente
  • POST /user/automode/ — attiva la modalità ARC, campagna pubblicitaria automatica
  • POST /user/manualmode/ — attiva la modalità manuale

Gruppi

  • GET /group/all/ — informazioni sui gruppi aggiunti
  • GET /group/{group_id}/ — informazioni su un gruppo specifico
  • PATCH /group/{group_id}/ — modifica parziale delle impostazioni del gruppo
  • PUT /group/{group_id}/ — aggiornamento completo delle impostazioni del gruppo
  • DELETE /group/{group_id}/ — eliminazione del gruppo
  • POST /group/create/ — creazione di un nuovo gruppo
  • POST /group/{group_id}/clone/ — clonazione del gruppo
  • POST /group/{group_id}/add_credits/ — aggiunge crediti visita al gruppo in modalità manuale
  • POST /group/{group_id}/refund_credits/ — restituisce tutti i crediti del progetto al saldo principale in modalità manuale
  • POST /group/{group_id}/reorder/ — modifica l'ordine delle pagine nel gruppo

Pagine

  • GET /page/{page_id}/ — informazioni su una pagina specifica
  • PATCH /page/{page_id}/ — modifica parziale delle impostazioni della pagina
  • PUT /page/{page_id}/ — aggiornamento completo delle impostazioni della pagina
  • DELETE /page/{page_id}/ — eliminazione della pagina
  • POST /page/create/ — creazione di una nuova pagina
  • POST /page/{page_id}/clone/ — clonazione della pagina
  • POST /page/{page_id}/up/ — sposta la pagina di una posizione verso l'alto
  • POST /page/{page_id}/down/ — sposta la pagina di una posizione verso il basso
  • POST /page/{page_id}/start/ — avvia la pagina
  • POST /page/{page_id}/stop/ — ferma la pagina
  • GET /pages-compiled-stats/ — statistiche delle visite della pagina

Formato degli errori

Di norma l'API restituisce gli errori in questo formato:

{
  "errors": {
    "field": ["message"]
  }
}

oppure:

{
  "errors": {
    "detail": "message"
  }
}

Limiti e costi

GET /limits/

Restituisce limiti e costi, inclusi i dati di pricing.

Parametri: nessuno.

La risposta contiene 4 blocchi:

  • general.timezone — fuso orario usato dall'API.
  • limits — limiti di riferimento per tipo di account: Minimo (account_type_id: 0, min), Standard (1, pro), Premium (2, vip).
  • user.limits — limiti effettivi dell'utente corrente, incluse eventuali estensioni individuali.
  • pricing — costo della visita in base a showtime e modificatori.

Per validare UI e richieste usa user.limits.

Campi principali di user.limits

  • min_showtime / max_showtime — intervallo ammesso per ogni valore di page.showtime; from e to sono validati separatamente.
  • min_daylimit / max_daylimit — intervallo di group.day_limit; se min_daylimit = 0, è ammesso day_limit = 0.
  • min_hourlimit / max_hourlimit — intervallo di group.hour_limit; se min_hourlimit = 0, è ammesso hour_limit = 0.
  • min_imp / max_imp — intervallo ammesso per ogni valore di group.interval; se min_imp = 0, il valore può essere disattivato.
  • max_keywords — numero massimo di elementi in sources.keywords.settings.list.
  • max_backlinks — numero massimo di elementi in sources.backlinks.settings.list.
  • max_selectors — numero massimo di elementi in behavior.settings.clicks.list in modalità clicks.
  • max_active_pages — numero di slot per avviare pagine in contemporanea.
  • max_alternate_urls — numero di URL aggiuntivi; massimo totale di URL per pagina: 1 + max_alternate_urls.
  • max_total_pages — numero massimo di pagine per account.

Esempio di risposta:

{
  "general": {"timezone": "Europe/Moscow"},
  "limits": [
    {"account_type_id": 0, "account_type": "min", "min_showtime": 15, "max_showtime": 45, "min_daylimit": 0, "max_daylimit": 200, "min_hourlimit": 0, "max_hourlimit": 50, "min_imp": 0, "max_imp": 10800, "max_keywords": 50, "max_backlinks": 50, "max_selectors": 2, "max_active_pages": 1, "max_alternate_urls": 0, "max_total_pages": 100},
    {"account_type_id": 1, "account_type": "pro", "min_showtime": 15, "max_showtime": 300, "min_daylimit": 0, "max_daylimit": 1000, "min_hourlimit": 0, "max_hourlimit": 200, "min_imp": 0, "max_imp": 10800, "max_keywords": 100, "max_backlinks": 100, "max_selectors": 5, "max_active_pages": 12, "max_alternate_urls": 5, "max_total_pages": 200},
    {"account_type_id": 2, "account_type": "vip", "min_showtime": 15, "max_showtime": 900, "min_daylimit": 0, "max_daylimit": 2000, "min_hourlimit": 0, "max_hourlimit": 501, "min_imp": 0, "max_imp": 10800, "max_keywords": 300, "max_backlinks": 300, "max_selectors": 10, "max_active_pages": 24, "max_alternate_urls": 10, "max_total_pages": 104}
  ],
  "pricing": {
    "showtime_price": {"15": 0.5, "900": 499},
    "modifiers": [
      {"key": "geotargeting", "type": "percentage", "value": "0.30", "description": "Geotargeting attivo: +30%", "enabled": true},
      {"key": "low_pf", "type": "percentage", "value": "-0.70", "description": "Traffico con qualità comportamentale bassa: -70%", "enabled": true}
    ]
  },
  "user": {"limits": {"account_type_id": 2, "account_type": "vip", "min_showtime": 15, "max_showtime": 900, "min_daylimit": 0, "max_daylimit": 2000, "min_hourlimit": 0, "max_hourlimit": 501, "min_imp": 0, "max_imp": 10800, "max_keywords": 300, "max_backlinks": 300, "max_selectors": 10, "max_active_pages": 24, "max_alternate_urls": 10, "max_total_pages": 104}}
}

Elenchi di riferimento

GET /categories/

Categorie utilizzabili in group.category.

Parametri: nessuno.

Esempio di risposta:

[{"id": 1, "name": "Internet, Computer", "parent": 0, "active": true}]

GET /countries/

Paesi utilizzabili in group.geo.

Parametri: nessuno.

Esempio di risposta:

[{"id": 1, "country": "RU", "region": "", "city": "", "name": "Russia"}]

GET /languages/

Lingue utilizzabili in group.language.

Parametri: nessuno.

Esempio di risposta:

[{"id": 2, "name": "Russian", "translate_name": "Russo"}]

Sorgenti

GET /sources/search/

Elenco dei motori di ricerca per sources.keywords.settings.search_engines.

Parametri: nessuno.

Campi dell'elemento di risposta:

  • id — ID della sorgente, usato come chiave in sources.keywords.settings.search_engines.
  • name — nome della sorgente.
  • default — peso predefinito, come stringa numerica.
  • payload — dati della sorgente: iso, codice Paese/regione, per esempio "RU", "BY", "KZ", "global"; str_id, identificatore testuale, per esempio "mail_ru", "ya_by", "rambler_ru".
  • enable — disponibilità della sorgente.

Esempio di risposta:

[{"id": 11, "name": "Mail.RU", "default": "0.8", "payload": {"iso": "RU", "str_id": "mail_ru"}, "enable": true}]

GET /sources/ad/

Elenco delle piattaforme pubblicitarie per sources.adsystems.settings.

Parametri: nessuno.

Campi dell'elemento di risposta: name, default, payload, enable. In payload: iso, codice Paese/regione, per esempio "RU" o "global"; fullName, nome visualizzato, per esempio "Facebook", "Google AdSense", "Kavanga".

Esempio di risposta:

[{"name": "facebook", "default": true, "payload": {"iso": "global", "fullName": "Facebook"}, "enable": true}]

GET /sources/messengers/

Elenco delle app di messaggistica per sources.messengers.settings.

Parametri: nessuno.

Campi dell'elemento di risposta: name, default, payload, enable. In payload: iso, codice Paese/regione, per esempio "global" o "UA"; fullName, nome visualizzato, per esempio "Slack", "Viber", "WhatsApp".

Esempio di risposta:

[{"name": "telegram", "default": true, "payload": {"iso": "global", "fullName": "Telegram"}, "enable": true}]

GET /sources/social/

Elenco dei social network per sources.socialanalytics.settings.

Parametri: nessuno.

Campi dell'elemento di risposta: name, default, payload, enable. In payload: iso, codice Paese/regione, per esempio "global", "RU", "CN"; fullName, nome visualizzato, per esempio "Instagram", "Pinterest", "VK", "Weibo", "Douyin", "Reddit".

Esempio di risposta:

[{"name": "pinterest", "default": false, "payload": {"iso": "global", "fullName": "Pinterest"}, "enable": true}]

GET /sources/neural/

Elenco delle sorgenti AI per sources.neurals.settings.

Parametri: nessuno.

Campi dell'elemento di risposta: name, default, payload, enable. In payload: iso, codice Paese/regione, per esempio "US"; fullName, nome visualizzato, per esempio "Poe", "Microsoft Edge Services", "Exa", "QuillBot", "Reka AI".

Esempio di risposta:

[{"name": "poe", "default": false, "payload": {"iso": "US", "fullName": "Poe"}, "enable": true}]

GET /sources/recommender/

Elenco delle sorgenti da feed e sistemi di raccomandazione per sources.recommenders.settings.

Parametri: nessuno.

Campi dell'elemento di risposta: name, default, payload, enable. In payload: iso, codice Paese/regione, per esempio "global", "RU", "CN"; fullName, nome visualizzato, per esempio "Opera Personal News", "Мир тесен", "Toutiao", "Дзен".

Esempio di risposta:

[{"name": "opera_personal_news", "default": false, "payload": {"iso": "global", "fullName": "Opera Personal News"}, "enable": true}]

Utente

GET /user/

Restituisce i parametri dell'utente e la modalità corrente.

Parametri: nessuno.

Campi principali della risposta:

  • credits — saldo corrente dei crediti.
  • workmode — modalità: 0 manuale, 1 automatica.
  • type — ID del tipo di account, solo informativo; per validare i limiti usa GET /limits/ -> user.limits.
  • experience — esperienza dell'utente.
  • token — token dell'utente.
  • is_active — stato dell'account.

Esempio di risposta:

{"credits": "170491620.33332", "workmode": 0, "type": 2, "experience": 72009, "token": "...", "is_active": true}

POST /user/automode/

Attiva la modalità automatica (ARC).

Parametri: nessuno.

Esempio di risposta:

{"status": 1}

POST /user/manualmode/

Attiva la modalità manuale.

Parametri: nessuno.

Esempio di risposta:

{"status": 1}

Gruppi

GET /group/all/

Restituisce tutti i gruppi dell'account, con configurazione completa e pagine incluse.

Parametri: nessuno.

Esempio di risposta:

[
  {
    "id": 123,
    "name": "Il mio gruppo",
    "hour_limit": 50,
    "day_limit": 1000,
    "interval": [30, 180],
    "uniq_ip": 0,
    "moby_ratio": 50,
    "geo": [1, 2],
    "autocalc_visits": {"enabled": false, "lower_at_night": false, "lower_at_week": false},
    "use_profiles": true,
    "retention": true,
    "description": "",
    "timezone": "Europe/Moscow",
    "category": 1,
    "language": 2,
    "bookmarks": [10, 40],
    "autolimit": [-10, 10],
    "schedules": [],
    "low_pf": {"enabled": false, "ratio": 30},
    "sources": {
      "keywords": {"value": 50, "enabled": true, "settings": {"list": ["frase di esempio"], "search_engines": {"1": 1}}},
      "adsystems": {"value": 20, "enabled": true, "settings": ["B2BContext"]},
      "backlinks": {"value": 10, "enabled": true, "settings": {"list": ["https://example.com"]}},
      "messengers": {"value": 5, "enabled": true, "settings": ["telegram"]},
      "clickunders": {"value": 5, "enabled": true},
      "emailanalytics": {"value": 5, "enabled": true},
      "socialanalytics": {"value": 5, "enabled": true, "settings": ["pinterest"]},
      "neurals": {"value": 0, "enabled": false, "settings": []},
      "recommenders": {"value": 0, "enabled": false, "settings": []},
      "qrcodes": {"value": 0, "enabled": false}
    },
    "pages": [{"id": 999, "state": 1, "position": 0, "url": ["https://example.com/"], "showtime": [15, 30], "break_chain": 0, "adult": false, "group_id": 123, "behavior": {"mode": "disabled", "settings": {"reading_up": false, "clicks": {"list": []}}}}],
    "credits": 0
  }
]

GET /group/{group_id}/

Restituisce la configurazione completa di un gruppo specifico.

Parametri URL:

  • group_id — ID del gruppo.

L'elenco dei group_id si ottiene con GET /group/all/.

Esempio di risposta:

{
  "id": 123,
  "name": "Il mio gruppo",
  "hour_limit": 50,
  "day_limit": 1000,
  "interval": [30, 180],
  "uniq_ip": 0,
  "moby_ratio": 50,
  "geo": [1, 2],
  "stopping_hours": [1, 2, 3],
  "autocalc_visits": {"enabled": false, "lower_at_night": false, "lower_at_week": false},
  "use_profiles": true,
  "retention": true,
  "description": "",
  "timezone": "Europe/Moscow",
  "category": 1,
  "language": 2,
  "bookmarks": [10, 40],
  "autolimit": [-10, 10],
  "schedules": [],
  "low_pf": {"enabled": false, "ratio": 30},
  "sources": {"keywords": {"value": 50, "enabled": true, "settings": {"list": ["frase di esempio"], "search_engines": {"1": 1}}}, "adsystems": {"value": 20, "enabled": true, "settings": ["B2BContext"]}, "backlinks": {"value": 10, "enabled": true, "settings": {"list": ["https://example.com"]}}, "messengers": {"value": 5, "enabled": true, "settings": ["telegram"]}, "clickunders": {"value": 5, "enabled": true}, "emailanalytics": {"value": 5, "enabled": true}, "socialanalytics": {"value": 5, "enabled": true, "settings": ["pinterest"]}, "neurals": {"value": 0, "enabled": false, "settings": []}, "recommenders": {"value": 0, "enabled": false, "settings": []}, "qrcodes": {"value": 0, "enabled": false}},
  "pages": [{"id": 999, "state": 1, "position": 0, "url": ["https://example.com/"], "showtime": [15, 30], "break_chain": 0, "adult": false, "group_id": 123, "behavior": {"mode": "neural", "settings": {"reading_up": true, "clicks": {"list": ["a", ".link"]}}}}],
  "credits": 0
}

PATCH /group/{group_id}/

Aggiorna parzialmente un gruppo. Cambiano solo i campi inviati; gli altri restano invariati. La validazione riguarda solo i campi presenti nella richiesta.

Parametri URL:

  • group_id — ID del gruppo.

Corpo della richiesta: qualsiasi sottoinsieme dei campi seguenti.

Campi principali:

  • name (string) — nome del gruppo, fino a 255 caratteri.
  • hour_limit (int) — limite orario nell'intervallo min_hourlimit..max_hourlimit da /limits/; se min_hourlimit = 0, è ammesso 0.
  • day_limit (int) — limite giornaliero nell'intervallo min_daylimit..max_daylimit; se min_daylimit = 0, è ammesso 0.
  • interval (array[int,int]) — intervallo tra le visite [from, to]; ogni valore deve rientrare in min_imp..max_imp.
  • uniq_ip (int) — unicità IP in ore: 0 disattivato, massimo 168.
  • moby_ratio (int) — quota di traffico mobile 0..100.
  • geo (array[int]) — elenco dei Paesi (GET /countries/).
  • autocalc_visits (object) — calcolo automatico dei limiti:
    • enabled (bool)
    • lower_at_night (bool) — riduce le visite notturne fino al 10% rispetto al fuso orario del gruppo
    • lower_at_week (bool)
  • use_profiles (bool) — profili di visitatori con cronologia di ricerca attiva, per migliorare la qualità comportamentale.
  • retention (bool) — mantenimento del visitatore.
  • description (string) — descrizione fino a 100 caratteri.
  • timezone (string) — TZID, per esempio Europe/Moscow.
  • stopping_hours (array[int]) — ore della settimana, 1..168.
  • category (int) — ID della categoria (GET /categories/).
  • language (int) — ID della lingua (GET /languages/).
  • bookmarks (array[int,int]) — intervallo delle visite dai preferiti.
  • autolimit (array[int,int]) — intervallo di modifica automatica del limite giornaliero (-500..500).
  • low_pf (object) — traffico con qualità comportamentale bassa:
    • enabled (bool)
    • ratio (int)
  • schedules (array) — pianificazione (Premium): elementi nel formato [state, "dd.mm.yyyy HH:MM"]; state: 0 — pausa, 1 — riprendi visite. Esempio: [[1, "07.02.2026 14:17"], [0, "08.02.2026 10:00"]].
  • sources (object) — impostazioni delle sorgenti di visite.

Struttura di sources:

  • keywords:
    • value (int), enabled (bool)
    • settings.list (array[string]) — massimo max_keywords
    • settings.search_engines (map[string,float]) — chiavi: id da GET /sources/search/; valori: float da 0 a 1, quota di utilizzo del motore di ricerca
  • adsystems:
    • value (int), enabled (bool)
    • settings (array[string]) — valori da GET /sources/ad/
  • backlinks:
    • value (int), enabled (bool)
    • settings.list (array[string]) — massimo max_backlinks
  • messengers:
    • value (int), enabled (bool)
    • settings (array[string]) — valori da GET /sources/messengers/
  • clickunders: value (int), enabled (bool)
  • emailanalytics: value (int), enabled (bool)
  • socialanalytics:
    • value (int), enabled (bool)
    • settings (array[string]) — valori da GET /sources/social/
  • neurals:
    • value (int), enabled (bool)
    • settings (array[string]) — valori da GET /sources/neural/
  • recommenders:
    • value (int), enabled (bool)
    • settings (array[string]) — valori da GET /sources/recommender/
  • qrcodes: value (int), enabled (bool)

Esempi di strutture per sorgente

keywords (visite dai motori di ricerca):

"keywords": {"value": 50, "enabled": true, "settings": {"list": ["frase di esempio", "altra frase"], "search_engines": {"1": 0.7, "2": 0.3}}}

adsystems (visite da piattaforme pubblicitarie):

"adsystems": {"value": 20, "enabled": true, "settings": ["B2BContext", "adfox"]}

backlinks (visite da link diretti):

"backlinks": {"value": 10, "enabled": true, "settings": {"list": ["https://example.com", "https://example.com/page"]}}

messengers (visite da app di messaggistica):

"messengers": {"value": 5, "enabled": true, "settings": ["telegram", "whatsapp"]}

clickunders (visite da clickunder):

"clickunders": {"value": 5, "enabled": true}

emailanalytics (visite da campagne email):

"emailanalytics": {"value": 5, "enabled": true}

socialanalytics (visite dai social network):

"socialanalytics": {"value": 5, "enabled": true, "settings": ["pinterest", "instagram"]}

neurals (visite da sorgenti AI):

"neurals": {"value": 5, "enabled": true, "settings": ["chatgpt", "poe"]}

recommenders (visite da feed e sistemi di raccomandazione):

"recommenders": {"value": 5, "enabled": true, "settings": ["dzen", "opera_personal_news"]}

qrcodes (visite tramite codici QR):

"qrcodes": {"value": 5, "enabled": true}

Esempio di richiesta:

curl -sS -X PATCH "https://api.livesurf.ru/group/123/" \
  -H "Authorization: <API_KEY>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{
    "hour_limit": 100,
    "day_limit": 10000,
    "interval": [60, 300],
    "autocalc_visits": {"enabled": true, "lower_at_night": true, "lower_at_week": false},
    "sources": {
      "keywords": {"value": 50, "enabled": true, "settings": {"list": ["Frase di ricerca"], "search_engines": {"1": 1}}},
      "adsystems": {"value": 50, "enabled": true, "settings": ["B2BContext"]}
    }
  }'

Esempio di risposta: stessa struttura di GET /group/{group_id}/, con tutti i campi del gruppo.

Esempio di configurazione completa, corpo per PATCH o frammento per PUT:

{
  "name": "Il mio gruppo",
  "hour_limit": 100,
  "day_limit": 10000,
  "interval": [60, 300],
  "uniq_ip": 0,
  "moby_ratio": 50,
  "geo": [1, 2],
  "timezone": "Europe/Moscow",
  "stopping_hours": [1, 2, 4, 5, 7, 9],
  "autocalc_visits": {"enabled": true, "lower_at_night": true, "lower_at_week": false},
  "use_profiles": true,
  "retention": true,
  "description": "",
  "category": 1,
  "language": 1,
  "bookmarks": [10, 40],
  "autolimit": [-10, 10],
  "low_pf": {"enabled": false, "ratio": 30},
  "schedules": [[1, "07.02.2026 14:17"], [0, "08.02.2026 10:00"]],
  "sources": {"keywords": {"value": 50, "enabled": true, "settings": {"list": ["Frase di ricerca"], "search_engines": {"1": 1}}}, "adsystems": {"value": 20, "enabled": true, "settings": ["B2BContext"]}, "backlinks": {"value": 10, "enabled": true, "settings": {"list": ["https://example.com"]}}, "messengers": {"value": 5, "enabled": true, "settings": ["telegram"]}, "clickunders": {"value": 5, "enabled": true}, "emailanalytics": {"value": 5, "enabled": true}, "socialanalytics": {"value": 5, "enabled": true, "settings": ["pinterest"]}, "neurals": {"value": 0, "enabled": false, "settings": []}, "recommenders": {"value": 0, "enabled": false, "settings": []}, "qrcodes": {"value": 0, "enabled": false}}
}

PUT /group/{group_id}/

Aggiorna completamente un gruppo. A differenza di PATCH, PUT sostituisce tutte le impostazioni del gruppo. I campi assenti nel corpo della richiesta tornano ai valori predefiniti. La validazione riguarda tutti i campi.

Parametri URL:

  • group_id — ID del gruppo.

Corpo della richiesta: gli stessi campi di PATCH /group/{group_id}/.

Esempio di richiesta:

curl -sS -X PUT "https://api.livesurf.ru/group/123/" \
  -H "Authorization: <API_KEY>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{"name": "Il mio gruppo", "hour_limit": 100, "day_limit": 10000, "interval": [60, 300], "uniq_ip": 0, "moby_ratio": 0, "geo": [1], "timezone": "Europe/Moscow", "autocalc_visits": {"enabled": false, "lower_at_night": false, "lower_at_week": false}, "sources": {"keywords": {"value": 50, "enabled": true, "settings": {"list": ["Frase di ricerca"], "search_engines": {"1": 1}}}}}'

Esempio di risposta: stessa struttura di GET /group/{group_id}/, con tutti i campi del gruppo.

DELETE /group/{group_id}/

Elimina il gruppo e tutte le pagine incluse.

Parametri URL:

  • group_id — ID del gruppo.

Esempio di risposta:

{"status": 1}

POST /group/{group_id}/clone/

Clona un gruppo insieme a tutte le sue pagine.

Parametri URL:

  • group_id — ID del gruppo.

Corpo della richiesta:

  • name (string, opzionale) — nome del nuovo gruppo.

Esempio di risposta: struttura completa come in GET /group/{group_id}/. Esempio:

{"id": 456, "name": "Copia 2 del mio gruppo", "hour_limit": 50, "day_limit": 1000, "interval": [30, 180], "uniq_ip": 0, "moby_ratio": 50, "geo": [1, 2], "stopping_hours": [], "autocalc_visits": {"enabled": false, "lower_at_night": false, "lower_at_week": false}, "use_profiles": true, "retention": true, "description": "", "timezone": "Europe/Moscow", "category": 1, "language": 2, "bookmarks": [10, 40], "autolimit": [-10, 10], "schedules": [], "low_pf": {"enabled": false, "ratio": 30}, "sources": {"keywords": {"value": 50, "enabled": true, "settings": {"list": ["frase di esempio"], "search_engines": {"1": 1}}}, "adsystems": {"value": 20, "enabled": true, "settings": ["B2BContext"]}, "backlinks": {"value": 10, "enabled": true, "settings": {"list": ["https://example.com"]}}, "messengers": {"value": 5, "enabled": true, "settings": ["telegram"]}, "clickunders": {"value": 5, "enabled": true}, "emailanalytics": {"value": 5, "enabled": true}, "socialanalytics": {"value": 5, "enabled": true, "settings": ["pinterest"]}, "neurals": {"value": 0, "enabled": false, "settings": []}, "recommenders": {"value": 0, "enabled": false, "settings": []}, "qrcodes": {"value": 0, "enabled": false}}, "pages": [{"id": 1001, "state": 0, "position": 0, "url": ["https://example.com/"], "showtime": [15, 30], "break_chain": 0, "adult": false, "group_id": 456, "behavior": {"mode": "disabled", "settings": {"reading_up": false, "clicks": {"list": []}}}}, {"id": 1002, "state": 0, "position": 1, "url": ["https://example.com/page2"], "showtime": [15, 30], "break_chain": 0, "adult": false, "group_id": 456, "behavior": {"mode": "disabled", "settings": {"reading_up": false, "clicks": {"list": []}}}}], "credits": 0}

POST /group/{group_id}/add_credits/

Aggiunge crediti visita al progetto in modalità manuale.

Parametri URL:

  • group_id — ID del gruppo.

Corpo della richiesta:

  • credits (int) — quantità di crediti da aggiungere. Sono ammessi solo valori positivi, maggiori di 0. Il metodo è disponibile solo in modalità manuale.

Esempio di richiesta:

curl -sS -X POST "https://api.livesurf.ru/group/123/add_credits/" \
  -H "Authorization: <API_KEY>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{"credits": 100}'

Esempio di risposta:

{"status": 1}

POST /group/{group_id}/refund_credits/

Restituisce tutti i crediti del progetto al saldo principale dell'account, in modalità manuale.

Parametri URL:

  • group_id — ID del gruppo.

Parametri del corpo: nessuno.

Esempio di risposta:

{"status": 1}

POST /group/{group_id}/reorder/

Modifica l'ordine delle pagine nel gruppo. L'ordine è definito da page_ids: il primo ID assume position 0, il secondo position 1 e così via.

Dopo l'aggiornamento, GET /group/{group_id}/ e GET /group/all/ restituiscono le pagine nel nuovo ordine. Se page_ids non è un array, è vuoto, contiene ID esterni al gruppo, è incompleto o contiene duplicati, l'API restituisce 400 con errors.page_ids.

Parametri URL:

  • group_id — ID del gruppo.

Corpo della richiesta:

  • page_ids (array of int) — elenco completo degli ID delle pagine del gruppo, senza duplicati, nell'ordine desiderato. Deve contenere esattamente tutte le pagine del gruppo.

Esempio di richiesta:

curl -sS -X POST "https://api.livesurf.ru/group/12345/reorder/" \
  -H "Authorization: <API_KEY>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{"page_ids": [102, 101, 103]}'

Esempio di risposta:

{"id": 12345}

POST /group/create/

Crea un gruppo con le relative pagine.

Campi del corpo della richiesta:

  • Sono supportati gli stessi campi di configurazione del gruppo di PATCH /group/{group_id}/.
  • In più:
    • pages (array) — elenco delle pagine da creare.
    • Ogni elemento di pages usa i campi di POST /page/create/.

Limitazioni importanti:

  • sources.keywords.settings.list <= max_keywords.
  • sources.backlinks.settings.list <= max_backlinks.
  • Numero totale di pagine dell'account <= max_total_pages.

Esempio di richiesta, configurazione completa con più pagine e tutte le sorgenti:

{"name": "Gruppo 27", "hour_limit": 50, "day_limit": 10000, "interval": [60, 300], "uniq_ip": 0, "moby_ratio": 50, "geo": [1, 2], "timezone": "Europe/Moscow", "autocalc_visits": {"enabled": false, "lower_at_night": false, "lower_at_week": false}, "use_profiles": true, "retention": true, "category": 1, "language": 1, "bookmarks": [10, 40], "autolimit": [-10, 10], "schedules": [[1, "07.02.2026 14:17"], [0, "08.02.2026 10:00"]], "pages": [{"url": ["https://example.com/", "https://example.com/page2"], "showtime": [15, 30], "state": 0, "break_chain": 10}, {"url": ["https://example.com/page3", "https://example.com/page4"], "showtime": [15, 30], "state": 0, "break_chain": 0}], "sources": {"keywords": {"value": 50, "enabled": true, "settings": {"list": ["frase chiave 1", "frase chiave 2"], "search_engines": {"1": 1, "2": 0.5}}}, "adsystems": {"value": 20, "enabled": true, "settings": ["B2BContext"]}, "backlinks": {"value": 10, "enabled": true, "settings": {"list": ["https://example.com"]}}, "messengers": {"value": 5, "enabled": true, "settings": ["telegram"]}, "clickunders": {"value": 5, "enabled": true}, "emailanalytics": {"value": 5, "enabled": true}, "socialanalytics": {"value": 5, "enabled": true, "settings": ["pinterest"]}, "neurals": {"value": 0, "enabled": false, "settings": []}, "recommenders": {"value": 0, "enabled": false, "settings": []}, "qrcodes": {"value": 0, "enabled": false}}}

Esempio di risposta: struttura completa come in GET /group/{group_id}/. Esempio:

{"id": 789, "name": "Gruppo 27", "hour_limit": 50, "day_limit": 10000, "interval": [60, 300], "uniq_ip": 0, "moby_ratio": 50, "geo": [1, 2], "stopping_hours": [], "autocalc_visits": {"enabled": false, "lower_at_night": false, "lower_at_week": false}, "use_profiles": true, "retention": true, "description": "", "timezone": "Europe/Moscow", "category": 1, "language": 1, "bookmarks": [10, 40], "autolimit": [-10, 10], "schedules": [], "low_pf": {"enabled": false, "ratio": 30}, "sources": {"keywords": {"value": 50, "enabled": true, "settings": {"list": ["frase chiave 1"], "search_engines": {"1": 1}}}, "adsystems": {"value": 20, "enabled": true, "settings": ["B2BContext"]}, "backlinks": {"value": 10, "enabled": true, "settings": {"list": ["https://example.com"]}}, "messengers": {"value": 5, "enabled": true, "settings": ["telegram"]}, "clickunders": {"value": 5, "enabled": true}, "emailanalytics": {"value": 5, "enabled": true}, "socialanalytics": {"value": 5, "enabled": true, "settings": ["pinterest"]}, "neurals": {"value": 0, "enabled": false, "settings": []}, "recommenders": {"value": 0, "enabled": false, "settings": []}, "qrcodes": {"value": 0, "enabled": false}}, "pages": [{"id": 1001, "state": 0, "position": 0, "url": ["https://example.com/", "https://example.com/page2"], "showtime": [15, 30], "break_chain": 10, "adult": false, "group_id": 789, "behavior": {"mode": "disabled", "settings": {"reading_up": false, "clicks": {"list": []}}}}], "credits": 0}

Esempio di errore di validazione (400):

{"errors": {"pages": ["Ensure this field has at least 1 elements."]}}

Pagine

GET /page/{page_id}/

Restituisce la configurazione della pagina.

Parametri URL:

  • page_id — ID della pagina.

Gli ID delle pagine si ottengono con GET /group/{group_id}/.

Esempio di risposta:

{"id": 1086337, "state": 1, "position": 3, "url": ["https://example.com/"], "showtime": [15, 45], "break_chain": 10, "adult": false, "group_id": 123, "behavior": {"mode": "neural", "settings": {"reading_up": true, "clicks": {"list": ["a", ".css-class", "#css-id"]}}}}

PATCH /page/{page_id}/

Aggiorna parzialmente una pagina. Cambiano solo i campi inviati.

Parametri URL:

  • page_id — ID della pagina.

Campi principali del corpo:

  • state (int): 0 pausa, 1 attiva.
  • break_chain (int): probabilità di interrompere la sequenza (0-100).
  • url (array[string]): elenco di URL sullo stesso dominio, massimo 1 + max_alternate_urls.
  • showtime (array[int,int]): [from, to]; ogni valore deve rientrare separatamente in min_showtime..max_showtime.
  • behavior (object): impostazioni del comportamento.

behavior.mode:

  • disabled — comportamento disattivato.
  • clicks — clic sui selettori indicati.
  • fixation — mantiene il visitatore con un clic finale.
  • neural — comportamento generato dall'AI.
  • manual — comportamento configurato manualmente tramite scenario JSON di azioni.

behavior.settings:

  • reading_up (bool) — lettura fino in fondo: aggiunge lo scroll fino alla parte bassa della pagina in qualsiasi modalità, tranne la configurazione manuale.
  • clicks.list (array[string]) — selettori CSS per la modalità clicks, massimo max_selectors. Il clic viene eseguito su uno dei selettori dell'elenco, scelto casualmente all'inizio della visita.

behavior.manual, solo per mode = "manual":

  • actions (object) — scenario JSON delle azioni sulla pagina.

Esempio di richiesta:

curl -sS -X PATCH "https://api.livesurf.ru/page/1086337/" \
  -H "Authorization: <API_KEY>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{"url": ["https://example.com/page_1.html", "https://example.com/page_2.html"], "break_chain": 10, "showtime": [30, 45], "behavior": {"mode": "neural", "settings": {"reading_up": true, "clicks": {"list": ["a", "span", "#awesome_button"]}}}, "state": 1}'

Esempio di risposta:

{"id": 1086337}

PUT /page/{page_id}/

Aggiorna completamente una pagina. A differenza di PATCH, PUT sostituisce tutte le impostazioni della pagina. I campi assenti nel corpo della richiesta tornano ai valori predefiniti. La validazione riguarda tutti i campi.

Parametri URL:

  • page_id — ID della pagina.

Corpo della richiesta: gli stessi campi di PATCH /page/{page_id}/.

Esempio di risposta:

{"id": 1086337}

DELETE /page/{page_id}/

Elimina una pagina. Se nel gruppo non resta nessuna pagina, viene eliminato anche il gruppo.

Parametri URL:

  • page_id — ID della pagina.

Esempio di risposta:

{"status": 1}

POST /page/create/

Crea una nuova pagina.

Campi del corpo:

  • group_id (int) — ID del gruppo.
  • state (int) — 0/1.
  • break_chain (int) — probabilità di interruzione (0-100).
  • url (array[string]) — fino a 1 + max_alternate_urls.
  • showtime (array[int,int]) — ogni valore in min_showtime..max_showtime.
  • behavior (object) — impostazioni del comportamento.

Esempio di richiesta:

{"group_id": 123, "state": 0, "break_chain": 10, "url": ["https://example.com/", "https://example.com/page2"], "showtime": [15, 30], "behavior": {"mode": "disabled", "settings": {"reading_up": true, "clicks": {"list": ["a"]}}}}

Esempio di risposta:

{"id": 1}

Esempio di errore di validazione (400):

{"errors": {"group_id": "Group with group_id=0 does not exist"}}

POST /page/{page_id}/clone/

Clona una pagina all'interno del gruppo e inserisce la nuova pagina alla fine dell'elenco.

Parametri URL:

  • page_id — ID della pagina.

Esempio di risposta:

{"id": 1087000}

POST /page/{page_id}/up/

Sposta la pagina di 1 posizione verso l'alto nell'elenco.

Parametri URL:

  • page_id — ID della pagina.

Esempio di risposta:

{"status": 1}

POST /page/{page_id}/down/

Sposta la pagina di 1 posizione verso il basso nell'elenco.

Parametri URL:

  • page_id — ID della pagina.

Esempio di risposta:

{"status": 1}

POST /page/{page_id}/start/

Avvia la pagina.

Parametri URL:

  • page_id — ID della pagina.

Esempio di risposta:

{"status": 1}

POST /page/{page_id}/stop/

Ferma la pagina.

Parametri URL:

  • page_id — ID della pagina.

Esempio di risposta:

{"status": 1}

Statistiche

GET /pages-compiled-stats/

Restituisce le statistiche delle visite per pagina o gruppo in una data o in un periodo. L'intervallo massimo è di 7 giorni.

Parametri query:

  • page_id (int) oppure group_id (int)
  • e una delle varianti di periodo:
    • date (YYYY-MM-DD)
    • date_from + date_to (YYYY-MM-DD)

Esempio di richiesta:

curl -sS "https://api.livesurf.ru/pages-compiled-stats/?group_id=123&date=2026-02-19" \
  -H "Authorization: <API_KEY>" \
  -H "Accept: application/json"

Esempio di risposta:

[{"group_id": 123, "page_id": 1086337, "visits": 42, "credits": 98, "date": "19.02.2026", "date_update": "19.02.2026 15:57:24"}]

Esempio di errore (400):

{"errors": {"non_field_errors": ["required parameter \"date\" or parameters \"date_from\" and \"date_to\""]}}

Buone pratiche

  • Inizia sempre da GET /limits/, poi valida i moduli in base a user.limits.
  • Nel calcolo del prezzo considera pricing.showtime_price e pricing.modifiers.
  • Per le operazioni massive rispetta il limite di 10 rps.
  • Controlla i vincoli max_* lato client prima di inviare le richieste.
  • Conserva le risposte 400 reali dell'integrazione: sono più utili dei messaggi generici.