API REST
Autentica con claves de API, consulta los endpoints de Clautia y gestiona confirmaciones. Revisa ejemplos, errores y límites de uso.
URL base: https://app.clautia.com/api/v1
OpenAPI: https://app.clautia.com/api/v1/openapi.json
Autenticación
Usa una clave bearer en cada petición:
curl https://app.clautia.com/api/v1/whoami \
-H "Authorization: Bearer $CLAUTIA_API_KEY"
whoami devuelve la organización de la clave y sus scopes.
Endpoints, scopes y clase
Clase: R = lectura, W = escritura, D = destructiva (pide token de confirmación).
| Método | Ruta | Scope(s) | Clase |
|---|---|---|---|
| GET | /whoami | clave requerida | R |
| GET | /brands | brands:read | R |
| GET | /accounts | brands:read | R |
| GET | /posts | posts:read | R |
| GET | /posts/{postId} | posts:read | R |
| POST | /posts | posts:write | W |
| POST | /posts/{postId}/schedule | posts:write | W* |
| POST | /posts/{postId}/publish | posts:write | D |
| POST | /posts/{postId}/cancel | posts:write | D |
| POST | /ai/draft | ai:write | W |
| POST | /ai/adapt | ai:write | W |
* posts_schedule pide confirmación si programas con menos de 10 minutos.
Los endpoints de redacción y adaptación con IA admiten 8 redes: Instagram, Facebook, TikTok, X, LinkedIn, YouTube, Threads y Google Business Profile (Perfil de Empresa de Google). No admiten Bluesky ni Telegram.
Ejemplos
Crear un borrador:
curl -X POST https://app.clautia.com/api/v1/posts \
-H "Authorization: Bearer $CLAUTIA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"brandId": "BRAND_ID",
"socialAccountIds": ["ACCOUNT_ID"],
"textDefault": "Hola desde Clautia",
"idempotencyKey": "docs-post-001"
}'
Programar un post:
curl -X POST https://app.clautia.com/api/v1/posts/POST_ID/schedule \
-H "Authorization: Bearer $CLAUTIA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"scheduledAt":"2026-12-01T10:00:00Z"}'
Publicar ahora (confirmación en dos pasos):
# Paso 1: pedir token
curl -X POST https://app.clautia.com/api/v1/posts/POST_ID/publish \
-H "Authorization: Bearer $CLAUTIA_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
# Paso 2: ejecutar con token
curl -X POST https://app.clautia.com/api/v1/posts/POST_ID/publish \
-H "Authorization: Bearer $CLAUTIA_API_KEY" \
-H "X-Confirmation-Token: $TOKEN" \
-H "Content-Type: application/json" \
-d '{}'
Errores y formato de respuesta
Los errores devuelven:
{ "code": "FORBIDDEN", "message": "Access denied." }
Códigos comunes:
| HTTP | Código | Significado |
|---|---|---|
| 400 | BAD_REQUEST | Payload inválido |
| 401 | UNAUTHORIZED | Clave ausente/inválida/revocada |
| 402 | PAYMENT_REQUIRED | Hace falta suscripción activa |
| 403 | FORBIDDEN | El scope o rol no permite la acción |
| 404 | NOT_FOUND | Recurso no existe en este espacio |
| 409 | CONFLICT | Conflicto de estado o idempotencia |
| 429 | TOO_MANY_REQUESTS | Exceso de tasa o presupuesto diario |
| 500 | INTERNAL_SERVER_ERROR | Error inesperado del servidor |
| 503 | SERVICE_UNAVAILABLE | Capacidad temporal (Retry-After: 1) |
En estos errores de validación, HTTP 400 devuelve BAD_REQUEST como código y el motivo en message:
| Mensaje | Significado |
|---|---|
account_disconnected | Una cuenta elegida no está disponible o se ha desconectado. |
plan_capacity_exceeded | El número de canales conectados supera el límite del plan. |
gbp_location_required | La cuenta de Google Business Profile necesita una ubicación. |
gbp_invalid_media | El archivo de Google Business Profile no es válido. |
destination_required | Elige primero un destino de LinkedIn o Facebook. |
destination_unknown | Ese destino no está elegido para la cuenta. |
Otros errores de validación devuelven un código específico y un mensaje descriptivo:
| Código | Significado |
|---|---|
instagram_media_required | Instagram necesita una imagen o un vídeo. |
character_limit | El texto supera el límite de caracteres de una red. |
telegram_caption_limit | El texto que acompaña al archivo supera el límite de Telegram. |
media_not_uploaded | Sube el archivo a Clautia antes de usarlo. |
Si una publicación tiene un envío en curso o recién hecho, «actualizar» o «publicar ya» responden HTTP 409 con el código recovery_pending: no se reenvía nada a la vez y Clautia lo reintenta automáticamente en unos minutos. Reintentar una publicación incierta, o cancelarla, mientras un envío anterior puede seguir en curso responde HTTP 409 con retry_wait: vuelve a intentarlo en unos minutos. Cancelar una publicación que el servicio de publicación está a punto de enviar responde HTTP 409 con about_to_publish, y una que el servicio sigue dando por programada mucho después de su hora responde overdue_at_provider: no se cambia nada y la publicación sigue lo que diga el servicio.
Límites
- 60 lecturas y 30 escrituras por minuto y clave
- Límites diarios por plan, contados en horario UTC. Las publicaciones cuentan para todo el espacio, así que todas sus claves las comparten. Los créditos IA cuentan por clave, siempre dentro del tope diario de créditos IA del espacio:
- Creator: 50 publicaciones, 50 créditos IA por clave, 300 créditos IA por espacio
- Pro: 200 publicaciones, 200 créditos IA por clave, 900 créditos IA por espacio
- Agency: 1.000 publicaciones, 1.000 créditos IA por clave, 2.250 créditos IA por espacio
- Claves activas por plan:
- Creator: 2
- Pro: 5
- Agency: 20
Sigue con MCP o CLI. Para ver lo que pide la API de cada red, lee APIs de redes sociales comparadas; Ayrshare es la alternativa pensada solo para desarrolladores.
Crea tu espacio, genera una clave en Ajustes → API y conecta tu agente.
Empieza tu prueba de 7 días