Skip to content

API

View as Markdown

Use the CoAgent API to create and manage CoAgents, configure provider connections, and inspect execution. The reference below is generated from the published @socra/agent-api contract.

Authentication

Send an Account-scoped Socra access token in the Authorization: Bearer ACCESS_TOKEN header. Replace ACCESS_TOKEN with your token. Account owners and admins manage CoAgent resources; runtime-only operations require the CoAgent's own identity.

API paths use resource IDs. The CLI additionally resolves CoAgent usernames.

Execution and credentials

Lifecycle operations can complete asynchronously. Inspect the returned state before assuming the computer is ready. Secret responses contain metadata rather than stored values.

Read Events and execution before using mailbox outcomes to track work completion.

Base URL

https://agent.socra.cloud

Agents

A managed software worker with an Account identity and durable cloud sandbox.

Read own runtime settings

GET/v1/agents/runtime-settings

Query parameters

No query parameters

Response

4 fields

modelstringrequired
min length: 1 · max length: 128
reasoning_effortstring | nullrequired
runtime"codex" | "claude"optional
shared_connectionbooleanoptional

Read cached model catalog

GET/v1/agents/{agent_id}/models

Path parameters

agent_idcustomrequired

Query parameters

No query parameters

Response

2 fields

dataobject[]required
modelstringrequired
displayNamestringrequired
defaultReasoningEffortstringrequired
supportedReasoningEffortsobject[]required
reasoningEffortstringrequired
descriptionstringrequired
checked_atstring | nullrequired

Refresh available models

POST/v1/agents/{agent_id}/models/refresh

Path parameters

agent_idcustomrequired

Request body

No request body

Response

2 fields

dataobject[]required
modelstringrequired
displayNamestringrequired
defaultReasoningEffortstringrequired
supportedReasoningEffortsobject[]required
reasoningEffortstringrequired
descriptionstringrequired
checked_atstring | nullrequired

Read AI connection

GET/v1/agents/{agent_id}/connection

Path parameters

agent_idcustomrequired

Query parameters

No query parameters

Response

5 fields

shared_connectionstring | nulloptional
status"not_connected" | "connecting" | "connected" | "reconnect_required"required
checked_atstring | nullrequired
availablebooleanrequired
loginobject | nullrequired

Connect ChatGPT

POST/v1/agents/{agent_id}/connection

Path parameters

agent_idcustomrequired

Request body

No request body

Response

5 fields

shared_connectionstring | nulloptional
status"not_connected" | "connecting" | "connected" | "reconnect_required"required
checked_atstring | nullrequired
availablebooleanrequired
loginobject | nullrequired

Check AI connection

POST/v1/agents/{agent_id}/connection/check

Path parameters

agent_idcustomrequired

Request body

No request body

Response

5 fields

shared_connectionstring | nulloptional
status"not_connected" | "connecting" | "connected" | "reconnect_required"required
checked_atstring | nullrequired
availablebooleanrequired
loginobject | nullrequired

Sign out of ChatGPT

POST/v1/agents/{agent_id}/connection/disconnect

Path parameters

agent_idcustomrequired

Request body

No request body

Response

5 fields

shared_connectionstring | nulloptional
status"not_connected" | "connecting" | "connected" | "reconnect_required"required
checked_atstring | nullrequired
availablebooleanrequired
loginobject | nullrequired

Cancel ChatGPT sign-in

POST/v1/agents/{agent_id}/connection/cancel

Path parameters

agent_idcustomrequired

Request body

No request body

Response

5 fields

shared_connectionstring | nulloptional
status"not_connected" | "connecting" | "connected" | "reconnect_required"required
checked_atstring | nullrequired
availablebooleanrequired
loginobject | nullrequired

Pause work while retaining the paid seat and home

POST/v1/agents/{agent_id}/pause

Path parameters

agent_idcustomrequired

Request body

No request body

Response

24 fields

idcustomrequired
usernamestringrequired
ai_connectionstring | nulloptional
daily_input_tokensinteger | nullrequired
daily_output_tokensinteger | nullrequired
status"provisioning" | "sleeping" | "waking" | "upgrading" | "running" | "suspended" | "failed"required
billing_suspendedbooleanoptional
allowance_suspendedbooleanoptional
accountcustomrequired
principalcustom | nullrequired
computer_backend"sandbox" | "compute"optional
sandboxcustom | nullrequired
volumecustom | nullrequired
default: null
block_volumecustom | nulloptional
migration_sourcecustom | nulloptional
home_migration_verificationobject | nulloptional
runtime"codex" | "claude"required
modelstringrequired
default: "gpt-6-sol"
reasoning_effortstring | nullrequired
default: null
last_errorstring | nullrequired
home_storageobject | nulloptional
created_bycustomrequired
created_atcustomrequired
updated_atcustomrequired

Resume a manually paused Agent

POST/v1/agents/{agent_id}/resume

Path parameters

agent_idcustomrequired

Request body

No request body

Response

24 fields

idcustomrequired
usernamestringrequired
ai_connectionstring | nulloptional
daily_input_tokensinteger | nullrequired
daily_output_tokensinteger | nullrequired
status"provisioning" | "sleeping" | "waking" | "upgrading" | "running" | "suspended" | "failed"required
billing_suspendedbooleanoptional
allowance_suspendedbooleanoptional
accountcustomrequired
principalcustom | nullrequired
computer_backend"sandbox" | "compute"optional
sandboxcustom | nullrequired
volumecustom | nullrequired
default: null
block_volumecustom | nulloptional
migration_sourcecustom | nulloptional
home_migration_verificationobject | nulloptional
runtime"codex" | "claude"required
modelstringrequired
default: "gpt-6-sol"
reasoning_effortstring | nullrequired
default: null
last_errorstring | nullrequired
home_storageobject | nulloptional
created_bycustomrequired
created_atcustomrequired
updated_atcustomrequired

Resume Agent provisioning without buying another seat

POST/v1/agents/{agent_id}/provision

Path parameters

agent_idcustomrequired

Request body

No request body

Response

24 fields

idcustomrequired
usernamestringrequired
ai_connectionstring | nulloptional
daily_input_tokensinteger | nullrequired
daily_output_tokensinteger | nullrequired
status"provisioning" | "sleeping" | "waking" | "upgrading" | "running" | "suspended" | "failed"required
billing_suspendedbooleanoptional
allowance_suspendedbooleanoptional
accountcustomrequired
principalcustom | nullrequired
computer_backend"sandbox" | "compute"optional
sandboxcustom | nullrequired
volumecustom | nullrequired
default: null
block_volumecustom | nulloptional
migration_sourcecustom | nulloptional
home_migration_verificationobject | nulloptional
runtime"codex" | "claude"required
modelstringrequired
default: "gpt-6-sol"
reasoning_effortstring | nullrequired
default: null
last_errorstring | nullrequired
home_storageobject | nulloptional
created_bycustomrequired
created_atcustomrequired
updated_atcustomrequired

Read individual Agent seat usage

GET/v1/agents/{agent_id}/usage

Path parameters

agent_idcustomrequired

Query parameters

No query parameters

Response

object | null

object | null

Get available Agent seats

GET/v1/agents/capacity

Query parameters

No query parameters

Response

4 fields

billing_enabledbooleanrequired
workspace_usageobjectoptional
activebooleanrequired
eligiblebooleanrequired
capacityinteger | nullrequired
availableinteger | nullrequired

Create agent

POST/v1/agents

Request body

idempotency_keystringoptional
format: uuid · pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
usernamestringrequired
min length: 1 · max length: 64 · pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
runtime"codex" | "claude"optional
default: "codex"
daily_input_tokensinteger | nulloptional
daily_output_tokensinteger | nulloptional

Response

24 fields

idcustomrequired
usernamestringrequired
ai_connectionstring | nulloptional
daily_input_tokensinteger | nullrequired
daily_output_tokensinteger | nullrequired
status"provisioning" | "sleeping" | "waking" | "upgrading" | "running" | "suspended" | "failed"required
billing_suspendedbooleanoptional
allowance_suspendedbooleanoptional
accountcustomrequired
principalcustom | nullrequired
computer_backend"sandbox" | "compute"optional
sandboxcustom | nullrequired
volumecustom | nullrequired
default: null
block_volumecustom | nulloptional
migration_sourcecustom | nulloptional
home_migration_verificationobject | nulloptional
runtime"codex" | "claude"required
modelstringrequired
default: "gpt-6-sol"
reasoning_effortstring | nullrequired
default: null
last_errorstring | nullrequired
home_storageobject | nulloptional
created_bycustomrequired
created_atcustomrequired
updated_atcustomrequired

Update agent

PATCH/v1/agents/{agent_id}

Path parameters

agent_idcustomrequired

Request body

runtime"codex" | "claude"optional
usernamestringoptional
min length: 1 · max length: 64 · pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
modelstringoptional
min length: 1 · max length: 128
reasoning_effortstring | nulloptional
daily_input_tokensinteger | nulloptional
daily_output_tokensinteger | nulloptional

Response

24 fields

idcustomrequired
usernamestringrequired
ai_connectionstring | nulloptional
daily_input_tokensinteger | nullrequired
daily_output_tokensinteger | nullrequired
status"provisioning" | "sleeping" | "waking" | "upgrading" | "running" | "suspended" | "failed"required
billing_suspendedbooleanoptional
allowance_suspendedbooleanoptional
accountcustomrequired
principalcustom | nullrequired
computer_backend"sandbox" | "compute"optional
sandboxcustom | nullrequired
volumecustom | nullrequired
default: null
block_volumecustom | nulloptional
migration_sourcecustom | nulloptional
home_migration_verificationobject | nulloptional
runtime"codex" | "claude"required
modelstringrequired
default: "gpt-6-sol"
reasoning_effortstring | nullrequired
default: null
last_errorstring | nullrequired
home_storageobject | nulloptional
created_bycustomrequired
created_atcustomrequired
updated_atcustomrequired

List agents

GET/v1/agents

Query parameters

limitintegeroptional
min: 1 · max: 100
afterstringoptional

Response

2 fields

dataobject[]required
idcustomrequired
usernamestringrequired
ai_connectionstring | nulloptional
daily_input_tokensinteger | nullrequired
daily_output_tokensinteger | nullrequired
status"provisioning" | "sleeping" | "waking" | "upgrading" | "running" | "suspended" | "failed"required
billing_suspendedbooleanoptional
allowance_suspendedbooleanoptional
accountcustomrequired
principalcustom | nullrequired
computer_backend"sandbox" | "compute"optional
sandboxcustom | nullrequired
volumecustom | nullrequired
default: null
block_volumecustom | nulloptional
migration_sourcecustom | nulloptional
home_migration_verificationobject | nulloptional
runtime"codex" | "claude"required
modelstringrequired
default: "gpt-6-sol"
reasoning_effortstring | nullrequired
default: null
last_errorstring | nullrequired
home_storageobject | nulloptional
created_bycustomrequired
created_atcustomrequired
updated_atcustomrequired
has_morebooleanrequired

Get agent

GET/v1/agents/{agent_id}

Path parameters

agent_idcustomrequired

Query parameters

No query parameters

Response

24 fields

idcustomrequired
usernamestringrequired
ai_connectionstring | nulloptional
daily_input_tokensinteger | nullrequired
daily_output_tokensinteger | nullrequired
status"provisioning" | "sleeping" | "waking" | "upgrading" | "running" | "suspended" | "failed"required
billing_suspendedbooleanoptional
allowance_suspendedbooleanoptional
accountcustomrequired
principalcustom | nullrequired
computer_backend"sandbox" | "compute"optional
sandboxcustom | nullrequired
volumecustom | nullrequired
default: null
block_volumecustom | nulloptional
migration_sourcecustom | nulloptional
home_migration_verificationobject | nulloptional
runtime"codex" | "claude"required
modelstringrequired
default: "gpt-6-sol"
reasoning_effortstring | nullrequired
default: null
last_errorstring | nullrequired
home_storageobject | nulloptional
created_bycustomrequired
created_atcustomrequired
updated_atcustomrequired

Read agent activity

POST/v1/agents/{agent_id}/activity

Path parameters

agent_idcustomrequired

Request body

afterintegeroptional
default: 0 · min: 0 · max: 9007199254740991
recovery_onlybooleanoptional

Response

7 fields

recoveryobjectoptional
observed_atstringrequired
completed_atstringrequired
provider_retry_atstring | nullrequired
cooldown_activebooleanrequired
pendingobjectrequired
queuedintegerrequired
min: 0 · max: 9007199254740991
deliveredintegerrequired
min: 0 · max: 9007199254740991
aged_queuedintegerrequired
min: 0 · max: 9007199254740991
selection_eligiblebooleanrequired
selection_reason"deletion_pending" | "lifecycle_not_recoverable" | "provider_cooldown" | "no_pending_messages" | "running_without_aged_queued_message" | "eligible"required
worker_outcome"unknown"required
statestringrequired
detailstring | nullrequired
queuednumberrequired
active_messagestring | nullrequired
cursornumberrequired
eventsobject[]required
seqnumberrequired
atstringrequired
typestringrequired
textstringrequired
message_idstring | nullrequired

Wake agent

POST/v1/agents/{agent_id}/wake

Path parameters

agent_idcustomrequired

Request body

No request body

Response

24 fields

idcustomrequired
usernamestringrequired
ai_connectionstring | nulloptional
daily_input_tokensinteger | nullrequired
daily_output_tokensinteger | nullrequired
status"provisioning" | "sleeping" | "waking" | "upgrading" | "running" | "suspended" | "failed"required
billing_suspendedbooleanoptional
allowance_suspendedbooleanoptional
accountcustomrequired
principalcustom | nullrequired
computer_backend"sandbox" | "compute"optional
sandboxcustom | nullrequired
volumecustom | nullrequired
default: null
block_volumecustom | nulloptional
migration_sourcecustom | nulloptional
home_migration_verificationobject | nulloptional
runtime"codex" | "claude"required
modelstringrequired
default: "gpt-6-sol"
reasoning_effortstring | nullrequired
default: null
last_errorstring | nullrequired
home_storageobject | nulloptional
created_bycustomrequired
created_atcustomrequired
updated_atcustomrequired

Upgrade agent

POST/v1/agents/{agent_id}/upgrade

Path parameters

agent_idcustomrequired

Request body

No request body

Response

24 fields

idcustomrequired
usernamestringrequired
ai_connectionstring | nulloptional
daily_input_tokensinteger | nullrequired
daily_output_tokensinteger | nullrequired
status"provisioning" | "sleeping" | "waking" | "upgrading" | "running" | "suspended" | "failed"required
billing_suspendedbooleanoptional
allowance_suspendedbooleanoptional
accountcustomrequired
principalcustom | nullrequired
computer_backend"sandbox" | "compute"optional
sandboxcustom | nullrequired
volumecustom | nullrequired
default: null
block_volumecustom | nulloptional
migration_sourcecustom | nulloptional
home_migration_verificationobject | nulloptional
runtime"codex" | "claude"required
modelstringrequired
default: "gpt-6-sol"
reasoning_effortstring | nullrequired
default: null
last_errorstring | nullrequired
home_storageobject | nulloptional
created_bycustomrequired
created_atcustomrequired
updated_atcustomrequired

Delete agent

DELETE/v1/agents/{agent_id}

Path parameters

agent_idcustomrequired

Query parameters

No query parameters

Response

No response body

AI connections

Provider authentication stored independently of Agent computers. Credentials are never returned.

Create AI connection

POST/v1/connections

Request body

namestringrequired
min length: 1 · max length: 100
provider"chatgpt" | "claude"optional
default: "chatgpt"

Response

10 fields

idcustomrequired
namestringrequired
provider"chatgpt" | "claude"required
created_bycustomrequired
status"not_connected" | "connected" | "reconnect_required"required
provider_accountobject | nullrequired
verified_atcustom | nullrequired
loginobject | nullrequired
created_atcustomrequired
updated_atcustomrequired

List your AI connections

GET/v1/connections

Query parameters

No query parameters

Response

2 fields

dataobject[]required
idcustomrequired
namestringrequired
provider"chatgpt" | "claude"required
created_bycustomrequired
status"not_connected" | "connected" | "reconnect_required"required
provider_accountobject | nullrequired
verified_atcustom | nullrequired
loginobject | nullrequired
created_atcustomrequired
updated_atcustomrequired
has_morefalserequired

Get AI connection

GET/v1/connections/{id}

Path parameters

idcustomrequired

Query parameters

No query parameters

Response

10 fields

idcustomrequired
namestringrequired
provider"chatgpt" | "claude"required
created_bycustomrequired
status"not_connected" | "connected" | "reconnect_required"required
provider_accountobject | nullrequired
verified_atcustom | nullrequired
loginobject | nullrequired
created_atcustomrequired
updated_atcustomrequired

Connect Claude subscription token

POST/v1/connections/{id}/token

Path parameters

idcustomrequired

Request body

tokenstringrequired
min length: 20 · max length: 8192

Response

10 fields

idcustomrequired
namestringrequired
provider"chatgpt" | "claude"required
created_bycustomrequired
status"not_connected" | "connected" | "reconnect_required"required
provider_accountobject | nullrequired
verified_atcustom | nullrequired
loginobject | nullrequired
created_atcustomrequired
updated_atcustomrequired

Start provider sign-in

POST/v1/connections/{id}/login

Path parameters

idcustomrequired

Request body

No request body

Response

10 fields

idcustomrequired
namestringrequired
provider"chatgpt" | "claude"required
created_bycustomrequired
status"not_connected" | "connected" | "reconnect_required"required
provider_accountobject | nullrequired
verified_atcustom | nullrequired
loginobject | nullrequired
created_atcustomrequired
updated_atcustomrequired

Complete Claude browser sign-in

POST/v1/connections/{id}/code

Path parameters

idcustomrequired

Request body

attemptstringrequired
format: uuid · pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
codestringrequired
pattern: ^[A-Za-z0-9_.~#-]{1,4096}$

Response

10 fields

idcustomrequired
namestringrequired
provider"chatgpt" | "claude"required
created_bycustomrequired
status"not_connected" | "connected" | "reconnect_required"required
provider_accountobject | nullrequired
verified_atcustom | nullrequired
loginobject | nullrequired
created_atcustomrequired
updated_atcustomrequired

Cancel device login

POST/v1/connections/{id}/cancel

Path parameters

idcustomrequired

Request body

No request body

Response

10 fields

idcustomrequired
namestringrequired
provider"chatgpt" | "claude"required
created_bycustomrequired
status"not_connected" | "connected" | "reconnect_required"required
provider_accountobject | nullrequired
verified_atcustom | nullrequired
loginobject | nullrequired
created_atcustomrequired
updated_atcustomrequired

Verify and refresh AI connection

POST/v1/connections/{id}/verify

Path parameters

idcustomrequired

Request body

No request body

Response

10 fields

idcustomrequired
namestringrequired
provider"chatgpt" | "claude"required
created_bycustomrequired
status"not_connected" | "connected" | "reconnect_required"required
provider_accountobject | nullrequired
verified_atcustom | nullrequired
loginobject | nullrequired
created_atcustomrequired
updated_atcustomrequired

Disconnect AI connection

POST/v1/connections/{id}/disconnect

Path parameters

idcustomrequired

Request body

No request body

Response

10 fields

idcustomrequired
namestringrequired
provider"chatgpt" | "claude"required
created_bycustomrequired
status"not_connected" | "connected" | "reconnect_required"required
provider_accountobject | nullrequired
verified_atcustom | nullrequired
loginobject | nullrequired
created_atcustomrequired
updated_atcustomrequired

Assign connection to an idle Agent

POST/v1/connections/{id}/assign

Path parameters

idcustomrequired

Request body

agentcustomrequired

Response

10 fields

idcustomrequired
namestringrequired
provider"chatgpt" | "claude"required
created_bycustomrequired
status"not_connected" | "connected" | "reconnect_required"required
provider_accountobject | nullrequired
verified_atcustom | nullrequired
loginobject | nullrequired
created_atcustomrequired
updated_atcustomrequired

Remove connection from an idle Agent

POST/v1/connections/{id}/unassign

Path parameters

idcustomrequired

Request body

agentcustomrequired

Response

10 fields

idcustomrequired
namestringrequired
provider"chatgpt" | "claude"required
created_bycustomrequired
status"not_connected" | "connected" | "reconnect_required"required
provider_accountobject | nullrequired
verified_atcustom | nullrequired
loginobject | nullrequired
created_atcustomrequired
updated_atcustomrequired

Delete AI connection

DELETE/v1/connections/{id}

Path parameters

idcustomrequired

Query parameters

No query parameters

Response

No response body

Agent secrets

Write-only credentials injected into new Agent sessions.

Create Agent secret

POST/v1/agent-secrets

Request body

agent_idcustomrequired
namestringrequired
pattern: ^[A-Z][A-Z0-9_]{0,127}$
valuestringrequired
min length: 1 · max length: 4096

Response

6 fields

idcustomrequired
agent_idcustomrequired
namestringrequired
readybooleanrequired
created_atcustomrequired
updated_atcustomrequired

List Agent secrets

GET/v1/agent-secrets

Query parameters

agent_idcustomrequired

Response

2 fields

dataobject[]required
idcustomrequired
agent_idcustomrequired
namestringrequired
readybooleanrequired
created_atcustomrequired
updated_atcustomrequired
has_morefalserequired

Get Agent secret metadata

GET/v1/agent-secrets/{id}

Path parameters

idcustomrequired

Query parameters

No query parameters

Response

6 fields

idcustomrequired
agent_idcustomrequired
namestringrequired
readybooleanrequired
created_atcustomrequired
updated_atcustomrequired

Rotate Agent secret

PATCH/v1/agent-secrets/{id}

Path parameters

idcustomrequired

Request body

valuestringrequired
min length: 1 · max length: 4096

Response

6 fields

idcustomrequired
agent_idcustomrequired
namestringrequired
readybooleanrequired
created_atcustomrequired
updated_atcustomrequired

Delete Agent secret

DELETE/v1/agent-secrets/{id}

Path parameters

idcustomrequired

Query parameters

No query parameters

Response

No response body

Agent messages

A durable event delivered to one managed Agent context.

Sleep the current Agent when its mailbox is empty

POST/v1/messages/sleep

Request body

No request body

Response

1 field

sleepingbooleanrequired

List agent messages

GET/v1/messages

Query parameters

agent_idcustomrequired
status"queued" | "delivered" | "acknowledged"optional
limitintegeroptional
min: 1 · max: 100
afterstringoptional

Response

2 fields

dataobject[]required
idcustomrequired
agent_idcustomrequired
source_event_idstringrequired
sourcestringrequired
typestringrequired
subjectstringrequired
payloadobjectrequired
status"queued" | "delivered" | "acknowledged"required
delivered_atcustom | nullrequired
acknowledged_atcustom | nullrequired
outcome"succeeded" | "failed" | "canceled" | nullrequired
resultstring | nullrequired
errorstring | nullrequired
created_atcustomrequired
has_morebooleanrequired

Pull next agent message

POST/v1/messages/pull

Request body

in_flightcustom[]optional
max items: 1000

Response

object | null

object | null

Acknowledge agent message

POST/v1/messages/{message_id}/acknowledge

Path parameters

message_idcustomrequired

Request body

outcome"succeeded" | "failed" | "canceled"optional
default: "succeeded"
resultstring | nulloptional
errorstring | nulloptional

Response

14 fields

idcustomrequired
agent_idcustomrequired
source_event_idstringrequired
sourcestringrequired
typestringrequired
subjectstringrequired
payloadobjectrequired
status"queued" | "delivered" | "acknowledged"required
delivered_atcustom | nullrequired
acknowledged_atcustom | nullrequired
outcome"succeeded" | "failed" | "canceled" | nullrequired
resultstring | nullrequired
errorstring | nullrequired
created_atcustomrequired

Cancel agent message

POST/v1/messages/{message_id}/cancel

Path parameters

message_idcustomrequired

Request body

No request body

Response

14 fields

idcustomrequired
agent_idcustomrequired
source_event_idstringrequired
sourcestringrequired
typestringrequired
subjectstringrequired
payloadobjectrequired
status"queued" | "delivered" | "acknowledged"required
delivered_atcustom | nullrequired
acknowledged_atcustom | nullrequired
outcome"succeeded" | "failed" | "canceled" | nullrequired
resultstring | nullrequired
errorstring | nullrequired
created_atcustomrequired

Retry agent message

POST/v1/messages/{message_id}/retry

Path parameters

message_idcustomrequired

Request body

No request body

Response

14 fields

idcustomrequired
agent_idcustomrequired
source_event_idstringrequired
sourcestringrequired
typestringrequired
subjectstringrequired
payloadobjectrequired
status"queued" | "delivered" | "acknowledged"required
delivered_atcustom | nullrequired
acknowledged_atcustom | nullrequired
outcome"succeeded" | "failed" | "canceled" | nullrequired
resultstring | nullrequired
errorstring | nullrequired
created_atcustomrequired

Git hub connections

The GitHub App installation trusted by the current Account.

Get GitHub connection

GET/v1/github/connection

Query parameters

No query parameters

Response

7 fields

idcustomrequired
accountcustomrequired
github_account_idstringrequired
github_account_loginstringrequired
created_bycustomrequired
created_atcustomrequired
updated_atcustomrequired

Read approved GitHub installation capabilities

GET/v1/github/connection/capabilities

Query parameters

No query parameters

Response

3 fields

checked_atstringrequired
suspendedbooleanrequired
permissionsobjectrequired
contents"none" | "read" | "write"required
pull_requests"none" | "read" | "write"required
actions"none" | "read" | "write"required

Start GitHub connection

POST/v1/github/connection/start

Request body

No request body

Response

2 fields

installation_urlstringrequired
format: uri
expires_atcustomrequired

Disconnect GitHub

DELETE/v1/github/connection

Query parameters

No query parameters

Response

No response body

Repositories

A GitHub repository made available to managed Agents in an Account.

Add repository

POST/v1/repositories

Request body

full_namestringrequired
pattern: ^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$

Response

9 fields

idcustomrequired
accountcustomrequired
provider"github"required
external_idstringrequired
full_namestringrequired
pattern: ^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$
clone_urlstringrequired
format: uri
default_branchstringrequired
created_atcustomrequired
updated_atcustomrequired

List repositories

GET/v1/repositories

Query parameters

limitintegeroptional
min: 1 · max: 100

Response

2 fields

dataobject[]required
idcustomrequired
accountcustomrequired
provider"github"required
external_idstringrequired
full_namestringrequired
pattern: ^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$
clone_urlstringrequired
format: uri
default_branchstringrequired
created_atcustomrequired
updated_atcustomrequired
has_morebooleanrequired

Remove repository

DELETE/v1/repositories/{repository_id}

Path parameters

repository_idcustomrequired

Query parameters

No query parameters

Response

No response body

Repository grants

Permission for a managed Agent to use a repository.

Grant repository access

POST/v1/repository-grants

Request body

agentcustomrequired
repositorycustomrequired
permission"read" | "write"optional
default: "write"
actions_permission"read" | "write"optional

Response

7 fields

idcustomrequired
accountcustomrequired
agentcustomrequired
repositorycustomrequired
permission"read" | "write"required
actions_permission"read" | "write"required
default: "read"
created_atcustomrequired

List repository grants

GET/v1/repository-grants

Query parameters

agentcustomoptional

Response

2 fields

dataobject[]required
idcustomrequired
accountcustomrequired
agentcustomrequired
repositorycustomrequired
permission"read" | "write"required
actions_permission"read" | "write"required
default: "read"
created_atcustomrequired
has_morebooleanrequired

Revoke repository access

DELETE/v1/repository-grants/{grant_id}

Path parameters

grant_idcustomrequired

Query parameters

No query parameters

Response

No response body

Repository metadata discovery

Delegated metadata-only installed repository candidates, separate from source access.

Discover installed GitHub repository metadata

GET/v1/repository-discovery

Query parameters

pageintegeroptional
default: 1 · min: 1 · max: 1000000

Response

5 fields

provider"github"required
checked_atstringrequired
dataobject[]required
provider"github"required
provider_idstringrequired
pattern: ^\d+$
full_namestringrequired
canonical_urlstringrequired
format: uri
default_branchstringrequired
archivedbooleanrequired
total_countintegerrequired
min: 0 · max: 9007199254740991
next_pageinteger | nullrequired

Repository metadata delegations

Account administrator delegation to discover GitHub metadata without source grants.

Delegate GitHub metadata discovery

POST/v1/repository-discovery-delegations

Request body

agentcustomrequired

Response

3 fields

agentcustomrequired
provider"github"required
created_atcustomrequired

Read metadata discovery delegation

GET/v1/repository-discovery-delegations/{agent_id}

Path parameters

agent_idcustomrequired

Query parameters

No query parameters

Response

3 fields

agentcustomrequired
provider"github"required
created_atcustomrequired

Revoke metadata discovery delegation

DELETE/v1/repository-discovery-delegations/{agent_id}

Path parameters

agent_idcustomrequired

Query parameters

No query parameters

Response

No response body

See also