Prerequisiti

Prima di integrare l'API REST, assicurati di disporre di:

1

Un account Agente o Partner

L'accesso all'API richiede un piano Agente o superiore, o lo status di partner. Richiedi l'accesso se non ne hai ancora uno.

2

Una chiave API REST

Avrai bisogno di una chiave API (formato aila_...) generata dalla pagina API & Integrazioni.

3

Un client HTTP

Qualsiasi client HTTP va bene: curl, Python requests, JavaScript fetch, Postman, ecc.

Ottenere la chiave API

La tua chiave API è la stessa utilizzata per le connessioni MCP. Se ne hai già una, puoi utilizzarla direttamente.

1

Vai in API & Integrazioni

Naviga verso Account → API & Integrazioni nel tuo pannello di controllo.

2

Creare una nuova chiave

Clicca su "Crea una chiave API", assegnale un nome (es. "La mia App") e seleziona i permessi desiderati.

3

Copiare e conservare in modo sicuro

La tua chiave inizia con aila_. Copiala immediatamente — non verrà più visualizzata. Conservala in una variabile d'ambiente, mai nel codice sorgente.

Suggerimento

Puoi anche esplorare l'API in modo interattivo tramite la nostra documentazione Swagger multilingue (/api/v1/docs?lang=fr|en|es|de) che elenca i 119 endpoint disponibili.

Autenticazione

L'API supporta due metodi di autenticazione. Scegli quello più adatto al tuo stack:

Metodo 1: Header X-Api-Key

CURL

curl -H "X-Api-Key: aila_your_key_here" \
     https://ailabsaudit.com/api/v1/clients

Metodo 2: Authorization Bearer

CURL

curl -H "Authorization: Bearer aila_your_key_here" \
     https://ailabsaudit.com/api/v1/clients

Sicurezza

Non esporre mai la tua chiave API in codice lato client (JavaScript nel browser). Effettua sempre le chiamate API dal tuo server (backend).

Prima richiesta

Verifichiamo che la tua connessione funzioni recuperando l'elenco dei tuoi clienti:

CURL

curl -s -H "X-Api-Key: aila_your_key_here" \
     https://ailabsaudit.com/api/v1/clients | python3 -m json.tool

Risposta riuscita (200 OK)

JSON

{
    "success": true,
    "data": [
        {
            "id": 42,
            "name": "Acme Corp",
            "sector": "Technology",
            "website": "https://acme.com",
            "country": "FR",
            "created_at": "2025-01-15T10:30:00Z"
        }
    ],
    "pagination": {
        "page": 1,
        "per_page": 20,
        "total": 1,
        "total_pages": 1
    }
}

È tutto!

Se vedi l'elenco dei tuoi clienti, la tua chiave API funziona. Ora puoi esplorare tutti gli endpoint disponibili qui sotto.

Endpoint

L'API è organizzata in 12 gruppi di endpoint per un totale di 119 endpoint. Tutti gli URL sono preceduti da https://ailabsaudit.com/api/v1/. Gli endpoint di contenuto accettano un parametro opzionale ?lang=fr|en|es|de per risposte multilingue.

Clienti

Metodo	Endpoint	Description
GET	`/clients`	Elencare tutti i clienti
GET	`/clients/{id}`	Dettaglio di un cliente
GET	`/clients/{id}/contacts`	Contatti del cliente
GET	`/clients/{id}/competitors`	Concorrenti del cliente
GET	`/clients/{id}/360`	Vista 360 completa

Audits

Metodo	Endpoint	Description
GET	`/audits`	Elencare gli audit
GET	`/audits/{id}`	Dettaglio di un audit
GET	`/audits/{id}/results`	Risultati di un audit
GET	`/audits/{id}/scores`	Punteggi di visibilità
POST	`/audits/launch`	Avviare un nuovo audit

Report

Metodo	Endpoint	Description
GET	`/reports`	Elencare i report
GET	`/reports/{id}`	Dettaglio di un report
GET	`/reports/{id}/download`	Scaricare il PDF

Piani d'azione

Metodo	Endpoint	Description
GET	`/action-plans`	Elencare i piani d'azione
GET	`/action-plans/{id}`	Dettaglio di un piano
GET	`/action-plans/{id}/progress`	Progressione del piano

Questionari

Metodo	Endpoint	Description
GET	`/questionnaires`	Elencare i questionari
GET	`/questionnaires/{id}/responses`	Risposte del questionario

Analytics

Metodo	Endpoint	Description
GET	`/analytics/portfolio`	Panoramica del portfolio
GET	`/analytics/leaderboard`	Classifica di visibilità
GET	`/analytics/scores/distribution`	Distribuzione dei punteggi

Modelli

Metodo	Endpoint	Description
GET	`/models`	Elencare i modelli IA disponibili
GET	`/models/{id}`	Dettaglio del modello e tariffe

Account

Metodo	Endpoint	Description
GET	`/account/profile`	Il tuo profilo
GET	`/account/credits`	Saldo crediti
GET	`/account/subscription`	Info abbonamento

Blog `?lang=`

Metodo	Endpoint	Description
GET	`/blog?lang=fr\|en\|es\|de`	Elencare gli articoli del blog (multilingue)
GET	`/blog/{slug}`	Dettaglio di un articolo

Glossario `?lang=`

Metodo	Endpoint	Description
GET	`/glossary?lang=fr\|en\|es\|de`	Elencare i termini del glossario (multilingue)
GET	`/glossary/{slug}`	Dettaglio di un termine

GEO Checklist & URL allucinati

Metodo	Endpoint	Description
GET	`/clients/{id}/geo-checklist`	Checklist di ottimizzazione GEO
GET	`/clients/{id}/hallucinated-urls`	URL allucinati rilevati dai modelli IA

Audit programmati

Metodo	Endpoint	Description
GET	`/scheduled-audits`	Elencare gli audit programmati
POST	`/scheduled-audits`	Creare un audit programmato
PUT	`/scheduled-audits/{id}`	Modificare un audit programmato
DELETE	`/scheduled-audits/{id}`	Eliminare un audit programmato

Documentazione completa

L'API documenta 16 schemi (Client, Audit, GeoChecklist, BlogArticle, GlossaryTerm, HallucinatedUrl, ecc.), gli header di rate limit e il supporto CORS. Consulta l'elenco completo dei 119 endpoint, parametri e schemi di risposta nella documentazione Swagger interattiva multilingue (/api/v1/docs?lang=fr|en|es|de).

Paginazione e filtri

Tutti gli endpoint di elenco supportano la paginazione tramite parametri di query:

Parametro	Predefinito	Description
`page`	`1`	Numero di pagina
`per_page`	`20`	Elementi per pagina (max 100)

Esempio con paginazione

CURL

curl -H "X-Api-Key: aila_your_key_here" \
     "https://ailabsaudit.com/api/v1/audits?page=2&per_page=10"

Oggetto paginazione nella risposta

JSON

{
    "pagination": {
        "page": 2,
        "per_page": 10,
        "total": 47,
        "total_pages": 5
    }
}

Errori e rate limiting

Codici di stato HTTP

Code	Significato
`200`	Successo
`400`	Richiesta non valida (parametri errati)
`401`	Non autorizzato (chiave API assente o non valida)
`403`	Vietato (permessi insufficienti)
`404`	Non trovato
`429`	Limite di richieste raggiunto
`500`	Errore del server

Formato di risposta in caso di errore

JSON

{
    "success": false,
    "error": {
        "code": 401,
        "message": "Invalid or missing API key"
    }
}

Rate limiting

L'API consente 60 richieste al minuto per chiave API. Gli header di risposta includono le informazioni sul limite:

HTTP HEADERS

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1709472000

Se raggiungi il limite

Quando ricevi una risposta 429, attendi il timestamp X-RateLimit-Reset prima di riprovare. Implementa un backoff esponenziale nel tuo codice per la produzione.

Esempi di codice

Ecco esempi completi per iniziare nel tuo linguaggio preferito:

import requests

API_KEY = "aila_your_key_here"
BASE_URL = "https://ailabsaudit.com/api/v1"

headers = {"X-Api-Key": API_KEY}

# List clients
response = requests.get(f"{BASE_URL}/clients", headers=headers)
clients = response.json()

for client in clients["data"]:
    print(f"{client['name']} — {client['sector']}")

    # Get audits for each client
    audits = requests.get(
        f"{BASE_URL}/audits",
        headers=headers,
        params={"client_id": client["id"], "per_page": 5}
    ).json()

    for audit in audits["data"]:
        print(f"  Audit #{audit['id']} — Score: {audit.get('score', 'N/A')}")

# Download a report as PDF
report_id = 1
r = requests.get(
    f"{BASE_URL}/reports/{report_id}/download",
    headers=headers
)
if r.status_code == 200:
    with open(f"report_{report_id}.pdf", "wb") as f:
        f.write(r.content)
    print(f"Report saved: report_{report_id}.pdf")

const API_KEY = "aila_your_key_here";
const BASE_URL = "https://ailabsaudit.com/api/v1";

const headers = { "X-Api-Key": API_KEY };

// List clients
async function getClients() {
    const response = await fetch(`${BASE_URL}/clients`, { headers });
    const { data, pagination } = await response.json();

    console.log(`${pagination.total} clients found`);
    data.forEach(client => {
        console.log(`${client.name} — ${client.sector}`);
    });

    return data;
}

// Get audit results
async function getAuditResults(auditId) {
    const response = await fetch(
        `${BASE_URL}/audits/${auditId}/results`,
        { headers }
    );
    return await response.json();
}

// Paginate through all audits
async function getAllAudits() {
    let page = 1;
    let allAudits = [];

    while (true) {
        const response = await fetch(
            `${BASE_URL}/audits?page=${page}&per_page=50`,
            { headers }
        );
        const { data, pagination } = await response.json();
        allAudits.push(...data);

        if (page >= pagination.total_pages) break;
        page++;
    }

    return allAudits;
}

getClients().then(console.log);

<?php
$apiKey = "aila_your_key_here";
$baseUrl = "https://ailabsaudit.com/api/v1";

function apiRequest($endpoint, $params = []) {
    global $apiKey, $baseUrl;

    $url = $baseUrl . $endpoint;
    if (!empty($params)) {
        $url .= "?" . http_build_query($params);
    }

    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ["X-Api-Key: $apiKey"],
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode !== 200) {
        throw new Exception("API error: HTTP $httpCode");
    }

    return json_decode($response, true);
}

// List clients
$clients = apiRequest("/clients");
foreach ($clients["data"] as $client) {
    echo "{$client['name']} — {$client['sector']}\n";
}

// Get audits with pagination
$audits = apiRequest("/audits", [
    "page" => 1,
    "per_page" => 10
]);
echo "Total audits: {$audits['pagination']['total']}\n";

// Get client 360 view
$client360 = apiRequest("/clients/42/360");
print_r($client360["data"]);

Risorse correlate

Glossario: API REST | GEO | AEO

Tutorial correlati: Portale cliente | Pagina vetrina | Audit programmati | Creazione cliente

Guida all'integrazione API REST GEO/AEO

Sommario

Prerequisiti

Un account Agente o Partner

Una chiave API REST

Un client HTTP

Ottenere la chiave API

Vai in API & Integrazioni

Creare una nuova chiave

Copiare e conservare in modo sicuro

Suggerimento

Autenticazione

Metodo 1: Header X-Api-Key

Metodo 2: Authorization Bearer

Sicurezza

Prima richiesta

Risposta riuscita (200 OK)

È tutto!

Endpoint

Clienti

Audits

Report

Piani d'azione

Questionari

Analytics

Modelli

Account

Blog `?lang=`

Glossario `?lang=`

GEO Checklist & URL allucinati

Audit programmati

Documentazione completa

Errori e rate limiting

Codici di stato HTTP

Formato di risposta in caso di errore

Rate limiting

Se raggiungi il limite

Esempi di codice

Pret a integrer l’API GEO/AEO ?

Pronto a verificare la tua visibilità AI?

Guida all'integrazione API REST GEO/AEO

Sommario

Prerequisiti

Un account Agente o Partner

Una chiave API REST

Un client HTTP

Ottenere la chiave API

Vai in API & Integrazioni

Creare una nuova chiave

Copiare e conservare in modo sicuro

Suggerimento

Autenticazione

Metodo 1: Header X-Api-Key

Metodo 2: Authorization Bearer

Sicurezza

Prima richiesta

Risposta riuscita (200 OK)

È tutto!

Endpoint

Clienti

Audits

Report

Piani d'azione

Questionari

Analytics

Modelli

Account

Blog ?lang=

Glossario ?lang=

GEO Checklist & URL allucinati

Audit programmati

Documentazione completa

Paginazione e filtri

Esempio con paginazione

Oggetto paginazione nella risposta

Errori e rate limiting

Codici di stato HTTP

Formato di risposta in caso di errore

Rate limiting

Se raggiungi il limite

Esempi di codice

Risorse correlate

Pret a integrer l’API GEO/AEO ?

Pronto a verificare la tua visibilità AI?

Blog `?lang=`

Glossario `?lang=`