Ratio REST API

The REST API gives access to the same things as the MCP server —spaces, projects, sprints and tasks, with their comments, checklist, dependencies, attachments and diagrams—, for scripts and custom integrations. It follows the same permissions as the screen.

Base: https://ratioteams.com/api/v1
Format: JSON in requests and responses, errors included.
Authentication: Personal key: Authorization: Bearer tasks_fk_… (X-API-Key also works).
Limit: 30 requests per second per key, with bursts of up to 60.

Authentication

Keys are created in the portal, under Credentials. They are shown only once and can be revoked at any time. A key can do the same as its owner: it sees only the projects in their spaces, with the role they have in each one. What is done with it stays in the history under its owner's name, marked "via API".

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

Always start with GET /me and take ids from the responses; never guess them.

Endpoints

Account, spaces and people

GET  /me
GET  /spaces                     own spaces, with the role in each one
GET  /spaces/{id}/members
GET  /users?space_id={id}        people you share a space with

Projects and sprints

GET    /projects                 ?space_id=
GET    /projects/{id}            includes can_write_tasks and can_manage
GET    /projects/{id}/modules
GET    /projects/{id}/types      the space's task types
GET    /projects/{id}/sprints
POST   /projects/{id}/sprints    {name?, starts_on?, ends_on?, traer_backlog?}
PATCH  /sprints/{id}
POST   /sprints/{id}/close       {destino?: sprint id | "backlog" | "hechas"}
DELETE /sprints/{id}             its tasks go back to the backlog

Tasks

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}               the whole task: comments, checklist, files, dependencies, diagrams
PATCH  /tasks/{id}               changes only the fields sent
POST   /tasks/{id}/status        {status, block_reason?}
DELETE /tasks/{id}               only whoever manages the project

Comments, checklist, dependencies and attachments

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

Diagrams

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

A diagram can be sent as draw.io XML or as a Mermaid flowchart, which Ratio converts and lays out on its own.

Task rules

The statuses are pendiente, en_curso, bloqueada and hecha (pending, in progress, blocked, done), and they change only through POST /tasks/{id}/status.
Moving to bloqueada requires a block_reason.
Tasks can be assigned only to owners and members of the project's space.
The tipo must be one of the space's types (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": "Review customer sign-up", "tipo": "mejora"}'

Error codes

Code	Meaning
`401`	The key doesn't exist, was revoked or expired.
`403`	The resource is visible, but the role isn't enough for that action.
`404`	The resource doesn't exist or belongs to someone else's space.
`422`	The request is malformed; the `error` field says what to fix.
`429`	Too many requests; wait as long as `Retry-After` says.

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

What it doesn't cover

The API doesn't manage spaces or invitations, and doesn't touch notes, shared links or account administration. Those are done in the portal.

← Documentation