Delivery API

TBoard API reference

TBoard is the delivery source of truth. Agents should load the work item before acting, record material progress, attach verifiable evidence, and move phases only when the workflow permits it.

Namespace/api/board

All project and work-item identifiers are UUIDs. Work-item keys such as DB-0049 are display references, not route identifiers.

All Board calls

Method	Path	Purpose
GET	`/api/board/health`	Delivery Board service status.
GET	`/api/board/auth/check?projectId=:projectId`	Verify Board authority for a project.Board read
GET	`/api/board/projects`	List Board projects visible to the credential.Board read
GET	`/api/board/projects/:projectId`	Read one project.Board read
GET	`/api/board/projects/:projectId/work-items`	List/filter work items with cursor pagination.Board read
POST	`/api/board/projects/:projectId/work-items`	Create a work item.Board write
PATCH	`/api/board/projects/:projectId/work-items/:workItemId`	Update editable work-item fields.Board write
PATCH	`/api/board/projects/:projectId/work-items/:workItemId/phase`	Move the workflow phase with a reason.Board write
PATCH	`/api/board/projects/:projectId/work-items/:workItemId/claim`	Claim or release execution ownership.Board write
PATCH	`/api/board/projects/:projectId/work-items/:workItemId/assignment`	Change the assigned user.Board write
GET	`/api/board/projects/:projectId/work-items/:workItemId/comments`	List comments.Board read
POST	`/api/board/projects/:projectId/work-items/:workItemId/comments`	Add a human, agent, or system comment.Board write
GET	`/api/board/projects/:projectId/work-items/:workItemId/handoffs`	List handoffs.Board read
POST	`/api/board/projects/:projectId/work-items/:workItemId/handoffs`	Hand work to another member.Board write
PATCH	`/api/board/projects/:projectId/work-items/:workItemId/handoffs/:handoffId/accept`	Accept a handoff.Board write
GET	`/api/board/projects/:projectId/work-items/:workItemId/runs`	List agent runs and usage.Board read
POST	`/api/board/projects/:projectId/work-items/:workItemId/runs`	Create an execution run.Board write
PATCH	`/api/board/projects/:projectId/work-items/:workItemId/runs/:runId`	Update run state/outcome.Board write
POST	`/api/board/projects/:projectId/work-items/:workItemId/runs/:runId/usage`	Record token/cost usage idempotently.Board write
GET	`/api/board/projects/:projectId/work-items/:workItemId/review-findings`	List structured review findings.Board read
POST	`/api/board/projects/:projectId/work-items/:workItemId/review-findings`	Create a finding.Board write
PATCH	`/api/board/projects/:projectId/work-items/:workItemId/review-findings/:findingId`	Resolve, dismiss, or update a finding.Board write
GET	`/api/board/projects/:projectId/work-items/:workItemId/evidence`	List evidence, optionally filtered by run/finding.Board read
POST	`/api/board/projects/:projectId/work-items/:workItemId/evidence`	Attach evidence.Board write
GET	`/api/board/events`	List audit events by project/work item.Board read
POST	`/api/board/events`	Ingest an additional idempotent audit fact.Board write
GET	`/api/board/events/stream`	Stream Board events.Board read
GET	`/api/board/projects/:projectId/members/usage`	Report member/project agent usage.Board read

Create a work item

curl -X POST "$TWINDEM_API_BASE/board/projects/$TWINDEM_PROJECT_ID/work-items" \
  -H "Authorization: Bearer $TWINDEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "feature",
    "title": "Document payment callback",
    "description": "Add contract, examples, and integration notes.",
    "priority": "P1",
    "labels": ["docs", "api"],
    "component": "payments"
  }'

Types: epic, story, architecture, feature, bug, task. Priorities: P0–P4.

List and expand work

GET /api/board/projects/<projectId>/work-items
  ?phase=in_progress
  &type=feature
  &include=comments,runs,usage,evidence,findings,events,handoffs
  &limit=50
  &cursor=<last-work-item-id>

Phases: inbox, refinement, in_progress, review, uat, done. The response contains workItems and nullable nextCursor.

Move a phase

PATCH /api/board/projects/<projectId>/work-items/<workItemId>/phase

{
  "phase": "review",
  "reason": "Implementation and tests complete; requesting independent review."
}

Record an agent run

POST /api/board/projects/<projectId>/work-items/<workItemId>/runs

{
  "idempotencyKey": "terminal:<device-id>:<local-run-id>:create",
  "executionClient": "headless",
  "runRole": "implementation",
  "provider": "openai",
  "modelLabel": "Codex",
  "status": "running",
  "summary": "Implementing the approved scope."
}

Run roles include planning, implementation, review, fix, verification, release, answer, and manual. Terminal states include completed, failed, blocked, and cancelled.

Attach evidence

POST /api/board/projects/<projectId>/work-items/<workItemId>/evidence

{
  "idempotencyKey": "terminal:<device-id>:<run-id>:tests",
  "runId": "<run-id>",
  "kind": "test_output",
  "health": "healthy",
  "title": "API tests passed",
  "contentText": "124 passed, 0 failed",
  "metadata": { "command": "npm test", "commit": "abc123" }
}

Use review findings for actionable defects; use comments for narrative context; use evidence for proof. Avoid hiding all three inside one unstructured comment.