API REST

Autenticazione

L’API REST dà a script e dashboard gli stessi dati dell’app. Uno script la raggiunge con una chiave API dello spazio di lavoro inviata come bearer token. Questa pagina copre le chiavi, i loro livelli di accesso e gli errori che puoi ricevere.

Indirizzo di base e formato

https://teddit.io/api

Richieste e risposte sono JSON. Invia Content-Type: application/json con ogni body. Il body di una richiesta può arrivare a 4 MB.
Gli id sono numeri. L’API chiama uno spazio di lavoro organizzazione (/orgs/:orgId) e un sito project (/projects/:id).
Gli orari sono ISO 8601 in UTC. Settimane e altri periodi sono indicati come data, YYYY-MM-DD.

L’elenco degli indirizzi è nella pagina Endpoint.

Chiavi API

Crea una chiave nell’app: icona dell’ingranaggio → API e MCP → Crea chiave. Qualsiasi ruolo può farlo; la chiave ottiene al massimo l’accesso del tuo.

Una chiave ha la forma tdt_ seguito da 40 lettere, cifre, - e _.
Viene mostrata una sola volta, quando viene creata. Teddit ne conserva un hash, non la chiave, quindi una chiave persa non può essere recuperata. Creane una nuova.
Una chiave appartiene a un solo spazio di lavoro e può raggiungere ogni sito al suo interno.
L’elenco Chiavi mostra per ogni chiave il nome, i primi caratteri, l’accesso, chi l’ha creata e quando è stata usata l’ultima volta. “Ultimo uso” viene aggiornato al massimo una volta ogni cinque minuti.
Una chiave non scade. Revocala con l’icona del cestino; smette di funzionare dalla richiesta successiva.

Le stesse chiavi aprono il server MCP.

Inviare la chiave

Metti la chiave nell’header Authorization di ogni richiesta:

curl https://teddit.io/api/whoami \
  -H "Authorization: Bearer tdt_…"

GET /api/whoami è la chiamata da cui partire. Dice a quale spazio di lavoro appartiene la chiave e cosa può fare:

{
  "kind": "token",
  "tokenName": "Reporting script",
  "user": { "id": 7, "name": "Dana Whitfield", "email": "dana@brightloop.example" },
  "org": { "id": 3, "name": "Brightloop", "plan": "free" },
  "role": "viewer"
}

Usa org.id negli indirizzi /orgs/:orgId/…. user è la persona che ha creato la chiave: le azioni compiute con la chiave, come avviare una scansione, sono registrate a quel nome.

La chiave è l’intera credenziale. Tienila fuori da pagine web, repository e messaggi di chat, e dai a ogni script la propria chiave, così da poterne revocare una senza fermare le altre.

Livelli di accesso delle chiavi

Una chiave ha uno di tre livelli di accesso. Ciascuno è un ruolo dello spazio di lavoro, e ciascuno include quello sopra di sé.

Accesso nell’app	`role`	Può chiamare
Lettura	`viewer`	Tutto ciò che legge: report, prompt, risposte, concorrenti, pagine, scansioni, membri. Anche la stima del costo di una scansione.
Lettura + modifica	`member`	In più: creare, modificare ed eliminare prompt, categorie e concorrenti; importare; cambiare i nomi, la lingua e il paese di un sito.
Lettura + scansione	`admin`	In più: avviare e annullare scansioni, attivare e disattivare il calendario, cambiare il tetto mensile e le impostazioni di scansione, aggiungere siti, invitare e rimuovere membri.

Non esistono chiavi con il ruolo Owner. Ricaricare, eliminare un sito e rinominare uno spazio di lavoro restano a un Owner autenticato.
Non puoi creare una chiave con più accesso di quanto ti dia il tuo ruolo.
Una chiave segue la persona che l’ha creata: abbassata con il suo ruolo, fermata quando lascia lo spazio di lavoro.

Cosa una chiave non può fare

Alcune azioni richiedono una persona autenticata nell’app in un browser. Chiamate con una chiave, rispondono 403 con “This action needs a signed-in person, not an API token.”

Creare, elencare e revocare chiavi API.
Cambiare nome, email o password, ed eliminare l’account.
Creare uno spazio di lavoro, eliminarne uno, passare da uno spazio all’altro e lasciarne uno.
Accettare un invito.

Una chiave inoltre non vede nulla fuori dal suo spazio di lavoro. L’id di un sito o di uno spazio che appartiene a qualcun altro risponde 404, come un id che non esiste.

Errori

Ogni errore ha lo stesso body: un messaggio per una persona in error, e fields con un messaggio per campo quando il problema è nell’input, altrimenti null.

HTTP/1.1 409 Conflict

{
  "error": "This prompt already exists in the project.",
  "fields": { "text": "Already tracked" }
}

Stato	Quando
400	La richiesta è ben formata ma rifiutata: un limite dello spazio di lavoro è raggiunto, una scansione non può partire (un’altra è in corso, nessun prompt attivo, il credito non la copre, il tetto mensile è esaurito), o un indirizzo non è un dominio. Il messaggio dice quale.
401	Nessuna chiave, una chiave nella forma sbagliata, o una chiave revocata. Il messaggio è “Sign in to continue.”
403	Il livello di accesso della chiave è troppo basso per l’azione, oppure l’azione richiede una persona autenticata.
404	L’indirizzo o l’id non esiste, oppure appartiene a un altro spazio di lavoro.
409	Un duplicato: un prompt con lo stesso testo, un concorrente o una categoria con lo stesso nome, un invito per qualcuno che è già membro.
422	Il body o la query string non hanno superato la validazione. `fields` indica ogni campo sbagliato.
429	Troppe richieste a un indirizzo con un proprio limite, come l’accesso, gli inviti o la lettura della sitemap. Aspetta e riprova.
500, 502	Qualcosa è fallito da parte nostra, oppure un assistente è fallito mentre la richiesta veniva gestita.

Le chiamate riuscite rispondono 200 con JSON. Eliminare un sito, un membro o un invito risponde 204 senza body.

Limiti di frequenza e dello spazio di lavoro

La maggior parte delle richieste fatte con una chiave non ha un limite di frequenza. Alcune azioni ne hanno uno proprio: invitare persone, rileggere la sitemap e riscrivere le query. Superarlo risponde 429.
I limiti dello spazio di lavoro valgono per l’API esattamente come nell’app: siti, prompt per sito, scansioni al mese e membri. Una chiamata che supererebbe un limite risponde 400 con il limite nel messaggio.
Gli indirizzi degli elenchi sono paginati. L’elenco dei prompt accetta page e perPage (da 5 a 200); chiedere di più risponde 422.

Precedente‹ Domande di esempio SuccessivoEndpoint ›