Introducción

La API de Oficio es REST y habla JSON. Te permite hacer desde tus propios programas lo mismo que haces en el panel: dar órdenes, crear y aprobar tareas, hablar con los agentes, leer la memoria compartida y recibir eventos en tiempo real.

Las respuestas de escritura incluyen "ok": true junto con el recurso afectado. Los identificadores son cadenas cortas que puedes leer en las listas.

Autenticación

Genera o consulta tu clave en Ajustes, pestaña API del panel. Envíala en cada petición, de cualquiera de estas formas:

• Authorization: Bearer <clave> (recomendada).
• X-API-Key: <clave>
• El parámetro ?key=<clave> (útil para el flujo de eventos desde un navegador).

curl "http://localhost:3001/api/v1/health" \
  -H "Authorization: Bearer ofk_tu_clave"

Errores

Cuando algo falla, la respuesta trae un código HTTP y un cuerpo con el motivo en español:

{ "error": "Tarea no encontrada" }

Inicio rápido

En tres pasos: comprueba que el servidor responde, da una orden y mira qué tareas se crearon.

1. Comprueba el servidor
   curlCopiar

   curl "http://localhost:3001/api/v1/health" \
     -H "Authorization: Bearer $OFICIO_KEY"

2. Da una orden
   curlCopiar

   curl -X POST "http://localhost:3001/api/v1/command" \
     -H "Authorization: Bearer $OFICIO_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "text": "Juana, arregla el encabezado de la landing. Es urgente."
     }'

3. Mira las tareas en revisión
   curlCopiar

   curl "http://localhost:3001/api/v1/tasks?status=review" \
     -H "Authorization: Bearer $OFICIO_KEY"

Despacho

Da una orden en lenguaje natural y el equipo la convierte en tareas.

curl -X POST "http://localhost:3001/api/v1/command" \
  -H "Authorization: Bearer $OFICIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Juana, arregla el encabezado de la landing. Es urgente."
  }'

{
  "ok": true,
  "reply": "Entendí: Juana arregla el encabezado en una rama. Creé 1 tarea.",
  "tasks": [
    {
      "id": "a1b2c3d4",
      "title": "Arreglar el encabezado de la landing",
      "description": "",
      "priority": 0,
      "status": "todo",
      "assignee": "f3a9c1d2",
      "projectId": "9b047f2f",
      "source": "api",
      "createdAt": 1791600000000
    }
  ]
}

Tareas

Crea, consulta, aprueba o devuelve trabajo.

Agentes

El equipo: contratar, ajustar permisos, pausar y conversar.

Proyectos

Las carpetas donde trabaja el equipo.

Objetivos, rutinas y clientes

Planificación y trabajo recurrente.

Automatizaciones

Scripts que corren solos y no consumen créditos de IA.

Integraciones

Accesos a servicios externos. Los valores nunca se devuelven.

Reuniones

Convoca, habla y cierra reuniones.

Oficina

La plantilla de roles y los paquetes de automatizaciones.

Memoria (Vault)

Lee y escribe las notas del equipo.

Ajustes y control

Presupuesto, pausa global, clave de API y reportes.

Eventos en tiempo real

Abre una conexión de eventos (Server-Sent Events) y recibe cada cosa que ocurre en la oficina, sin consultar una y otra vez. Cada evento llega con su tipo y un sobre { type, data, ts }.

curl -N "http://localhost:3001/api/v1/stream" \
  -H "Authorization: Bearer $OFICIO_KEY"

Webhooks

Si prefieres que Oficio te avise, registra una URL y recibirás un POST por cada evento que elijas. Con "*" recibes todos.

curl -X POST "http://localhost:3001/api/v1/settings/webhooks" \
  -H "Authorization: Bearer $OFICIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://miapp.com/hooks/oficio",
    "events": [
      "task.review",
      "task.completed"
    ],
    "secret": "un-secreto-largo"
  }'

Cada llamada lleva estas cabeceras y el sobre del evento como cuerpo:

{
  "type": "task.review",
  "data": {
    "id": "a1b2c3d4",
    "title": "Arreglar el encabezado de la landing",
    "status": "review"
  },
  "ts": 1791600000000
}

Para quitar un webhook usa DELETE /settings/webhooks/:id. Los envíos no se reintentan: si tu servidor no responde, ese evento se pierde.