Usa la API REST de Clevera

La API REST de Clevera permite que tus propios scripts y servicios hagan lo que un agente puede hacer a través de MCP: leer tu biblioteca, solicitar videos y artículos, exportar videos, trabajar en sitios de documentación y seguir los trabajos. Este artículo cubre la URL base, la autenticación, el flujo de solicitud para trabajos de pago, los errores y los límites de tasa.

Conceptos básicos#

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 respuesta indica quién actúa con el token: el nombre y la fecha de caducidad del token, la persona y su rol actual, el espacio de trabajo, los sitios incluidos en el alcance y los permisos que funcionan en este momento (los permisos del token recortados al rol actual de la persona). Llama a esto primero cuando se rechace una llamada.

Endpoints#

Cada endpoint necesita el permiso mostrado. Llamar a uno sin él devuelve 403 forbidden_ability. Consulta Permisos del agente.

Biblioteca y materiales#

Videos y artículos#

Trabajos y créditos#

Sitios de documentación#

Más sobre agentes y sitios de documentación: Conectar agentes de IA a tus sitios de documentación.

Solicitar trabajo de pago#

El trabajo que cuesta créditos siempre requiere cotizar primero y luego iniciar:

1. Cotízalo. POST /videos/quotes (o /clips/quotes) con lo que deseas. La respuesta tiene un quote_id y el rango de créditos. Una cotización es válida por 15 minutos y se puede usar una vez.
2. Opcionalmente, haz una prueba. Envía el inicio con "dry_run": true para saber si comenzaría, si necesita aprobación o si está bloqueado. No se escribe nada.
3. Inícialo. POST /videos con quote_id y un encabezado Idempotency-Key. La respuesta es 202 con un trabajo.
4. Síguelo. GET /jobs/{job}/wait hasta que el status del trabajo cambie, o escucha los 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>"}'

Estados del trabajo:

Si un inicio se ejecuta de inmediato o espera a una persona depende de los límites de gasto del token y su configuración de Aprobar automáticamente por debajo de. Consulta Controlar el gasto y las aprobaciones del agente.

Reintentos e idempotencia#

Envía un encabezado Idempotency-Key (un UUID nuevo por acción) en cada creación e inicio. Si la red se cae y reintentas con la misma clave y cuerpo, obtienes la primera respuesta en lugar de un segundo video. Las claves se recuerdan durante 24 horas.

Errores#

Cada error tiene la misma forma, con un mensaje que indica qué hacer a continuación:

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

Incluye el request_id cuando contactes a soporte.

Cada mensaje, con la solución: Corregir errores del agente y de la API.

Límites de tasa#

Una respuesta 429 tiene un encabezado Retry-After y retry_after (segundos) en el cuerpo. Espera ese tiempo antes de reintentar. Las lecturas, cotizaciones y comprobaciones de estado no cuestan créditos.

Relacionado#