API REST de Ratio

La API REST da acceso a lo mismo que el servidor MCP —espacios, proyectos, sprints y tareas, con sus comentarios, checklist, dependencias, adjuntos y diagramas—, para scripts e integraciones propias. Respeta los mismos permisos que la pantalla.

Base

https://ratioteams.com/api/v1

Formato

JSON en los pedidos y en las respuestas, incluidos los errores.

Autenticación

Clave personal: Authorization: Bearer tasks_fk_… (también X-API-Key).

Límite

30 pedidos por segundo por clave, con ráfagas de hasta 60.

Autenticación

Las claves se generan en el portal, en Credenciales. Se muestran una sola vez y se pueden revocar en cualquier momento. Una clave puede lo mismo que su dueño: ve sólo los proyectos de sus espacios, con el rol que tiene en cada uno. Lo que se hace con ella queda en el historial a nombre de su dueño, marcado «vía API».

curl -s https://ratioteams.com/api/v1/me \
  -H "Authorization: Bearer $RATIO_API_KEY"

Conviene empezar siempre por GET /me y sacar los ids de las respuestas, nunca suponerlos.

Endpoints

Cuenta, espacios y personas

GET  /me
GET  /spaces                     espacios propios, con el rol en cada uno
GET  /spaces/{id}/members
GET  /users?space_id={id}        personas con las que se comparte un espacio

Proyectos y sprints

GET    /projects                 ?space_id=
GET    /projects/{id}            incluye can_write_tasks y can_manage
GET    /projects/{id}/modules
GET    /projects/{id}/types      tipos de tarea del espacio
GET    /projects/{id}/sprints
POST   /projects/{id}/sprints    {name?, starts_on?, ends_on?, traer_backlog?}
PATCH  /sprints/{id}
POST   /sprints/{id}/close       {destino?: id de sprint | "backlog" | "hechas"}
DELETE /sprints/{id}             las tareas vuelven al backlog

Tareas

GET    /projects/{id}/tasks      ?status=&sprint_id=&assignee=   (sprint_id=-1: backlog)
POST   /projects/{id}/tasks      {name, tipo?, description?, sprint_id?, module_id?, due_date?, assignee_ids?}
GET    /tasks/{id}               la tarea entera: comentarios, checklist, archivos, dependencias, diagramas
PATCH  /tasks/{id}               cambia sólo los campos enviados
POST   /tasks/{id}/status        {status, block_reason?}
DELETE /tasks/{id}               sólo quien gestiona el proyecto

Comentarios, checklist, dependencias y adjuntos

GET|POST /tasks/{id}/comments
PATCH    /comments/{id}          {text}
DELETE   /comments/{id}
GET|POST /tasks/{id}/checks
PATCH    /checks/{id}            {done} o {text}
GET|POST /tasks/{id}/dependencies          {depends_on}
DELETE   /tasks/{id}/dependencies/{otra_id}
GET      /tasks/{id}/files
GET      /tasks/{id}/files/{file_id}

Diagramas

GET|POST /tasks/{id}/diagrams    {title?, xml | mermaid}
GET      /diagrams/{id}
PATCH    /diagrams/{id}
DELETE   /diagrams/{id}

Un diagrama se puede mandar como XML de draw.io o como un diagrama de flujo en Mermaid, que Ratio convierte y ordena solo.

Reglas de las tareas

• Los estados son pendiente, en_curso, bloqueada y hecha, y se cambian sólo con POST /tasks/{id}/status.
• Pasar a bloqueada exige un block_reason.
• Se puede asignar sólo a dueños y miembros del espacio del proyecto.
• El tipo tiene que ser uno de los del espacio (GET /projects/{id}/types).

curl -s -X POST https://ratioteams.com/api/v1/projects/12/tasks \
  -H "Authorization: Bearer $RATIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Revisar el alta de clientes", "tipo": "mejora"}'

Códigos de error

{ "error": "Para bloquear una tarea hace falta 'block_reason'", "status": 422 }

Qué no cubre

La API no administra espacios ni invitaciones, ni toca las notas, los links compartidos o la administración de cuentas. Eso se hace desde el portal.