Reference · API v1 · Piano Agency

API Indagix v1

Quattro endpoint REST read-only per integrare Indagix nei tuoi sistemi: ricerca influencer con filtri, dettaglio profilo completo di recensioni, e accesso alle liste salvate del tuo workspace. Autenticazione via Bearer token, rate limit di 1000 richieste al giorno per chiave.

Autenticazione

Tutte le richieste devono includere l'header Authorization: Bearer <api_key>. Le chiavi hanno il prefisso ia_live_ e sono univoche per utente.

Come ottenere la chiave

L'accesso API è incluso nel piano Agency. Una volta attivato:

Accedi alla tua dashboard Indagix.
Apri la sezione Impostazioni → API Keys.
Clicca Genera nuova chiave: la stringa viene mostrata una sola volta — copiala subito in un password manager.
Da quel momento puoi usarla nell'header Authorization.

Esempio di richiesta autenticata

curl https://www.indagix.com/api/v1/influencers \
  -H "Authorization: Bearer ia_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Sicurezza: non includere mai la chiave in repository pubblici, codice client-side o URL. Se sospetti una compromissione revoca la chiave dalla dashboard e generane una nuova.

Rate limit

Ogni chiave ammette 1000 richieste al giorno (mezzanotte UTC). Il contatore si resetta automaticamente al cambio data. Ogni risposta include gli header:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 873
X-RateLimit-Reset: 2026-05-10T00:00:00.000Z

Al superamento del limite ricevi 429 Too Many Requests. Per quote più alte contattaci.

Codici di errore

Parametro	Tipo	Descrizione
`200`	`OK`	Richiesta riuscita.
`401`	`Unauthorized`	Header Authorization mancante, chiave revocata o formato non valido.
`403`	`Forbidden`	La chiave appartiene a un account senza piano Agency attivo.
`404`	`Not Found`	Risorsa non esistente o non accessibile dal tuo workspace.
`429`	`Too Many Requests`	Hai esaurito le 1000 richieste giornaliere. Riprova dopo il reset (mezzanotte UTC).
`500`	`Internal Error`	Errore lato server. Riprova; se persiste segnalalo.

Il body degli errori è sempre nella forma { "error": "messaggio descrittivo" }.

Ricerca influencer

GET/api/v1/influencers

Cerca influencer pubblicati nel database, con filtri su nicchia, piattaforma e fascia di follower. Risultati paginati.

Query parameters

Parametro	Tipo	Descrizione
`q`	`string`	Testo libero su nome o handle Instagram (case-insensitive).
`niche`	`string`	Filtra per nicchia (es. fashion, food, tech). Match esatto sull'array niche.
`platform`	`string`	Filtra per piattaforma (instagram, tiktok, youtube).
`min_followers`	`integer`	Soglia minima follower Instagram.
`max_followers`	`integer`	Soglia massima follower Instagram.
`page`	`integer`	Pagina (default: 1).
`per_page`	`integer`	Risultati per pagina (default: 20, max: 50).

Esempio

curl "https://www.indagix.com/api/v1/influencers?niche=food&min_followers=50000&per_page=10" \
  -H "Authorization: Bearer ia_live_..."

Risposta

{
  "data": [
    {
      "id": "uuid",
      "name": "Mario Rossi",
      "slug": "mario-rossi",
      "handle_instagram": "mariorossi",
      "niche": ["food", "lifestyle"],
      "platforms": ["instagram", "tiktok"],
      "country": "IT",
      "followers_instagram": 124000,
      "followers_tiktok": 89000,
      "followers_youtube": 0,
      "engagement_rate": "3.2%",
      "average_rating": 4.6,
      "reviews_count": 18,
      "verified": true,
      "photo": "https://...",
      "bio": "Food creator..."
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total": 47,
    "total_pages": 5
  }
}

Dettaglio influencer

GET/api/v1/influencers/:id

Restituisce il profilo completo di un influencer più tutte le recensioni verificate ricevute, ordinate per data discendente.

Path parameters

Parametro	Tipo	Descrizione
`id`obbligatorio	`uuid`	ID univoco dell'influencer (campo id restituito dalla ricerca).

Esempio

curl https://www.indagix.com/api/v1/influencers/00000000-0000-0000-0000-000000000000 \
  -H "Authorization: Bearer ia_live_..."

Risposta

Tutti i campi della tabella influencer più l'array reviews:

{
  "data": {
    "id": "uuid",
    "name": "Mario Rossi",
    "slug": "mario-rossi",
    "handle_instagram": "mariorossi",
    "bio": "Food creator...",
    "bio_extended": "...",
    "niche": ["food"],
    "platforms": ["instagram", "tiktok"],
    "country": "IT",
    "instagram_url": "https://instagram.com/mariorossi",
    "tiktok_url": "https://tiktok.com/@mariorossi",
    "youtube_url": null,
    "followers_instagram": 124000,
    "followers_tiktok": 89000,
    "followers_youtube": 0,
    "engagement_rate": "3.2%",
    "verified": true,
    "average_rating": 4.6,
    "reviews_count": 18,
    "management_agency_name": "One Shot Agency",
    "management_agency_url": "https://oneshot.agency",
    "reviews": [
      {
        "rating_generale": 5,
        "rating_comunicazione": 5,
        "rating_qualita": 4,
        "rating_puntualita": 5,
        "rating_prezzo": 4,
        "rating_professionalita": 5,
        "rating_brief": 5,
        "tipo_collaborazione": "post-storia",
        "data_collaborazione": "2026-03-15",
        "testo": "Collaborazione molto professionale...",
        "autore_nome": "Brand Verified",
        "created_at": "2026-03-20T14:30:00.000Z"
      }
    ]
  }
}

Liste salvate

GET/api/v1/lists

Restituisce tutte le liste salvate dell'utente proprietario della chiave (o del workspace condiviso), con conteggio degli influencer in ciascuna.

Esempio

curl https://www.indagix.com/api/v1/lists \
  -H "Authorization: Bearer ia_live_..."

Risposta

{
  "data": [
    {
      "id": "uuid",
      "nome": "Food Q2 2026",
      "descrizione": "Shortlist per campagna ricette estive",
      "items_count": 12,
      "created_at": "2026-04-01T10:00:00.000Z",
      "updated_at": "2026-05-01T15:22:00.000Z"
    }
  ]
}

Dettaglio lista

GET/api/v1/lists/:id

Restituisce metadati della lista più l'array completo degli influencer in essa contenuti (gli stessi campi della ricerca).

Path parameters

Parametro	Tipo	Descrizione
`id`obbligatorio	`uuid`	ID della lista. Solo le liste possedute (o condivise nel tuo workspace) sono accessibili: altrimenti 404.

Esempio

curl https://www.indagix.com/api/v1/lists/00000000-0000-0000-0000-000000000000 \
  -H "Authorization: Bearer ia_live_..."

Risposta

{
  "data": {
    "id": "uuid",
    "nome": "Food Q2 2026",
    "descrizione": "Shortlist per campagna ricette estive",
    "created_at": "2026-04-01T10:00:00.000Z",
    "updated_at": "2026-05-01T15:22:00.000Z",
    "influencers": [
      {
        "id": "uuid",
        "name": "Mario Rossi",
        "slug": "mario-rossi",
        "handle_instagram": "mariorossi",
        "niche": ["food"],
        "platforms": ["instagram", "tiktok"],
        "country": "IT",
        "followers_instagram": 124000,
        "followers_tiktok": 89000,
        "followers_youtube": 0,
        "engagement_rate": "3.2%",
        "average_rating": 4.6,
        "reviews_count": 18,
        "verified": true,
        "photo": "https://..."
      }
    ]
  }
}

Versioning

La versione corrente è v1. Le rotte sono prefissate con /api/v1/. Le modifiche non retro-compatibili saranno introdotte solo in una nuova major version (v2). Le aggiunte di campi alle risposte sono considerate retro-compatibili.

Non hai ancora una chiave?

L'accesso API è incluso nel piano Agency, insieme a report campagna white-label, membri illimitati nel team e quote estese sull'assistente AI.

Scopri il piano Agency →