Saltar al contenido

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étodoRutaScope(s)Clase
GET/whoamiclave requeridaR
GET/brandsbrands:readR
GET/accountsbrands:readR
GET/postsposts:readR
GET/posts/{postId}posts:readR
POST/postsposts:writeW
POST/posts/{postId}/scheduleposts:writeW*
POST/posts/{postId}/publishposts:writeD
POST/posts/{postId}/cancelposts:writeD
POST/ai/draftai:writeW
POST/ai/adaptai:writeW

* 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:

HTTPCódigoSignificado
400BAD_REQUESTPayload inválido
401UNAUTHORIZEDClave ausente/inválida/revocada
402PAYMENT_REQUIREDHace falta suscripción activa
403FORBIDDENEl scope o rol no permite la acción
404NOT_FOUNDRecurso no existe en este espacio
409CONFLICTConflicto de estado o idempotencia
429TOO_MANY_REQUESTSExceso de tasa o presupuesto diario
500INTERNAL_SERVER_ERRORError inesperado del servidor
503SERVICE_UNAVAILABLECapacidad temporal (Retry-After: 1)

En estos errores de validación, HTTP 400 devuelve BAD_REQUEST como código y el motivo en message:

MensajeSignificado
account_disconnectedUna cuenta elegida no está disponible o se ha desconectado.
plan_capacity_exceededEl número de canales conectados supera el límite del plan.
gbp_location_requiredLa cuenta de Google Business Profile necesita una ubicación.
gbp_invalid_mediaEl archivo de Google Business Profile no es válido.
destination_requiredElige primero un destino de LinkedIn o Facebook.
destination_unknownEse destino no está elegido para la cuenta.

Otros errores de validación devuelven un código específico y un mensaje descriptivo:

CódigoSignificado
instagram_media_requiredInstagram necesita una imagen o un vídeo.
character_limitEl texto supera el límite de caracteres de una red.
telegram_caption_limitEl texto que acompaña al archivo supera el límite de Telegram.
media_not_uploadedSube 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