Overviewالعربية
INTEGRATION CONTRACT

One API under /api and /api/v1

People use revocable account sessions and project memberships. Integrations send least-privilege Bearer service keys. /api/v1 rewrites to the same implementation.

01

Identity and capabilities

The account identifies a person and membership grants project capabilities; UI visibility is never authorization.

  • Person: sealed session cookie plus a server-verified selected project
  • Integration: Authorization: Bearer SERVICE_KEY
  • owner/editor/reviewer/viewer — named collaborator roles
  • srs:edit — restricted service editor
  • widget:write — issue/evidence and run-state submission
  • agent:execute — commands, credential lease, test results
  • read:demo — only when the demo is explicitly enabled
02

Project and SRS

Project sources, versions, and overlays.

  • GET/POST /api/account-projects
  • GET/PATCH /api/projects
  • GET /api/srs-graph and /api/srs-source-audit
  • GET /api/srs-story/:id and /api/srs-workflow/:id
  • POST/PATCH /api/story-edits
  • GET/POST /api/project-traceability and /api/validation-transfer
03

Quality and execution

Test planning, state, and results.

  • GET/POST/PATCH /api/test-commands
  • GET/POST /api/test-runs
  • GET/POST /api/run-state
  • POST /api/agent/plan and /api/agent/suite
  • GET/POST /api/project-scenarios
  • GET /api/route-catalog and /api/route-candidates
04

Issues, evidence, and health

Every issue and generated image remains project-scoped.

  • GET/POST /api/issues and PATCH /api/issues/:id
  • POST /api/issues/:id/attachments
  • GET/POST /api/ai-images for private project images
  • GET /api/files/:key through a signed path
  • GET/POST/PATCH /api/system-logs
  • GET /api/health and GET /api/ready
  • GET /api/project-handoff for machine-readable handoff