Usa la REST API di Clevera

La REST API di Clevera consente ai tuoi script e servizi di eseguire ciò che un agente può fare tramite MCP: leggere la tua libreria, richiedere video e articoli, esportare video, lavorare su siti di documentazione e seguire i lavori. Questo articolo copre l'URL di base, l'autenticazione, il flusso di richiesta per il lavoro a pagamento, gli errori e i limiti di frequenza.

Nozioni di base#

Verifica un token con GET /docs/me:

curl -H "Authorization: Bearer $CLEVERA_TOKEN" \
     -H "Accept: application/json" \
     https://app.clevera.ai/api/v1/docs/me

La risposta indica per conto di chi agisce il token: nome e scadenza del token, la persona e il suo ruolo attuale, l'area di lavoro, i siti inclusi nell'ambito e i permessi attualmente attivi (i permessi del token ridotti al ruolo attuale della persona). Chiamalo per primo quando una chiamata viene rifiutata.

Endpoint#

Ogni endpoint richiede il permesso mostrato. Chiamarne uno senza di esso restituisce 403 forbidden_ability. Vedi Permessi dell'agente.

Libreria e materiali#

Video e articoli#

Lavori e crediti#

Siti di documentazione#

Altro su agenti e siti di documentazione: Connetti agenti AI ai tuoi siti di documentazione.

Richiedi lavoro a pagamento#

Il lavoro che costa crediti prevede sempre prima un preventivo, poi l'avvio:

1. Preventivalo. POST /videos/quotes (o /clips/quotes) con ciò che desideri. La risposta contiene un quote_id e l'intervallo di crediti. Un preventivo è valido per 15 minuti e può essere utilizzato una volta.
2. Facoltativamente, esegui una prova. Invia l'avvio con "dry_run": true per sapere se verrebbe avviato, se necessita di approvazione o se verrebbe bloccato. Non viene scritto nulla.
3. Avvialo. POST /videos con quote_id e un'intestazione Idempotency-Key. La risposta è 202 con un lavoro.
4. Seguilo. GET /jobs/{job}/wait finché lo status del lavoro non cambia, oppure ascolta i webhook.

curl -X POST https://app.clevera.ai/api/v1/videos/quotes \
  -H "Authorization: Bearer $CLEVERA_TOKEN" -H "Content-Type: application/json" \
  -d '{"type": "how_to", "recording_id": "<recording id>", "language": "en-US"}'

curl -X POST https://app.clevera.ai/api/v1/videos \
  -H "Authorization: Bearer $CLEVERA_TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f6c1a2e-8d4b-4f7a-9c1e-2b5d7e9f0a13" \
  -d '{"quote_id": "<quote id>"}'

Stati del lavoro:

Se un avvio viene eseguito immediatamente o attende una persona dipende dai limiti di spesa del token e dalla sua impostazione Approva automaticamente sotto. Vedi Controlla la spesa e le approvazioni dell'agente.

Riprova e idempotenza#

Invia un'intestazione Idempotency-Key (un UUID nuovo per ogni azione) a ogni creazione e avvio. Se la rete cade e riprovi con la stessa chiave e lo stesso corpo, riceverai la prima risposta invece di un secondo video. Le chiavi vengono memorizzate per 24 ore.

Errori#

Ogni errore ha la stessa forma, con un messaggio che indica cosa fare dopo:

{
  "error": {
    "code": "forbidden_ability",
    "message": "This token lacks the videos:create ability. Ask the workspace member who owns it for a token that has it.",
    "details": { "ability": "videos:create" }
  },
  "request_id": "req_example"
}

Includi il request_id quando contatti l'assistenza.

Ogni messaggio, con la soluzione: Correggi gli errori dell'agente e dell'API.

Limiti di frequenza#

Una risposta 429 ha un'intestazione Retry-After e retry_after (secondi) nel corpo. Attendi quel tempo prima di riprovare. Letture, preventivi e controlli di stato non costano crediti.

Correlati#