API REST (beta)

La API REST de Orkestra está en beta: puedes usarla hoy con un token personal, pero todavía puede cambiar sin aviso. Esta página cubre lo básico — cómo entrar, qué puede hacer un token, el formato de las respuestas y los límites.

En beta

La API es la misma que usa la app web. Mientras esté en beta no hay promesa de estabilidad: una ruta o un campo pueden cambiar o desaparecer entre versiones. Si construyes algo encima, pruébalo después de cada cambio de Orkestra.

Dirección base

Todas las rutas cuelgan de /api/v1, por ejemplo https://api.orkestra.team/api/v1/projects.

Tokens personales

Para que un programa tuyo use la API, crea un token en Tus ajustes → Conexiones con IA en la app. Al crearlo eliges:

  • Por dónde entra: la API REST, el MCP (asistentes de IA) o ambos.
  • Qué puede hacer en cada parte: nada, lectura o escritura en cada uno de estos dominios — tareas y proyectos, documentos y tablas, conversaciones y avisos, tiempo, dinero, stock, productos y ventas, informes, organización y personas, y tu perfil. Buscar, la ayuda y el resumen siempre se pueden leer.
  • Una sola organización si quieres limitarlo, y un vencimiento (nunca, 30 días, 90 días o una fecha).

La clave empieza con ork_ y se muestra una sola vez. Se manda en cada pedido:

Authorization: Bearer ork_…

Un token nunca puede más que tú: lo que hace pasa por tus mismos permisos, y si pierdes acceso a algo, el token también. Todo lo que hace queda firmado en el historial con tu nombre y el del token. Puedes cambiar lo que alcanza, generar una clave nueva o revocarlo cuando quieras.

Algunas cosas solo se pueden hacer con tu sesión en la app, nunca con un token: gestionar tokens, entrar y el segundo paso, autorizar aplicaciones, la privacidad de tu cuenta, las notificaciones al teléfono, el calendario, SSO y SCIM, las exportaciones y la sincronización del teléfono.

Formato de respuesta

Todas las respuestas son JSON. En éxito:

{ "status": "success", "data": { } }

En error, message explica qué pasó (en el idioma del pedido) y code lo clasifica:

{ "status": "error", "message": "…", "code": "FORBIDDEN" }

Cuando un token no alcanza

  • 401 UNAUTHORIZED — el token es inválido, venció o fue revocado.
  • 403 FORBIDDEN — el token es válido pero no llega: el dominio no está en su recorte (o solo tiene lectura y el pedido escribe), la ruta es solo para la sesión, o lo que pides queda fuera de la organización a la que está limitado. El message dice cuál de las tres.
  • 429 RATE_LIMITED — el token pasó su límite; espera unos minutos.

Límite por token

Cada token tiene 1000 pedidos cada 15 minutos, un solo cupo para la API REST y el MCP juntos. Las respuestas limitadas por dirección IP traen los encabezados estándar RateLimit-*.

Listados

Los listados paginados aceptan page y limit y responden con pagination: { page, limit, total, pages }. Algunos listados devuelven solo una página sin ese bloque, recortada a limit (50 por defecto): si llega la página llena, pide la siguiente.

Rutas principales

  • /api/v1/organizations — organizaciones, miembros y áreas
  • /api/v1/projects — proyectos, y sus tareas en /api/v1/projects/:id/tasks
  • /api/v1/tasks — tareas, comentarios, dependencias y tiempo
  • /api/v1/wiki — documentos
  • /api/v1/tables — tablas de datos
  • /api/v1/search — búsqueda, filtrada según lo que el token puede leer

Avisos en lugar de preguntar

Si necesitas enterarte de cambios, usa los webhooks salientes en lugar de preguntar cada tanto: Orkestra avisa a tu sistema y reintenta si falla.