Endpoint

Convenzioni

Tutti i percorsi sono relativi a https://teddit.io/api. Invia la chiave come descritto sotto Autenticazione.

• Accesso è il ruolo minimo della chiave che può chiamare l’endpoint: viewer (una chiave Lettura), member (Lettura + modifica) o admin (Lettura + scansione). Un ruolo superiore può sempre chiamarlo a sua volta.
• :orgId è l’id dello spazio di lavoro da GET /whoami. :id è l’id di un sito da GET /orgs/:orgId/projects.
• Parametri di periodo. Gli endpoint dei report accettano period (day, week, month o quarter; predefinito week) e start (una data qualsiasi dentro il periodo che vuoi, YYYY-MM-DD; predefinito l’ultimo periodo). Le loro risposte ripetono period e start ed elencano in periods ogni periodo che ha dati.
• Nelle risposte, “citato” è mentioned, “linkato” è ownCited, la tua posizione è brandRank, visibility è il punteggio di visibilità, e un assistente è un provider con la chiave openai, anthropic, perplexity, gemini, google_aio o google_ai_mode.

Gli strumenti MCP restituiscono gli stessi dati, quindi la descrizione di uno strumento descrive anche l’endpoint corrispondente.

Spazio di lavoro

Aggiungere un sito accetta name e url (entrambi obbligatori), e facoltativamente industry, brandTerms (altri nomi, fino a 50), competitors (oggetti con name e domain, fino a 50), language (predefinito English) e location (predefinito United States).

Invitare accetta email e role (viewer, member o admin; predefinito member). Cambiare un ruolo accetta role. Cosa un admin può e non può fare agli altri membri è nella pagina Ruoli.

Non disponibile alle chiavi: tutto ciò che sta sotto /auth e /account, creare, eliminare e lasciare spazi di lavoro, rinominare uno spazio di lavoro (PATCH /orgs/:orgId, solo Owner), ricariche e fatture (solo Owner) e la gestione delle chiavi (/orgs/:orgId/tokens).

Siti

Cambiare le impostazioni accetta uno qualsiasi di questi campi:

• name, brandTerms: il nome del brand e i suoi altri nomi. Cambiare l’uno o l’altro rilegge tutte le risposte conservate; la risposta porta allora un riepilogo reanalysis.
• industry, language, location (il paese).
• scanFrequencyDays (da 1 a 365): l’intervallo tra le scansioni programmate.
• monthlyCapUsd: il tetto mensile del sito in dollari USA. null o 0 lo rimuove.
• scanSettings: le impostazioni di scansione salvate, sostituite per intero. Un oggetto con providers (chiavi degli assistenti; omesso significa tutti quelli collegati), models (da chiave dell’assistente a modello), category, budgetUsd (il massimo che una scansione può costare; 0 significa il doppio della sua stima) e skipAtCap (false lascia partire le scansioni anche quando il tetto mensile è esaurito).

Calendario accetta enabled (true o false). Attivare il calendario fissa la prima scansione per la notte successiva (UTC); le risposte di una scansione programmata arrivano entro qualche ora.

Eliminare un sito, con i suoi prompt, scansioni e risposte, spetta a un Owner autenticato e non è disponibile alle chiavi.

Buyer persona

GET /projects/:id/personas elenca le persona di un sito con quanti prompt chiedono nei panni di ciascuna; POST (member) ne aggiunge una con name (fino a 80 caratteri) e context (fino a 600): chi chiede, con le sue parole. PATCH /projects/:id/personas/:personaId cambia l’uno o l’altro; DELETE ne rimuove una, e i suoi prompt vengono posti senza persona dalla scansione successiva. I prompt accettano personaId in creazione, modifica e modifica in blocco (null lo azzera). Ogni risposta conserva le parole con cui è stata posta come context.

Report

Sono tutti GET, richiedono viewer, e accettano i parametri di periodo.

curl "https://teddit.io/api/projects/12/report?period=month&start=2026-09-15" \
  -H "Authorization: Bearer tdt_…"

Come vengono calcolati i numeri in queste risposte: Metriche e stati.

Prompt e categorie

L’elenco e l’esportazione accettano gli stessi parametri di query: q (ricerca testuale), category, status (draft, active, paused), intent, verdict (named, lost, cited, missing, failed), competitor (il nome di un concorrente tracciato), stability (held, volatile, lost) e scanned (yes, never). L’elenco accetta anche sort (created, text, category, rank, scanned), dir (asc, desc), page, perPage (da 5 a 200, predefinito 20) e i parametri di periodo, che stabiliscono cosa rappresenta un quadratino dello storico.

Aggiungere accetta text (da 3 a 500 caratteri, obbligatorio), category o categories (un elenco di fino a 8), intent (predefinito informational), funnel (predefinito awareness) e status (predefinito active). Un testo già tracciato risponde 409. Modificare accetta gli stessi campi, tutti facoltativi; categories sostituisce l’intero elenco.

In blocco accetta ids (da 1 a 5000) e status, category o delete: true. Eliminare un prompt elimina le sue risposte.

Importare accetta contents (il testo del file, fino a 2.000.000 di caratteri), status (predefinito draft) e dryRun. Restituisce rows, created, updated, skipped e categories. Il formato del file è nella pagina Importare i prompt.

Una risposta accetta engine (la chiave di un assistente; predefinito il primo assistente che ha risposto) o r (l’id di una risposta passata, preso dai results del prompt).

Unire categorie accetta names (le categorie da accorpare) e into (il nome che assumono). Un nome è una rinomina, più nomi sono un’unione, e un into vuoto rimuove le categorie dai loro prompt.

Concorrenti e pagine

Tracciare accetta name (obbligatorio), domain, aliases (altri nomi, fino a 30), color e logo. Modificare accetta gli stessi campi, tutti facoltativi: cambia solo ciò che invii, aliases sostituisce l’intero elenco, e domain: null rimuove il dominio. Tutti e tre gli endpoint dei concorrenti rileggono le risposte conservate quando i nomi cambiano e restituiscono il risultato come reanalysis.

Pagine accetta q, section (la prima parte del percorso), shown (yes o no), page e perPage (da 5 a 200, predefinito 50).

Scansioni

Stima e avvio accettano lo stesso body. Ogni campo è facoltativo:

• providers: chiavi degli assistenti. Vuoto significa ogni assistente collegato.
• promptIds: un insieme scelto di prompt. Vuoto significa ogni prompt attivo. I prompt non attivi vengono saltati.
• category: scansiona una categoria.
• sample: scansiona questo numero di prompt, estratti a caso.
• models: da chiave dell’assistente a modello, tra le opzioni in scan-options. chatgpt-app e gemini-app (veloci: risposta subito) e chatgpt-app-queue e gemini-app-queue (lenti e più economici: qualche minuto) prendono la risposta come la mostra l’app.
• saved: true prende gli assistenti, i modelli e la categoria dalle impostazioni di scansione salvate del sito invece che da questa richiesta. All’avvio prende anche il limite per scansione salvato.
• Solo all’avvio: budgetUsd (fermati quando la scansione ha raggiunto questo costo; omesso, il doppio della sua stima) e label.

La stima restituisce prompts, answers, cost e formatted. L’avvio restituisce la scansione, risponde 402 quando il credito non copre la scansione, e 400 con il motivo per qualsiasi altra cosa le impedisca di partire. I motivi, e come viene contato il costo, sono nella pagina Credito e limiti di spesa.

Una scansione accetta tab (all, notNamed, competitorsOnly, errors), engine (la chiave di un assistente) e page. Gli stati di una scansione sono queued, running, cancelling, cancelled, done e failed.

Un esempio completo

Trova il sito, aggiungi un prompt, stima una scansione di una categoria, avviala e leggi il risultato. Avviare la scansione richiede una chiave Lettura + scansione.

KEY="tdt_…"
API="https://teddit.io/api"

# 1. Which workspace is this key for?
curl "$API/whoami" -H "Authorization: Bearer $KEY"
#    → "org": { "id": 3, … }

# 2. The sites of the workspace
curl "$API/orgs/3/projects" -H "Authorization: Bearer $KEY"
#    → "projects": [{ "id": 12, "domain": "brightloop.example", … }]

# 3. Add a prompt
curl -X POST "$API/projects/12/prompts" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"text": "What does email automation cost for 10,000 contacts?", "category": "pricing", "intent": "commercial"}'

# 4. What would a scan of that category cost?
curl -X POST "$API/projects/12/scans/estimate" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"category": "pricing"}'
#    → { "prompts": …, "answers": …, "cost": …, "formatted": "$…" }

# 5. Run it, and stop at 2 dollars
curl -X POST "$API/projects/12/scans" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"category": "pricing", "budgetUsd": 2}'

# 6. Follow it until "run" is null
curl "$API/projects/12/scans/live" -H "Authorization: Bearer $KEY"

# 7. Read this week's report
curl "$API/projects/12/report" -H "Authorization: Bearer $KEY"