# API de projetos

Mantenha o contexto com escopo de projeto e os registros de handoff vinculados ao fluxo de trabalho do agente que os criou.

- Canonical: https://docs.xmemo.dev/pt-br/docs/api/projects
- Locale: pt-BR
- Content-Locale: pt-BR
- Canonical-Content-Digest: f87dd0befa0c74658bc8585d0e0cb06c2f4e66349349fea57dfb0ad50d4d972a
- Edition-Digest: f666de7527eaa197d07ec6dc55d7deabdeb3f8ecec8ed900795bef4a8629ff18
- Source-Revision: sha256:4feaf3bfdc42a8d043acdcde2b2c2e4c2dd59e9077168e06d562745030d51c62

## Limites do projeto e contrato base

O contrato OpenAPI expõe as operações de projeto em /v1/projects/{project_id}; não existe uma operação POST /v1/projects de nível superior no contrato público de plano de dados versionado. project_id seleciona o workspace do projeto, enquanto scope, bucket, team_id e path continuam sendo campos de autorização e filtragem. Autentique com o cabeçalho X-API-Key e use um token autorizado para o projeto/equipe selecionado.

- Contexto: POST /v1/projects/{project_id}/context.
- Tarefas: POST /v1/projects/{project_id}/todos; GET /v1/projects/{project_id}/todos.
- Transições de tarefa: 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.
- Decisões: POST /v1/projects/{project_id}/decisions; GET /v1/projects/{project_id}/decisions.
- Transições de decisão: 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.
- Manutenção: 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 solicitação e resposta do contexto do projeto

POST /v1/projects/{project_id}/context aceita ProjectContextRequest: bucket tem % como padrão, team_id e durable_query aceitam null, max_items tem padrão 100 (1..1000), max_tokens tem padrão 8000 (1..50000), include_durable_context tem padrão true e recent_hours tem padrão 168 (1..8760). Retorna ProjectContextPackResponse com project_scope, assembled_at e budget obrigatórios, além de project_state, agent_states, action_items, decisions, timeline, recent_memories, durable_context, governance_caveats, missing_domains, incomplete_domains e 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
}
```

## Tarefas e decisões do projeto

A criação de tarefa aceita ProjectTodoCreateRequest com content obrigatório e priority, assignee_agent_id, depends_on, due_at, source_memory_id, metadata, bucket (default work), scope, path e team_id opcionais; retorna ProjectTodo. GET de tarefas aceita status e team_id opcionais e retorna um array de ProjectTodo. A criação de decisão aceita ProjectDecisionCreateRequest com context obrigatório e options, impact_level, proposed_by_agent_id, supersedes, source_memory_id, due_at, metadata, bucket (default work), scope, path e team_id opcionais; retorna ProjectDecision. A listagem de decisões aceita status e team_id e retorna um 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"]
}
```

## Operações do ciclo de vida de tarefas e decisões

As operações de ciclo de vida do OpenAPI retornam ProjectTodo ou ProjectDecision, exceto supersede, que retorna um array de ProjectDecision. ProjectTodo exige todo_id, project_id e content; os outros campos declarados incluem 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 e extra_metadata. ProjectDecision exige decision_id, project_id e content; os outros campos declarados incluem 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 e extra_metadata. POST /v1/projects/{project_id}/decisions/{decision_id}/resolve exige {resolution: string}; POST /v1/projects/{project_id}/decisions/{decision_id}/supersede exige context e aceita options, impact_level, proposed_by_agent_id e resolution_note; reopen não tem corpo de solicitação. accept, unblock e a maioria das transições de tarefa não têm corpo no OpenAPI; assign exige {assignee_agent_id: string}, block exige {reason: string}, complete aceita {note: string|null} e cancel aceita {reason: string|null}.

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

## Manutenção do projeto, paginação, erros e limites

A manutenção faz parte da superfície pública /v1/projects no OpenAPI: GET/PATCH de settings usam ProjectMaintenanceSettingsResponse e ProjectMaintenanceSettingsPatchRequest; o GET do relatório aceita team_id e scan_limit (default 1000, intervalo 1..5000) e retorna ProjectMaintenanceReportResponse; o POST de execução aceita ProjectMaintenanceExecuteRequest com actions (1..4 strings), target_ids (até 500 IDs) e confirm_all_matching (default false), retornando ProjectMaintenanceExecuteResponse. As listas de tarefas e decisões do projeto expõem filtros status/team_id, mas nenhum parâmetro de página ou cursor no OpenAPI. Todas as operações listadas declaram HTTPValidationError para 422. Os erros de autorização do runtime e os limites configuráveis de 60 segundos são compartilhados com as páginas Authentication e Memory API; nenhuma cota específica de projeto é publicada no OpenAPI.