Convenciones
Mapa de puntos finales del producto, convenciones de solicitud, paginación, conflictos y errores.
Los puntos finales /v1 protegidos toman cuerpos de solicitud Authorization: Bearer <access-token> y JSON. La API valida las formas de solicitud públicas, resuelve el contexto de la persona que llama y del espacio de trabajo y luego delega los servicios del dominio; no posee ningún almacenamiento de productos.
Mapa de puntos finales principales
| Dominio | Principales criterios de valoración |
|---|---|
| Libros de jugadas | GET/POST /v1/playbooks, GET/DELETE /v1/playbooks/:id, Versiones, /access, estrella, rutas de token compartido |
| Alias del Playbook | GET/PUT /v1/aliases, DELETE /v1/aliases/:alias; /v1/aliases/resolve resuelve referencias pb: |
| Casos | GET/POST /v1/cases, GET/PATCH /v1/cases/:id, cesionario, ACL, transferencias, candidatos/grafo de transferencias, cerrar, reabrir |
| Tareas | GET/POST /v1/cases/:id/tasks, GET /v1/tasks, actualizar, asignatario, cerrar, reabrir |
| Registros | GET/POST /v1/cases/:id/records (GET admite expansión de alcance a través de transferencias) |
| Sugerencias | GET/POST /v1/playbooks/:id/suggestions, GET /v1/suggestions, obtener, actualizar, resolver |
| Administración | espacios de trabajo, miembros del espacio de trabajo, equipos, miembros del equipo, créditos, tokens CLI y MCP |
La creación y la navegación dentro del recurso padre siguen la propiedad: las Tareas y los Registros viven bajo su Caso y las Sugerencias bajo su Playbook. Las listas de Tareas entre Casos y de Sugerencias entre Playbooks permanecen como vistas de bandeja de entrada de nivel superior. Las operaciones de alias son de nivel superior porque (ownerId, alias) identifica el recurso del namespace. Cada namespace personal o de Workspace administrado puede asignar un alias a cualquier Playbook legible. El alias del propietario del Playbook se muestra como oficial; un alias de terceros se devuelve solo en el contexto de su propietario. Use assignedTo=me para sus Tareas. Para las Sugerencias, view=sent lista las que envió y view=inbox las de los Playbooks que gestiona; ambas requieren autenticación.
Contexto y paginación
Los puntos finales administrativos admitidos toman workspaceId como parámetro de consulta. Las rutas de dominio de producto resuelven el contexto del actor a partir de la credencial del portador. Nunca asuma que un espacio de trabajo CLI seleccionado localmente se aplica a una solicitud HTTP sin formato.
Las operaciones de lista utilizan pageSize y un cursor opaco. Conserve el cursor exactamente; no lo construyas ni lo decodifiques. Los registros utilizan pedidos estables (createdAt, id) y aceptan order=asc|desc. Los filtros de registro siempre intersectan el acceso al caso en vivo de la persona que llama.
Mutaciones
Los cuerpos de mutación llevan idempotencyKey. Reutilice una clave solo para una solicitud idéntica después de una falla de la red o una respuesta incierta. Las mutaciones de caso y tarea incluyen expectedLockVersion; la publicación de un Playbook incluye baseVersionId. Una falta de coincidencia devuelve un conflicto para que el cliente pueda volver a leer y reconstruir la intención desde un estado nuevo.
Las solicitudes de cerrar tarea y cerrar caso pueden incluir nuevos registros, lo que permite que la transición de estado y los resultados duraderos finales se comprometan juntos.
Errores
| Estado | Significado |
| ------ | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 400 | parámetro, consulta, JSON, valor no admitido o error de validación del esquema de solicitud con formato incorrecto |
| 401 | credenciales de portador faltantes, caducadas o no válidas |
| 402 | créditos insuficientes en el contexto resuelto |
| 403 | autenticado pero no autorizado para la operación |
| 404 | recurso faltante u oculto intencionalmente |
| 409 | Versión base, versión de bloqueo, ciclo de vida o conflicto de unicidad |
| 429 | tarifa limitada; retroceder antes de volver a intentarlo |
| 5xx | servidor o fallo ascendente | Vuelva a intentar las respuestas 429 y transitorias 5xx con retroceso exponencial limitado. No vuelva a intentar automáticamente respuestas de validación, autorización o conflicto. Para un conflicto, lea el estado actual y obtenga el juicio humano o del agente antes de emitir una nueva mutación. |