API

What the API is for

From an end-user perspective, the API stores tenant-scoped work items and powers both the hosted website and the MCP workflow. It is hosted for you at https://api.traceops.dev. For setup, see setup.

• Base URL: `https://api.traceops.dev`.
• Most users only need work item endpoints plus their own key or token.
• The MCP server calls the same hosted API over HTTP.

Authentication

Use bearer authentication in user-facing API calls.

curl https://api.traceops.dev/api/workitems \
  -H "Authorization: Bearer <key>"

• Use `Authorization: Bearer <key>` in user-facing examples.
• If your account supports personal API keys, use one of those keys for MCP and direct API calls.

Endpoints

These are the API areas that matter to normal users.

• `GET /api/workitems` searches work items in your tenant and repository scope.
• `POST /api/workitems` creates one work item.
• `GET /api/workitems/next` returns the next actionable item.
• `GET /api/workitems/{workItemId}` returns one work item.
• `PATCH /api/workitems/{workItemId}/status` updates workflow status.
• `PATCH /api/workitems/{workItemId}/claim` claims a work item.
• `PATCH /api/workitems/{workItemId}/links` stores branch, commit, and PR metadata.
• For the work item model and lifecycle, see workitems.

Tenant context

Tenants are the access boundary. Your API calls and MCP workflow operate within the tenant your key or session can access.

• If you work only in your personal tenant, the hosted app can create that tenant during onboarding.
• If you need a shared tenant, a tenant admin must grant your membership.
• The website app and MCP server both use the same hosted API boundary.

Example requests

Use the hosted base URL in all user-facing examples.

curl "https://api.traceops.dev/api/workitems?repoId=AndersMaletzki/TraceOps.Dev-website&limit=5" \
  -H "Authorization: Bearer <key>"

curl https://api.traceops.dev/api/workitems \
  -X POST \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "repoId": "AndersMaletzki/TraceOps.Dev-website",
    "workItemType": "Issue",
    "category": "Documentation",
    "title": "Example work item",
    "description": "Created from the hosted API docs example.",
    "severity": "Low",
    "source": "manual",
    "createdBy": "your-name"
  }'

• Use `https://api.traceops.dev` as the API base URL.
• Use `https://api.traceops.dev/api` where the client expects the `/api` prefix in its configured base URL.
• For MCP configuration, see MCP docs.