API e MCP

Usa Point11 dal tuo software, dal tuo assistente IA o dal terminale.

Panoramica#

Il server MCP, l’API e lo strumento a riga di comando fanno quello che fai nella dashboard: leggono le tue campagne e i risultati e avviano lo stesso lavoro.

  • Server MCP: collega Claude, ChatGPT o un altro assistente IA.
  • API: chiama Point11 dal tuo codice all’indirizzo https://point11.ai/api/v1.
  • CLI: usa l’API dal terminale.

Accedi per aprire il riferimento dell’API; è disponibile per i membri di un’organizzazione Point11. Elenca ogni richiesta, cosa accetta e cosa restituisce, e quali azioni della dashboard raggiungono il server MCP, l’API e la CLI. Per testare annunci e altre creatività con i gemelli digitali dei tuoi clienti, vedi Testa le creatività con l’API.

Collega un assistente IA#

Usa questo URL del server MCP: https://point11.ai/api/mcp. Accedi a Point11 e approva l’accesso quando richiesto. Se fai parte di più organizzazioni, indica al tuo assistente quale usare. Per collegarti invece con una chiave API, segui i passaggi per il tuo client qui sotto.

Per dare al tuo assistente solo i prodotti che usi, collegati con una chiave API e aggiungi i loro nomi all’URL in minuscolo, separati da virgole, per esempio https://point11.ai/api/mcp?products=discovery,inspector. Un elenco di strumenti più breve lascia al tuo assistente più spazio per lavorare. Per accedere a Point11, usa esattamente l’URL indicato sopra, senza nulla dopo /api/mcp. Point11 elenca solo la versione attuale di ogni strumento; un assistente che usa ancora una versione precedente continua a funzionare.

Business e Alpha hanno il maggior numero di strumenti, quindi puoi anche aggiungere solo una parte di uno dei due: il prodotto, un punto e la parte, per esempio business.customers. Business comprende profiles, customers, crm, goals, products, measurement e google-ads. Alpha comprende chat, projects, files, workflows, ads, brand-kits, advisor e connectors. Combina prodotti e parti come preferisci, per esempio https://point11.ai/api/mcp?products=discovery,business.customers. Se il tuo assistente cerca gli strumenti quando gli servono, può comunque usare un prodotto intero o l’intero server.

I registri e i client possono leggere la descrizione del server all’indirizzo https://point11.ai/api/mcp/server-card.

Claude sul web e su desktop#

  1. Apri Customize > Connectors, poi + > Add custom connector.
  2. Assegna il nome Point11, inserisci esattamente https://point11.ai/api/mcp e seleziona Add, poi Connect.
  3. In una conversazione, apri + > Connectors e abilita Point11.

Per i piani Team ed Enterprise, un proprietario deve prima aggiungere il connettore in Organization settings > Connectors. Consulta la guida ai connettori di Claude.

Claude Code#

Esegui nel terminale:

bash
claude mcp add --transport http point11 https://point11.ai/api/mcp

Poi apri Claude Code, esegui /mcp e seleziona Point11 per autenticarti. Per usare invece una chiave API, aggiungila come intestazione:

bash
claude mcp add --transport http point11 https://point11.ai/api/mcp \
  --header "Authorization: Bearer $POINT11_API_KEY"

Consulta la guida MCP di Claude Code.

ChatGPT sul web#

  1. Apri Settings > Security and login e abilita Developer mode.
  2. Apri Plugins > +. Inserisci Point11, una breve descrizione e l’URL del server in Connection, poi crea la connessione.
  3. Controlla gli strumenti, avvia una nuova conversazione e seleziona Point11 dal menu degli strumenti.

La disponibilità dipende dalle impostazioni del tuo account e dello spazio di lavoro. Consulta la guida alla connessione di OpenAI.

ChatGPT desktop e Codex#

Nell’app desktop, apri Settings > MCP servers > Add server. Assegna il nome Point11, scegli Streamable HTTP e inserisci l’URL del server. Salva, seleziona Restart, poi Authenticate.

Per la CLI Codex, esegui:

bash
codex mcp add point11 --url https://point11.ai/api/mcp
codex mcp login point11

Per usare invece una chiave API, indica la variabile d’ambiente che la contiene:

bash
codex mcp add point11 --url https://point11.ai/api/mcp --bearer-token-env-var POINT11_API_KEY

I client desktop, CLI e IDE condividono la configurazione sul tuo computer. Consulta la guida MCP di OpenAI.

Visualizza la dashboard nel tuo assistente#

Chiedi una vista della dashboard di Discovery, come Quota del brand, Tasso di vittoria del brand o Concorrenti. Un assistente che mostra app interattive visualizza la stessa scheda che vedi nella tua dashboard, con un link per aprirla in Point11. Gli altri assistenti ricevono un breve riepilogo degli stessi numeri e il link.

Accedi o usa una chiave API#

  • Accedi con il tuo account. Point11 ti chiede di approvare l’accesso, poi il tuo assistente o strumento agisce con il tuo ruolo in ogni organizzazione di cui fai parte. Usa questa opzione per gli assistenti IA e il tuo lavoro.
  • Usa una chiave API per il software che funziona senza di te, come uno script o un’attività pianificata. Una chiave agisce per una sola organizzazione e può usare solo l’accesso che le concedi.

Alcune cose richiedono sempre il tuo intervento. Le tue conversazioni e i tuoi progetti Alpha, i commenti e le bozze degli studi Research appartengono a una persona, quindi una chiave API non può raggiungerli. Mettere in pausa o eliminare una campagna, invitare qualcuno o rimuovere un membro richiede prima la tua approvazione. Vedi l’organizzazione ed esattamente cosa cambierà, e la tua approvazione vale solo per quella richiesta. Fatturazione, chiavi API e ruoli dei membri si modificano solo nella dashboard.

Il lavoro che avvii dal server MCP, dall’API o dalla CLI viene conteggiato nel tuo piano come nella dashboard.

Scegli cosa può fare ogni assistente#

Ogni assistente IA o app che ha agito per tuo conto è elencato in Impostazioni > Sicurezza, sotto App collegate. Scegli cosa può fare ciascuno in quell’organizzazione: Completo, Sola lettura o Bloccato. Proprietari e amministratori scelgono anche cosa possono fare gli assistenti dei membri in tutta l’organizzazione, in Impostazioni > Sicurezza > Organizzazione sotto Client IA (MCP): Consentito, Sola lettura o Disattivato, e revocano l’app di un membro in App collegate dei membri. Una modifica si applica dalla richiesta successiva e le chiavi API non sono interessate.

Crea una chiave API#

Amministratori e proprietari possono creare chiavi.

  1. Apri Impostazioni > Chiavi API e seleziona Crea chiave.
  2. Inserisci un Nome, scegli il suo Accesso per ogni prodotto, quando scade in Scadenza e a chi appartiene in Appartiene a.
  3. Seleziona Crea, poi copia la chiave. La vedi una sola volta.

Conserva la chiave in un gestore di segreti, mai nel codice. Un’organizzazione può avere fino a 10 chiavi attive. Per disattivare una chiave, seleziona Revoca; Ruota le assegna un nuovo segreto. Una chiave che appartiene a Me viene revocata quando lasci l’organizzazione o non puoi più gestire le chiavi; una che appartiene a L’organizzazione continua a funzionare.

Invia la tua prima richiesta#

Invia la chiave come token bearer:

bash
curl https://point11.ai/api/v1/discovery/campaigns \
  -H "Authorization: Bearer $POINT11_API_KEY"

Le richieste di lettura usano GET. Le richieste che modificano qualcosa usano POST con un corpo JSON e un’intestazione Idempotency-Key che contiene un nuovo UUID:

bash
curl https://point11.ai/api/v1/inspector/scans/start \
  -H "Authorization: Bearer $POINT11_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

Se accedi invece di usare una chiave, invia anche Point11-Organization con l’ID della tua organizzazione. Copialo da Impostazioni > Chiavi API.

Gestisci le risposte#

  • Nuovi tentativi. Per ripetere una richiesta in sicurezza, inviala di nuovo con la stessa Idempotency-Key. Ripetere una creazione o un avvio restituisce la sua prima risposta e nulla viene eseguito due volte. Qualsiasi altra modifica ripetuta viene eseguita di nuovo e risponde con lo stato in cui lascia le cose, quindi un'eliminazione ripetuta che risponde 404 significa che l'elemento non esiste più. Usa una nuova chiave per ogni nuova richiesta. Tramite il server MCP, il tuo assistente invia la chiave come idempotencyKey. È obbligatoria per creare o avviare qualcosa; per qualsiasi altra modifica è facoltativa, e una richiesta senza chiave viene eseguita come una nuova richiesta.
  • Elenchi. Passa limit, fino a 100. Per ottenere la pagina successiva, passa il nextCursor della risposta precedente come cursor. nextCursor è null nell’ultima pagina.
  • Lavori più lunghi. L’avvio di una scansione o di una campagna risponde subito 202 con un runId. Controlla l’avanzamento con GET /api/v1/platform/runs-v2/{runId} o con platform_runs_get_v2 nel server MCP.
  • Errori. Ogni errore ha un code, un message e un request_id. Decidi cosa fare in base al code e includi il request_id quando chiedi aiuto.
  • Limiti. Ogni chiave ha un budget di richieste, e lo stesso vale per ogni persona che accede, su tutte le organizzazioni e tutti gli assistenti che usa. Le intestazioni RateLimit-Remaining e RateLimit-Reset mostrano quanto resta. Quando si esaurisce, ricevi 429; attendi i secondi indicati da Retry-After, poi riprova.

Usa la CLI#

La CLI è Restish, che legge il riferimento API e trasforma ogni richiesta in un comando con lo stesso nome, come discovery-campaigns-list. Usa una chiave API. Installa Restish, ad esempio con brew install restish, salva la tua chiave in POINT11_API_KEY, poi collega Restish a Point11:

bash
restish api connect p11 https://point11.ai --no-discover
restish api set p11 'profiles.default.auth: {type: bearer, params: {token: env:POINT11_API_KEY}}'
restish api set p11 'profiles.default.credentials.apiKey.auth: {type: bearer, params: {token: env:POINT11_API_KEY}}'
restish api sync p11

Poi esegui qualsiasi richiesta con il nome del suo comando:

bash
restish p11 discovery-campaigns-list

Per una richiesta che modifica qualcosa, metti prima l’Idempotency-Key:

bash
restish p11 inspector-scans-start "$(uuidgen)" url: https://example.com

Esegui di nuovo restish api sync p11 per ottenere le nuove richieste.