API REST

Orkestra expone una API REST completa sobre HTTPS con autenticación por bearer token. Esta página cubre las bases — auth, formato de respuestas, rate limits y los endpoints más usados.

Base URL

Todas las peticiones van a https://api.orkestra.team/v1/. Las versiones se mantienen por al menos 12 meses tras anunciar una nueva versión, con periodo de deprecación claro.

Autenticación

La API usa bearer tokens en el header Authorization. Hay dos formas de obtener tokens:

• Sesión de usuario — login con email/password o SSO devuelve un JWT. Expira en 7 días, renovable con refresh token.
• API key — para integraciones server-to-server. Generable desde Ajustes → API Keys (requiere plan Pro o superior).

Para desarrollo local, también puedes usar un token MCP — tienen el mismo scope que el usuario que los creó.

Formato de respuesta

Todas las respuestas son JSON. En éxito, el cuerpo es el objeto solicitado o un array. En error, el cuerpo incluye un error con code, message y opcionalmente details:

• 400 — Bad Request (validación fallida, body incorrecto)
• 401 — Unauthorized (token ausente o inválido)
• 403 — Forbidden (token válido pero sin permisos suficientes)
• 404 — Not Found
• 409 — Conflict (violación de constraint, como duplicado)
• 422 — Unprocessable Entity (negocio rechaza la operación)
• 429 — Rate limit excedido (mirar headers X-RateLimit-*)
• 5xx — Error de servidor (reintentable con backoff)

Rate limiting

Los límites se aplican por token y por endpoint:

• Lectura general: 1000 req/minuto
• Escritura general: 500 req/minuto
• Operaciones masivas: 100 req/minuto
• Auth (login, password reset): 5 req/minuto por IP
• Webhooks management: 100 req/minuto

Cada respuesta incluye headers X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset. En 429, respeta Retry-After.

Paginación

Los listados usan paginación por cursor. Parámetros de query:

• limit — número máximo de items (default 20, max 100)
• cursor — cursor opaco devuelto por la petición anterior

La respuesta incluye nextCursor si hay más items. Cuando es null, llegaste al final.

Endpoints principales

Los recursos principales de la API:

• /v1/organizations — CRUD de organizaciones, miembros, áreas
• /v1/projects — proyectos, workflows, custom fields
• /v1/tasks — tareas, estados, asignaciones, comentarios
• /v1/wiki — páginas, versiones, comentarios, edit locks
• /v1/chat — mensajes, rooms, búsqueda
• /v1/analytics — métricas, dashboards, exports
• /v1/webhooks — outbound + inbound webhooks
• /v1/mcp/tokens — gestión de tokens MCP

Webhooks en lugar de polling

Si necesitas enterarte de cambios en Orkestra, usa webhooks outbound en lugar de hacer polling. Son más eficientes, más rápidos y Orkestra garantiza la entrega con retries automáticos. Ver la guía de webhooks.

Documentación completa