control plane api

Captures

Read access to the evidence: list capture objects under a project (optionally narrowed to one workload), then fetch any single envelope by request id.

Endpoints

method & path	does
`GET /customer/v1/orgs/:org_id/projects/:project_id/captures`	List capture objects for the whole project, newest pages first. Cursor-paginated (limit 1–100, default 25).
`GET .../projects/:project_id/workloads/:workload_id/captures`	Narrowed to one workload, newest first. The server scans backwards through the project's capture history within a per-request budget; a page with zero rows plus a cursor means "nothing matched back to scanned_through yet — continue with the cursor".
`GET .../projects/:project_id/captures/:request_id`	Fetch one full capture envelope by request id.
`POST /admin/v1/orgs/:org_id/projects/:project_id/workloads/:workload_id/captures/export`	Export original stored captures for one workload and an exact from/to window of up to 24 hours. Returns at most 1,000 download URLs per page, valid for one hour.

List item shape

list response (shape)

{
  "captures": [
    {
      "key": "org_.../proj_.../api_key_.../2026/06/12/0190....jsonl",
      "request_id": "0190a7c2-7e11-7cc3-a312-9f1b22d40e88",
      "uploaded": "2026-06-12T00:00:12Z",
      "size": 4821,
      "workos_org_id": "org_...",
      "workos_api_key_id": "api_key_..."   // which key sent it — your env discriminator
    }
  ],
  "truncated": true,
  "cursor": "opaque — pass back to get the next page",
  "scanned_through": "2026-06-01"  // workload list only: oldest day the scan examined
}

The storage key encodes the partition scheme — org, project, key, date — which is also your mental model for how capture volume is organized. The request_id matches the x-understudy-request-id the original response carried.

Detail

The single-capture endpoint returns the envelope — request and response bodies, resolution metadata, your tags. The field-by-field tour lives in Capture.

Export a time window

POST workload captures/export

{
  "from": "2026-09-01T12:00:00.000Z",
  "to": "2026-09-01T12:15:00.000Z"
}

The start is inclusive and the end exclusive. The window must be positive, at most 24 hours, and end in the past. Authenticate with your existing organization API key or access token. Each response contains canonical_scope, captures, and next_cursor. Each capture includes its request ID, storage key, timestamp, and a direct R2 download URL.

To continue, send the same window and request environment with cursor set to next_cursor and ingestion_cutoff copied from canonical_scope. Stop when next_cursor is null. Existing workload-day exports in the agent-tools CLI use this contract.