# Projects API

project-scoped contextとhandoff recordを、それを作成したagent workflowに接続したまま管理します。

- Canonical: https://docs.xmemo.dev/ja/docs/api/projects
- Locale: ja-JP
- Content-Locale: ja-JP
- Canonical-Content-Digest: f87dd0befa0c74658bc8585d0e0cb06c2f4e66349349fea57dfb0ad50d4d972a
- Edition-Digest: 15d7103ddb9dcc26f06d56cc368f0e92a41ac33c1ff24849378e1d88adba0fa0
- Source-Revision: sha256:4feaf3bfdc42a8d043acdcde2b2c2e4c2dd59e9077168e06d562745030d51c62

## Project boundaryとbase contract

OpenAPI contractは/v1/projects/{project_id}配下にproject operationを公開します。committed public data-plane contractにはtop-level POST /v1/projects operationはありません。project_idがproject workspaceを選び、scope、bucket、team_id、pathはauthorizationとfiltering fieldとして残ります。X-API-Key headerで認証し、選択したproject/teamを認可されたtokenを使ってください。

- Context: POST /v1/projects/{project_id}/context。
- Todos: POST /v1/projects/{project_id}/todos。GET /v1/projects/{project_id}/todos。
- Todo transition: 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。
- Decision: POST /v1/projects/{project_id}/decisions。GET /v1/projects/{project_id}/decisions。
- Decision transition: 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。
- Maintenance: 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。

## Project context requestとresponse schema

POST /v1/projects/{project_id}/contextはProjectContextRequestを受け取ります。bucketのdefaultは%、team_idとdurable_queryはnullable、max_itemsのdefaultは100（1..1000）、max_tokensのdefaultは8000（1..50000）、include_durable_contextのdefaultはtrue、recent_hoursのdefaultは168（1..8760）です。ProjectContextPackResponseを返し、required fieldはproject_scope、assembled_at、budgetです。さらにproject_state、agent_states、action_items、decisions、timeline、recent_memories、durable_context、governance_caveats、missing_domains、incomplete_domains、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
}
```

## Project todoとdecision

Todoの作成では、required contentとoptionalなpriority、assignee_agent_id、depends_on、due_at、source_memory_id、metadata、bucket（default work）、scope、path、team_idを持つProjectTodoCreateRequestを受け取り、ProjectTodoを返します。GET todosはoptionalなstatusとteam_idを受け取り、ProjectTodoのarrayを返します。Decisionの作成では、required contextとoptionalなoptions、impact_level、proposed_by_agent_id、supersedes、source_memory_id、due_at、metadata、bucket（default work）、scope、path、team_idを持つProjectDecisionCreateRequestを受け取り、ProjectDecisionを返します。Decision listingはstatusとteam_idを受け取ります。

```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"]
}
```

## Todoとdecisionのlifecycle operation

OpenAPIのlifecycle operationは、supersedeがProjectDecisionのarrayを返す場合を除き、ProjectTodoまたはProjectDecisionを返します。ProjectTodoにはtodo_id、project_id、contentが必要で、その他の宣言済みfieldには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、extra_metadataがあります。ProjectDecisionにはdecision_id、project_id、contentが必要で、その他の宣言済みfieldには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、extra_metadataがあります。POST /v1/projects/{project_id}/decisions/{decision_id}/resolveは{resolution: string}を要求し、POST /v1/projects/{project_id}/decisions/{decision_id}/supersedeはcontextを要求してoptions、impact_level、proposed_by_agent_id、resolution_noteを受け取ります。reopenにrequest bodyはありません。Todoのaccept、unblock、その他の多くのtransitionはOpenAPI上request bodyを持たず、assignは{assignee_agent_id: string}、blockは{reason: string}、completeは{note: string|null}、cancelは{reason: string|null}を受け取ります。

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

## Project maintenance、pagination、error、limit

MaintenanceはOpenAPIのpublic /v1/projects surfaceの一部です。settings GET/PATCHはProjectMaintenanceSettingsResponseとProjectMaintenanceSettingsPatchRequestを使い、report GETはteam_idとscan_limit（default 1000、range 1..5000）を受けてProjectMaintenanceReportResponseを返します。execute POSTはactions（1..4 strings）、target_ids（最大500 ids）、confirm_all_matching（default false）を持つProjectMaintenanceExecuteRequestを受け取り、ProjectMaintenanceExecuteResponseを返します。Project todo/decision listはstatus/team_id filterを公開しますが、OpenAPIにはpageやcursor parameterがありません。列挙したすべてのoperationは422にHTTPValidationErrorを宣言します。runtime authorization errorと設定可能な60秒rate limitはAuthenticationおよびMemory API pageと共通で、OpenAPIにはproject-specific quotaが公開されていません。