참조REST API프로젝트 API

REST API

프로젝트 API

project-scoped context와 handoff record를 이를 만든 agent workflow에 연결해 유지합니다.

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 기본값은 %, team_id와 durable_query는 nullable, max_items 기본값은 100(1..1000), max_tokens 기본값은 8000(1..50000), include_durable_context 기본값은 true, recent_hours 기본값은 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가 포함됩니다.

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를 받습니다.

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가 필요하며, 그 밖의 declared 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가 필요하며, 그 밖의 declared 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}을 받습니다.

{
  "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(up to 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와 configurable 60-second rate limit은 Authentication 및 Memory API page와 공유되며 project-specific quota는 OpenAPI에 공개되지 않습니다.

출처: MCP tool surface