# API de proyectos

Mantén conectados el contexto de ámbito de proyecto y los registros de handoff con el workflow del agente que los creó.

- Canonical: https://docs.xmemo.dev/es/docs/api/projects
- Locale: es-ES
- Content-Locale: es-ES
- Canonical-Content-Digest: f87dd0befa0c74658bc8585d0e0cb06c2f4e66349349fea57dfb0ad50d4d972a
- Edition-Digest: 0e1a39daf092d9214828ce0a54bfd6661d01bebeb41e5fd984eb13dabc3ec37a
- Source-Revision: sha256:4feaf3bfdc42a8d043acdcde2b2c2e4c2dd59e9077168e06d562745030d51c62

## Límites de proyecto y contrato base

El contrato OpenAPI expone operaciones de proyecto bajo /v1/projects/{project_id}; no existe una operación POST /v1/projects de nivel superior en el contrato público del plano de datos versionado. project_id selecciona el workspace del proyecto, mientras que scope, bucket, team_id y path siguen siendo campos de autorización y filtrado. Autentícate con el header X-API-Key y usa un token autorizado para el proyecto/equipo seleccionado.

- Contexto: POST /v1/projects/{project_id}/context.
- TODOs: POST /v1/projects/{project_id}/todos; GET /v1/projects/{project_id}/todos.
- Transiciones de TODO: POST /v1/projects/{project_id}/todos/{todo_id}/accept; POST /v1/projects/{project_id}/todos/{todo_id}/assign; POST /v1/projects/{project_id}/todos/{todo_id}/block; POST /v1/projects/{project_id}/todos/{todo_id}/unblock; POST /v1/projects/{project_id}/todos/{todo_id}/complete; POST /v1/projects/{project_id}/todos/{todo_id}/cancel.
- Decisiones: POST /v1/projects/{project_id}/decisions; GET /v1/projects/{project_id}/decisions.
- Transiciones de decisión: POST /v1/projects/{project_id}/decisions/{decision_id}/resolve; POST /v1/projects/{project_id}/decisions/{decision_id}/supersede; POST /v1/projects/{project_id}/decisions/{decision_id}/reopen.
- Mantenimiento: GET /v1/projects/{project_id}/maintenance/settings; PATCH /v1/projects/{project_id}/maintenance/settings; GET /v1/projects/{project_id}/maintenance; POST /v1/projects/{project_id}/maintenance/execute.

## Esquemas de solicitud y respuesta del contexto de proyecto

POST /v1/projects/{project_id}/context acepta ProjectContextRequest: bucket tiene por defecto %, team_id y durable_query son anulables, max_items por defecto 100 (1..1000), max_tokens por defecto 8000 (1..50000), include_durable_context por defecto true y recent_hours por defecto 168 (1..8760). Devuelve ProjectContextPackResponse con project_scope, assembled_at y budget obligatorios, además de project_state, agent_states, action_items, decisions, timeline, recent_memories, durable_context, governance_caveats, missing_domains, incomplete_domains y suggested_next_actions.

```http
POST /v1/projects/memory-os/context
X-API-Key: <your-assigned-api-key>
Content-Type: application/json

{
  "bucket": "work",
  "max_items": 100,
  "max_tokens": 8000,
  "include_durable_context": true,
  "recent_hours": 168
}
```

## TODOs y decisiones de proyecto

La creación de TODO acepta ProjectTodoCreateRequest con content obligatorio y priority, assignee_agent_id, depends_on, due_at, source_memory_id, metadata, bucket (default work), scope, path y team_id opcionales; devuelve ProjectTodo. GET todos acepta status y team_id opcionales y devuelve un array de ProjectTodo. La creación de decisiones acepta ProjectDecisionCreateRequest con context obligatorio y options, impact_level, proposed_by_agent_id, supersedes, source_memory_id, due_at, metadata, bucket (default work), scope, path y team_id opcionales; devuelve ProjectDecision. El listado de decisiones acepta status y team_id y devuelve un array.

```http
POST /v1/projects/memory-os/todos
X-API-Key: <your-assigned-api-key>
Content-Type: application/json

{
  "content": "Review the current API contract",
  "priority": "high",
  "bucket": "work"
}

POST /v1/projects/memory-os/decisions
X-API-Key: <your-assigned-api-key>
Content-Type: application/json

{
  "context": "Choose the public REST reference scope",
  "options": ["memory-only", "full-openapi"]
}
```

## Operaciones del ciclo de vida de TODOs y decisiones

Las operaciones del ciclo de vida de OpenAPI devuelven ProjectTodo o ProjectDecision, salvo supersede, que devuelve un array de ProjectDecision. ProjectTodo requiere todo_id, project_id y content; sus otros campos declarados incluyen status, priority, assignee_agent_id, accepted_by_agent_id, blocked_reason, depends_on, due_at, completed_at, completion_note, source_memory_id, created_at, updated_at, audit_trail y extra_metadata. ProjectDecision requiere decision_id, project_id y content; sus otros campos declarados incluyen title, decision, rationale, status, proposed_by_agent_id, resolved_by_agent_id, impact_level, supersedes, superseded_by, options, resolution, decision_context, source_memory_id, resolved_at, created_at, updated_at, audit_trail y extra_metadata. POST /v1/projects/{project_id}/decisions/{decision_id}/resolve requiere {resolution: string}; POST /v1/projects/{project_id}/decisions/{decision_id}/supersede requiere context y acepta options, impact_level, proposed_by_agent_id y resolution_note; reopen no tiene cuerpo de solicitud. Todo accept, unblock y la mayoría de las transiciones no tienen cuerpo de solicitud en OpenAPI; assign requiere {assignee_agent_id: string}, block requiere {reason: string}, complete acepta {note: string|null} y cancel acepta {reason: string|null}.

```json
{
  "resolution": "Use the memory-only public reference."
}
```

## Mantenimiento, paginación, errores y límites de proyecto

El mantenimiento forma parte de la superficie pública /v1/projects en OpenAPI: GET/PATCH de settings usan ProjectMaintenanceSettingsResponse y ProjectMaintenanceSettingsPatchRequest; el informe GET acepta team_id y scan_limit (default 1000, rango 1..5000) y devuelve ProjectMaintenanceReportResponse; execute POST acepta ProjectMaintenanceExecuteRequest con actions (1..4 strings), target_ids (hasta 500 IDs) y confirm_all_matching (default false), y devuelve ProjectMaintenanceExecuteResponse. Las listas de TODOs/decisiones de proyecto exponen filtros status/team_id, pero no parámetros de página o cursor en OpenAPI. Todas las operaciones enumeradas declaran HTTPValidationError para 422. Los errores de autorización del runtime y los límites configurables de 60 segundos se comparten con las páginas Authentication y Memory API; OpenAPI no publica una cuota específica de proyecto.