De Clevera REST API gebruiken

Met de REST API van Clevera kunnen je eigen scripts en services doen wat een agent via MCP kan: je bibliotheek lezen, video's en artikelen aanvragen, video's exporteren, aan documentatiesites werken en taken volgen. Dit artikel behandelt de basis-URL, authenticatie, de aanvraagflow voor betaald werk, fouten en snelheidslimieten.

Basisprincipes#

Controleer een token met GET /docs/me:

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

Het antwoord geeft aan namens wie het token handelt: de naam en verloopdatum van het token, de persoon en hun huidige rol, de werkruimte, de sites in scope en de machtigingen die op dit moment werken (de machtigingen van het token ingeperkt tot de huidige rol van de persoon). Roep dit aan als een aanroep wordt geweigerd.

Eindpunten#

Elk eindpunt heeft de getoonde machtiging nodig. Een aanroep zonder deze machtiging geeft 403 forbidden_ability terug. Zie Agent-machtigingen.

Bibliotheek en materiaal#

Video's en artikelen#

Taken en credits#

Documentatiesites#

Meer over agents en documentatiesites: Verbind AI-agents met je documentatiesites.

Betaald werk aanvragen#

Werk dat credits kost, verloopt altijd eerst via een offerte, en dan starten:

1. Vraag een offerte aan. POST /videos/quotes (of /clips/quotes) met wat je wilt. Het antwoord bevat een quote_id en het creditbereik. Een offerte is 15 minuten geldig en kan eenmaal worden gebruikt.
2. Test het eventueel (dry-run). Stuur de start met "dry_run": true om te zien of het zou starten, goedkeuring nodig heeft of wordt geblokkeerd. Er wordt niets geschreven.
3. Start het. POST /videos met quote_id en een Idempotency-Key-header. Het antwoord is 202 met een taak.
4. Volg het. GET /jobs/{job}/wait totdat de status van de taak verandert, of luister naar webhooks.

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>"}'

Taakstatussen:

Of een start direct draait of wacht op een persoon, hangt af van de bestedingslimieten van het token en de instelling Automatisch goedkeuren hieronder. Zie Agent-uitgaven en goedkeuringen beheren.

Opnieuw proberen en idempotentie#

Stuur een Idempotency-Key-header (een verse UUID per actie) bij elke aanmaak en start. Als het netwerk wegvalt en je probeert het opnieuw met dezelfde sleutel en body, krijg je het eerste antwoord terug in plaats van een tweede video. Sleutels worden 24 uur onthouden.

Fouten#

Elke fout heeft dezelfde vorm, met een bericht dat aangeeft wat je vervolgens moet doen:

{
  "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"
}

Vermeld de request_id wanneer je contact opneemt met de ondersteuning.

Elk bericht, met de oplossing: Agent- en API-fouten oplossen.

Snelheidslimieten#

Een 429-antwoord bevat een Retry-After-header en retry_after (seconden) in de body. Wacht zo lang voordat je het opnieuw probeert. Lezen, offertes en statuscontroles kosten geen credits.

Gerelateerd#