# Universal API endpoints

Required inputs and documented response codes are summarized here. For optional parameters, full schemas, and response bodies, use the [Universal OpenAPI contract](https://swarm.services/guide/connect/openapi.json). Listed codes are not an exhaustive error policy.

> [API guide](https://swarm.services/guide/api.md) · [Documentation index](https://swarm.services/guide/llms.txt) · [Web reference](https://swarm.services/guide/api/reference/universal-api)

[Download OpenAPI JSON](https://swarm.services/guide/connect/openapi.json): The complete request, response and schema contract for scoped Universal connections.

## GET /v1/agent-action-traces

List agent action traces

Required: none declared. Documented responses: 200.

## GET /v1/agent-action-traces/{traceId}

Get agent action trace

Required: traceId (path). Documented responses: 200.

## GET /v1/approval-requests

List approval requests

Required: none declared. Documented responses: 200.

## GET /v1/approval-requests/{requestId}

Get approval request

Required: requestId (path). Documented responses: 200.

## GET /v1/artifacts

List artifacts

Required: none declared. Documented responses: 200.

## POST /v1/artifacts

Create artifact

Required: Idempotency-Key (header), space_id (JSON body), kind (JSON body), media_type (JSON body), body (JSON body). Documented responses: 201.

## GET /v1/artifacts/{artifactId}

Get artifact

Required: artifactId (path). Documented responses: 200.

## GET /v1/artifacts/{artifactId}/content

Get artifact content

Required: artifactId (path). Documented responses: 200, 410.

## GET /v1/artifacts/{artifactId}/sources

Read accessible cross-Space source references

Required: artifactId (path). Documented responses: 200.

## GET /v1/conversation-threads/{threadId}/anchors

List conversation thread anchors

Required: threadId (path). Documented responses: 200.

## GET /v1/conversation-threads/{threadId}/entries

List conversation thread entries

Required: threadId (path). Documented responses: 200.

## POST /v1/conversation-threads/{threadId}/mark-read

Mark a conversation thread read

Required: Idempotency-Key (header), threadId (path). Documented responses: 200.

## GET /v1/conversation-threads/{threadId}/view

Get a conversation thread view

Required: threadId (path). Documented responses: 200.

## GET /v1/evaluations

List evaluations

Required: none declared. Documented responses: 200.

## POST /v1/evaluations

Create evaluation

Required: Idempotency-Key (header), space_id (JSON body), summary (JSON body). Documented responses: 201.

## GET /v1/evaluations/{evaluationId}

Get evaluation

Required: evaluationId (path). Documented responses: 200.

## GET /v1/execution-policies

List execution policies

Required: none declared. Documented responses: 200.

## GET /v1/execution-policies/{policyId}

Get execution policy

Required: policyId (path). Documented responses: 200.

## POST /v1/foundation/run-groups/{runGroupId}:cancel

Cancel a canonical Run Group

Required: runGroupId (path), Idempotency-Key (header). Documented responses: 200.

## POST /v1/foundation/run-groups/{runGroupId}:pause

Pause a canonical Run Group

Required: runGroupId (path), Idempotency-Key (header). Documented responses: 200.

## POST /v1/foundation/run-groups/{runGroupId}:resume

Resume a canonical Run Group

Required: runGroupId (path), Idempotency-Key (header). Documented responses: 200.

## POST /v1/foundation/run-groups/{runGroupId}/runs

Create a Main Run in a canonical Run Group

Required: runGroupId (path), Idempotency-Key (header). Documented responses: 201.

## POST /v1/foundation/runs/{runId}/subruns

Spawn a canonical Subrun

Required: runId (path), Idempotency-Key (header), spawn_reason_key (JSON body). Documented responses: 201.

## POST /v1/foundation/spaces/{spaceId}/run-groups

Create a canonical Run Group

Required: spaceId (path), Idempotency-Key (header). Documented responses: 201.

## POST /v1/foundation/spaces/{spaceId}/runs:launch

Launch a freeform Main Run without requiring a Task

Required: spaceId (path), Idempotency-Key (header). Documented responses: 201.

## POST /v1/foundation/tasks/{taskId}/runs:launch

Launch a Main Run for an optional planning Task

Required: taskId (path), Idempotency-Key (header). Documented responses: 201.

## GET /v1/run-leases/{leaseId}

Get run lease

Required: leaseId (path). Documented responses: 200.

## POST /v1/run-leases/{leaseId}/release

Release run lease

Required: Idempotency-Key (header), leaseId (path). Documented responses: 200.

## POST /v1/run-leases/{leaseId}/renew

Renew run lease

Required: Idempotency-Key (header), leaseId (path), ttl_seconds (JSON body). Documented responses: 200.

## GET /v1/runs

List runs

Required: none declared. Documented responses: 200.

## GET /v1/runs/{runId}

Get run

Required: runId (path). Documented responses: 200.

## POST /v1/runs/{runId}/acquire

Claim one agent-executed Run

Required: Idempotency-Key (header), runId (path). Documented responses: 201, 403, 409.

## POST /v1/runs/{runId}/complete

Complete run

Required: Idempotency-Key (header), runId (path), lease_id (JSON body), outcome (JSON body). Documented responses: 200.

## GET /v1/runs/{runId}/context

Get resolved run context

Required: runId (path). Documented responses: 200.

## POST /v1/runs/{runId}/start

Start run

Required: Idempotency-Key (header), runId (path), lease_id (JSON body). Documented responses: 200.

## POST /v1/runs/{runId}/stop

Request run stop

Required: Idempotency-Key (header), runId (path), JSON body (request). Documented responses: 200.

## GET /v1/scheduler-policies

List scheduler policies

Required: none declared. Documented responses: 200.

## POST /v1/scheduler-policies

Create scheduler policy

Required: Idempotency-Key (header), space_id (JSON body), name (JSON body), trigger_key (JSON body), trigger_config (JSON body), target_task_id (JSON body). Documented responses: 201.

## GET /v1/scheduler-policies/{policyId}

Get scheduler policy

Required: policyId (path). Documented responses: 200.

## POST /v1/scheduler-policies/{policyId}/disable

Disable scheduler policy

Required: Idempotency-Key (header), policyId (path). Documented responses: 200.

## POST /v1/scheduler-policies/{policyId}/reconcile

Reconcile scheduler policy

Required: Idempotency-Key (header), policyId (path), JSON body (request). Documented responses: 200.

## POST /v1/scheduler-policies/{policyId}/update

Update scheduler policy

Required: Idempotency-Key (header), policyId (path), name (JSON body), trigger_key (JSON body), trigger_config (JSON body), target_task_id (JSON body). Documented responses: 200.

## GET /v1/search

Search authorized Swarm records

Required: q (query). Documented responses: 200.

## GET /v1/spaces

List spaces

Required: none declared. Documented responses: 200.

## POST /v1/spaces

Create space

Required: Idempotency-Key (header), entity_id (JSON body), key (JSON body), name (JSON body). Documented responses: 201.

## GET /v1/spaces/{spaceId}

Get space

Required: spaceId (path). Documented responses: 200.

## GET /v1/spaces/{spaceId}/action-intelligence

Get bounded action intelligence summary for a space

Required: spaceId (path). Documented responses: 200.

## POST /v1/spaces/{spaceId}/agent-action-traces/batches

Append a bounded client-reported Agent action trace batch

Required: spaceId (path), Idempotency-Key (header), trace_root_id (JSON body), events (JSON body). Documented responses: 200, 201.

## GET /v1/spaces/{spaceId}/agent-participants

List current Space execution participants

Required: spaceId (path). Documented responses: 200, 503.

## POST /v1/spaces/{spaceId}/agent-requests

Ask an available Space agent to start work from a human request

Required: Idempotency-Key (header), spaceId (path), body_text (JSON body). Documented responses: 202.

## GET /v1/spaces/{spaceId}/answer-contract

Get the Space Ask answer contract

Required: spaceId (path). Documented responses: 200.

## GET /v1/spaces/{spaceId}/answers

List persisted space answers

Required: spaceId (path). Documented responses: 200.

## GET /v1/spaces/{spaceId}/answers/{answerId}

Get a persisted space answer

Required: spaceId (path), answerId (path). Documented responses: 200.

## POST /v1/spaces/{spaceId}/ask

Ask a space from visible memory

Required: spaceId (path), Idempotency-Key (header), question (JSON body). Documented responses: 201.

## POST /v1/spaces/{spaceId}/checkpoints

Publish one reviewed durable checkpoint

Required: spaceId (path), Idempotency-Key (header), checkpoint_kind_key (JSON body), title (JSON body). Documented responses: 200, 201.

## POST /v1/spaces/{spaceId}/context-links

Attach a canonical Space context link

Required: spaceId (path), Idempotency-Key (header). Documented responses: 201.

## POST /v1/spaces/{spaceId}/context-links/{contextLinkId}/detach

Detach a canonical Space context link

Required: spaceId (path), contextLinkId (path), Idempotency-Key (header). Documented responses: 200.

## POST /v1/spaces/{spaceId}/context-pack

Build a bounded context pack for a space

Required: spaceId (path). Documented responses: 200.

## POST /v1/spaces/{spaceId}/context-plan/view

Explain the bounded context plan for composer input without persistence or a model call

Required: spaceId (path), composer_text (JSON body). Documented responses: 200, 400, 403, 413.

## GET /v1/spaces/{spaceId}/conversation

Get the primary Space conversation thread

Required: spaceId (path). Documented responses: 200.

## POST /v1/spaces/{spaceId}/conversation/entries

Create an authorized conversation entry

Required: Idempotency-Key (header), spaceId (path), JSON body (request). Documented responses: 201.

## GET /v1/spaces/{spaceId}/conversation/updates

Get an authorized Space conversation revision hint

Required: spaceId (path). Documented responses: 200.

## GET /v1/spaces/{spaceId}/decision-graph

Get the derived space decision graph

Required: spaceId (path). Documented responses: 200.

## POST /v1/spaces/{spaceId}/executor-capabilities

Declare this connection's execution capabilities

Required: Idempotency-Key (header), spaceId (path), JSON body (request). Documented responses: 200, 403.

## POST /v1/spaces/{spaceId}/handoff-preview/view

Compile a bounded, Permit-filtered handoff preview without persistence or a model call

Required: spaceId (path), source_resource_ref (JSON body). Documented responses: 200, 400, 403, 413.

## GET /v1/spaces/{spaceId}/operations

List Space intelligence operations

Required: spaceId (path). Documented responses: 200.

## GET /v1/spaces/{spaceId}/operations/{operationId}

Get a Space intelligence operation

Required: spaceId (path), operationId (path). Documented responses: 200.

## POST /v1/spaces/{spaceId}/runs:claim-next

Claim the next eligible agent-executed Run

Required: Idempotency-Key (header), spaceId (path). Documented responses: 200, 409.

## GET /v1/spaces/{spaceId}/work-contract

Get the Space work contract

Required: spaceId (path). Documented responses: 200.

## GET /v1/task-dependencies

List task dependencies

Required: none declared. Documented responses: 200.

## POST /v1/task-dependencies

Create task dependency

Required: Idempotency-Key (header), space_id (JSON body), predecessor_task_id (JSON body), successor_task_id (JSON body). Documented responses: 201.

## GET /v1/task-dependencies/{dependencyId}

Get task dependency

Required: dependencyId (path). Documented responses: 200.

## GET /v1/tasks

List tasks

Required: none declared. Documented responses: 200.

## POST /v1/tasks

Create task

Required: Idempotency-Key (header), space_id (JSON body), title (JSON body), description (JSON body). Documented responses: 201.

## GET /v1/tasks/{taskId}

Get task

Required: taskId (path). Documented responses: 200.

## PATCH /v1/tasks/{taskId}

Update an unexecuted task

Required: Idempotency-Key (header), taskId (path), title (JSON body), description (JSON body). Documented responses: 200.

## POST /v1/tasks/{taskId}/cancel

Clear an unexecuted task

Required: Idempotency-Key (header), taskId (path). Documented responses: 200.

## POST /v1/universal-connection-requests

Request human consent for an HTTPS app or agent

Required: name (JSON body), access_profile_key (JSON body). Documented responses: 201, 400, 413, 429, 503.

## POST /v1/universal-connection-requests/{requestId}/exchange

Collect an approved Universal connection

Required: requestId (path), device_code (JSON body). Documented responses: 200, 400, 413, 429.

## POST /v1/universal-connections/{connectionId}/renew

Keep an approved Universal connection usable without repeating setup

Required: connectionId (path), Idempotency-Key (header), refresh_token (JSON body). Documented responses: 200, 400, 413, 429.