API REST

Todo lo que haces en el panel, por HTTP y en JSON. La API y el servidor MCP comparten el mismo registro de 84 operaciones y las mismas llaves. Disponible en Starter y Pro.

Autenticación

Crea una llave en Ajustes → API. Se muestra una sola vez: guárdala en tu gestor de secretos. Mándala en cada petición con la cabecera Authorization: Bearer pk_live_….

Dirección base: https://jotly.si/api/v1

curl "https://jotly.si/api/v1/requests?statuses=planned,in_progress&sort=top&limit=10" \  -H "Authorization: Bearer pk_live_TU_LLAVE"

Cada llave tiene acceso completo a su espacio. Crea una por integración o agente para poder revocarla sin afectar a las demás.

Crear y responder

Los parámetros de ruta van en la URL; en GET y DELETE el resto va en la query, y en POST, PATCH y PUT en un cuerpo JSON. Cada recurso viene envuelto en su nombre ({ request }, { board }, { member }). Al crear la respuesta es 201; las relaciones (votar, suscribir, etiquetar) responden { ok: true } y los borrados 204 sin cuerpo.

curl -X POST "https://jotly.si/api/v1/requests" \  -H "Authorization: Bearer pk_live_TU_LLAVE" \  -H "Content-Type: application/json" \  -d '{    "board_id": "brd_123",    "title": "Exportación automática cada mes",    "body": "Que las facturas lleguen solas al contador.",    "author": { "external_id": "u_812" }  }'

HTTP/1.1 201 CreatedX-Request-Id: req_8f2k1x0c9q7m3v5b6n4z {  "request": {    "id": "post_4j8w2q",    "number": 42,    "title": "Exportación automática cada mes",    "status": "pending",    "board": { "id": "brd_123", "name": "Funciones", "type": "public" },    "author": { "id": "cus_9x1", "external_id": "u_812", "type": "user", "first_name": "Lucía" },    "tags": [],    "attachments": [],    "vote_count": 1,    "comment_count": 0  }}

Los miembros (author, voter, subscriber, actor, member) se referencian con { id } o { external_id } (tu id de usuario). Jotly también acepta { email }; con external_id o email el miembro se crea si no existe. El actor de una respuesta o de un cambio de estado tiene que ser alguien del equipo; sin él actúa quien creó la llave.

Paginación

Todas las listas responden { <recurso>: [...], next_cursor }. Pide la siguiente página con cursor igual al next_cursor de la anterior; cuando llega null ya no hay más. limit va de 1 a 100 (10 en solicitudes y novedades, 20 en conversaciones y miembros, 50 en votos y en la línea de tiempo). El cursor es opaco: no lo armes a mano.

Idempotencia

POST /requests, POST /changelogs, POST /assets/import y las respuestas y notas de conversación aceptan la cabecera Idempotency-Key. Durante 24 horas, repetir la petición con la misma llave y el mismo cuerpo devuelve la respuesta original (con la cabecera Idempotent-Replayed: true) en vez de crear otra vez.

curl -X POST "https://jotly.si/api/v1/conversations/cnv_123/replies" \  -H "Authorization: Bearer pk_live_TU_LLAVE" \  -H "Idempotency-Key: corrida-2026-10-19-cnv_123" \  -H "Content-Type: application/json" \  -d '{ "body": "Listo, ya quedó.", "actor": { "external_id": "agente-soporte" } }'

Límites de tasa

Cada llave tiene un límite por minuto que comparten la API REST y el servidor MCP (120 por omisión). Al pasarlo, la respuesta es 429 con la cabecera Retry-After y los segundos de espera en details.retry_after_seconds.

HTTP/1.1 429 Too Many RequestsRetry-After: 23 {  "error": {    "code": "rate_limited",    "message": "Demasiadas peticiones: el límite es 120 por minuto por llave",    "details": { "retry_after_seconds": 23 }  }}

Errores

Los errores responden con el código HTTP correspondiente y { error: { code, message, details? } }. Toda respuesta, también los errores, trae la cabecera X-Request-Id: inclúyela si nos escribes a soporte.

{  "error": {    "code": "invalid_api_token",    "message": "Token de API inválido"  }}

Miembros y empresas

POST /members/sync crea o actualiza un miembro por external_id; sus traits se fusionan (un rasgo en null se borra) y companies crea o actualiza sus empresas y lo liga a ellas. El identify del widget acepta el mismo companies. DELETE /members/:member_id borra sus datos personales y conserva sus solicitudes, comentarios y votos; después, leerlo o borrarlo otra vez responde 410 member_erased.

Adjuntos y archivos: Jotly todavía no tiene almacenamiento de archivos, así que attachment_urls, addRequestAttachments, addCommentAttachments, POST /assets y POST /assets/import responden 422 invalid_attachment o invalid_asset. Listar y quitar adjuntos sí funciona.

Operaciones

El detalle de cada parámetro está en la especificación OpenAPI. Puedes importarla en Postman o Insomnia, o generar un cliente con ella.

Tableros

Solicitudes

Archivos

Novedades

Miembros

Empresas

Conversaciones