Agents

List agent assignments

GET /v1/agent-assignments · listAgentAssignments

Private account-owned assignment. Creation records intent; only the selected, account-authorized host may execute through its session ledger after its own permission checks. IDs and command IDs survive restart. Retain request_id and exact inputs for retry; changed inputs conflict. Follow-up and stop are intents, not proof of consumption or cancellation. Archive is refused while queued/running. Reports are what a host the account authorized says happened, not proof we checked, and require the selected host ID and exact expected revision. The transcript remains on coder-sync under chat; result is only a bounded summary. Limits: 256 unarchived assignments, 128 commands per assignment, 4096 saved mutations and 4 MiB per account including history. Maximum JSON body 96 KiB; list pages contain at most eight assignments.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Parameters

Response

200 — Account-owned assignment or page, no-store/private.

Type: AgentAssignmentPage

Errors

Example

curl 'https://api.openagents.com/v1/agent-assignments' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

In the Rust SDK

• Agents::assignments

Create agent assignment

POST /v1/agent-assignments · createAgentAssignment

Private account-owned assignment. Creation records intent; only the selected, account-authorized host may execute through its session ledger after its own permission checks. IDs and command IDs survive restart. Retain request_id and exact inputs for retry; changed inputs conflict. Follow-up and stop are intents, not proof of consumption or cancellation. Archive is refused while queued/running. Reports are what a host the account authorized says happened, not proof we checked, and require the selected host ID and exact expected revision. The transcript remains on coder-sync under chat; result is only a bounded summary. Limits: 256 unarchived assignments, 128 commands per assignment, 4096 saved mutations and 4 MiB per account including history. Maximum JSON body 96 KiB; list pages contain at most eight assignments.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Request body

Content type: application/json

Type: AgentAssignmentCreate

Response

200 — Account-owned assignment or page, no-store/private.

Type: AgentAssignmentValue

Errors

Example

curl -X POST 'https://api.openagents.com/v1/agent-assignments' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "request_id": "string",
  "spec": {
    "agent": "string",
    "agent_revision": 1,
    "host": "string",
    "task": "string"
  }
}'

In the Rust SDK

• Agents::assign

Get agent assignment

GET /v1/agent-assignments/{id} · getAgentAssignment

Private account-owned assignment. Creation records intent; only the selected, account-authorized host may execute through its session ledger after its own permission checks. IDs and command IDs survive restart. Retain request_id and exact inputs for retry; changed inputs conflict. Follow-up and stop are intents, not proof of consumption or cancellation. Archive is refused while queued/running. Reports are what a host the account authorized says happened, not proof we checked, and require the selected host ID and exact expected revision. The transcript remains on coder-sync under chat; result is only a bounded summary. Limits: 256 unarchived assignments, 128 commands per assignment, 4096 saved mutations and 4 MiB per account including history. Maximum JSON body 96 KiB; list pages contain at most eight assignments.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Parameters

Response

200 — Account-owned assignment or page, no-store/private.

Type: AgentAssignmentValue

Errors

Example

curl 'https://api.openagents.com/v1/agent-assignments/{id}' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

In the Rust SDK

• Agents::assignment

Command agent assignment

POST /v1/agent-assignments/{id}/commands · commandAgentAssignment

Private account-owned assignment. Creation records intent; only the selected, account-authorized host may execute through its session ledger after its own permission checks. IDs and command IDs survive restart. Retain request_id and exact inputs for retry; changed inputs conflict. Follow-up and stop are intents, not proof of consumption or cancellation. Archive is refused while queued/running. Reports are what a host the account authorized says happened, not proof we checked, and require the selected host ID and exact expected revision. The transcript remains on coder-sync under chat; result is only a bounded summary. Limits: 256 unarchived assignments, 128 commands per assignment, 4096 saved mutations and 4 MiB per account including history. Maximum JSON body 96 KiB; list pages contain at most eight assignments.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Parameters

Request body

Content type: application/json

Type: AgentAssignmentCommand

Response

200 — Account-owned assignment or page, no-store/private.

Type: AgentAssignmentValue

Errors

Example

curl -X POST 'https://api.openagents.com/v1/agent-assignments/{id}/commands' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "request_id": "string",
  "action": {
    "action": "follow_up",
    "text": "string"
  }
}'

In the Rust SDK

• Agents::command

Report agent assignment

POST /v1/agent-assignments/{id}/report · reportAgentAssignment

Private account-owned assignment. Creation records intent; only the selected, account-authorized host may execute through its session ledger after its own permission checks. IDs and command IDs survive restart. Retain request_id and exact inputs for retry; changed inputs conflict. Follow-up and stop are intents, not proof of consumption or cancellation. Archive is refused while queued/running. Reports are what a host the account authorized says happened, not proof we checked, and require the selected host ID and exact expected revision. The transcript remains on coder-sync under chat; result is only a bounded summary. Limits: 256 unarchived assignments, 128 commands per assignment, 4096 saved mutations and 4 MiB per account including history. Maximum JSON body 96 KiB; list pages contain at most eight assignments.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Parameters

Request body

Content type: application/json

Type: AgentAssignmentReport

Response

200 — Account-owned assignment or page, no-store/private.

Type: AgentAssignmentValue

Errors

Example

curl -X POST 'https://api.openagents.com/v1/agent-assignments/{id}/report' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "request_id": "string",
  "host": "string",
  "expected_revision": 1,
  "state": "running"
}'

In the Rust SDK

• Agents::report

List agent definitions

GET /v1/agent-definitions · listAgentDefinitions

Private account-owned definition. Does not install or execute an agent. We keep each change's request_id: a retry with the same inputs returns the first result, and changed inputs conflict. Deleted definitions and old revisions remain readable to their owner. Lists exclude deleted definitions and continue in ID order. Capacity is 128 active definitions, 4096 mutations, and 4 MiB per account, including history; no automatic history pruning. Updates and deletion require expected_revision. Maximum JSON body is 24 KiB.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Parameters

Response

200 — The account-owned result; no-store, private.

Type: CustomAgentPage

Errors

Example

curl 'https://api.openagents.com/v1/agent-definitions' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

In the Rust SDK

• Agents::list

Create agent definition

POST /v1/agent-definitions · createAgentDefinition

Private account-owned definition. Does not install or execute an agent. We keep each change's request_id: a retry with the same inputs returns the first result, and changed inputs conflict. Deleted definitions and old revisions remain readable to their owner. Lists exclude deleted definitions and continue in ID order. Capacity is 128 active definitions, 4096 mutations, and 4 MiB per account, including history; no automatic history pruning. Updates and deletion require expected_revision. Maximum JSON body is 24 KiB.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Request body

Content type: application/json

Type: CustomAgentCreate

Response

200 — The account-owned result; no-store, private.

Type: CustomAgentDefinition

Errors

Example

curl -X POST 'https://api.openagents.com/v1/agent-definitions' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "request_id": "string",
  "spec": {
    "name": "string",
    "description": "string",
    "instructions": "string",
    "runtime": "string",
    "model": "string",
    "access": "host_default"
  }
}'

In the Rust SDK

• Agents::create

Get agent definition

GET /v1/agent-definitions/{id} · getAgentDefinition

Private account-owned definition. Does not install or execute an agent. We keep each change's request_id: a retry with the same inputs returns the first result, and changed inputs conflict. Deleted definitions and old revisions remain readable to their owner. Lists exclude deleted definitions and continue in ID order. Capacity is 128 active definitions, 4096 mutations, and 4 MiB per account, including history; no automatic history pruning. Updates and deletion require expected_revision. Maximum JSON body is 24 KiB.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Parameters

Response

200 — The account-owned result; no-store, private.

Type: CustomAgentDefinition

Errors

Example

curl 'https://api.openagents.com/v1/agent-definitions/{id}' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

In the Rust SDK

• Agents::get

Update agent definition

PUT /v1/agent-definitions/{id} · updateAgentDefinition

Private account-owned definition. Does not install or execute an agent. We keep each change's request_id: a retry with the same inputs returns the first result, and changed inputs conflict. Deleted definitions and old revisions remain readable to their owner. Lists exclude deleted definitions and continue in ID order. Capacity is 128 active definitions, 4096 mutations, and 4 MiB per account, including history; no automatic history pruning. Updates and deletion require expected_revision. Maximum JSON body is 24 KiB.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Parameters

Request body

Content type: application/json

Type: CustomAgentUpdate

Response

200 — The account-owned result; no-store, private.

Type: CustomAgentDefinition

Errors

Example

curl -X PUT 'https://api.openagents.com/v1/agent-definitions/{id}' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "request_id": "string",
  "expected_revision": 1,
  "spec": {
    "name": "string",
    "description": "string",
    "instructions": "string",
    "runtime": "string",
    "model": "string",
    "access": "host_default"
  }
}'

In the Rust SDK

• Agents::update

Delete agent definition

DELETE /v1/agent-definitions/{id} · deleteAgentDefinition

Private account-owned definition. Does not install or execute an agent. We keep each change's request_id: a retry with the same inputs returns the first result, and changed inputs conflict. Deleted definitions and old revisions remain readable to their owner. Lists exclude deleted definitions and continue in ID order. Capacity is 128 active definitions, 4096 mutations, and 4 MiB per account, including history; no automatic history pruning. Updates and deletion require expected_revision. Maximum JSON body is 24 KiB.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Parameters

Request body

Content type: application/json

Type: CustomAgentDelete

Response

200 — The account-owned result; no-store, private.

Type: CustomAgentDefinition

Errors

Example

curl -X DELETE 'https://api.openagents.com/v1/agent-definitions/{id}' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "request_id": "string",
  "expected_revision": 1
}'

In the Rust SDK

• Agents::delete