API
Use the Agent API to create and manage agents, 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 Agent resources; runtime-only operations require the agent's own identity.
API paths use resource IDs. The CLI additionally resolves agent 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.cloudAgents
A managed software worker with an Account identity and durable cloud sandbox.
Read own runtime settings
GET
/v1/agents/runtime-settingsQuery parameters
No query parameters
Response
2 fields
modelstringrequiredmin length: 1 · max length: 128reasoning_effortstring | nullrequiredRead cached model catalog
GET
/v1/agents/{agent_id}/modelsPath parameters
agent_idcustomrequiredQuery parameters
No query parameters
Response
2 fields
dataobject[]required
dataobject[]requiredmodelstringrequireddisplayNamestringrequireddefaultReasoningEffortstringrequiredsupportedReasoningEffortsobject[]required
supportedReasoningEffortsobject[]requiredreasoningEffortstringrequireddescriptionstringrequiredchecked_atstring | nullrequiredRefresh available models
POST
/v1/agents/{agent_id}/models/refreshPath parameters
agent_idcustomrequiredRequest body
No request body
Response
2 fields
dataobject[]required
dataobject[]requiredmodelstringrequireddisplayNamestringrequireddefaultReasoningEffortstringrequiredsupportedReasoningEffortsobject[]required
supportedReasoningEffortsobject[]requiredreasoningEffortstringrequireddescriptionstringrequiredchecked_atstring | nullrequiredRead AI connection
GET
/v1/agents/{agent_id}/connectionPath parameters
agent_idcustomrequiredQuery parameters
No query parameters
Response
4 fields
status"not_connected" | "connecting" | "connected" | "reconnect_required"requiredchecked_atstring | nullrequiredavailablebooleanrequiredloginobject | nullrequiredConnect ChatGPT
POST
/v1/agents/{agent_id}/connectionPath parameters
agent_idcustomrequiredRequest body
No request body
Response
4 fields
status"not_connected" | "connecting" | "connected" | "reconnect_required"requiredchecked_atstring | nullrequiredavailablebooleanrequiredloginobject | nullrequiredCheck AI connection
POST
/v1/agents/{agent_id}/connection/checkPath parameters
agent_idcustomrequiredRequest body
No request body
Response
4 fields
status"not_connected" | "connecting" | "connected" | "reconnect_required"requiredchecked_atstring | nullrequiredavailablebooleanrequiredloginobject | nullrequiredSign out of ChatGPT
POST
/v1/agents/{agent_id}/connection/disconnectPath parameters
agent_idcustomrequiredRequest body
No request body
Response
4 fields
status"not_connected" | "connecting" | "connected" | "reconnect_required"requiredchecked_atstring | nullrequiredavailablebooleanrequiredloginobject | nullrequiredCancel ChatGPT sign-in
POST
/v1/agents/{agent_id}/connection/cancelPath parameters
agent_idcustomrequiredRequest body
No request body
Response
4 fields
status"not_connected" | "connecting" | "connected" | "reconnect_required"requiredchecked_atstring | nullrequiredavailablebooleanrequiredloginobject | nullrequiredPause work while retaining the paid seat and home
POST
/v1/agents/{agent_id}/pausePath parameters
agent_idcustomrequiredRequest body
No request body
Response
17 fields
idcustomrequiredusernamestringrequireddaily_input_tokensinteger | nullrequireddaily_output_tokensinteger | nullrequiredstatus"provisioning" | "sleeping" | "waking" | "upgrading" | "running" | "suspended" | "failed"requiredbilling_suspendedbooleanoptionalallowance_suspendedbooleanoptionalaccountcustomrequiredprincipalcustom | nullrequiredsandboxcustom | nullrequiredruntime"codex" | "claude"requiredmodelstringrequireddefault: "gpt-6-sol"reasoning_effortstring | nullrequireddefault: nulllast_errorstring | nullrequiredcreated_bycustomrequiredcreated_atcustomrequiredupdated_atcustomrequiredResume a manually paused Agent
POST
/v1/agents/{agent_id}/resumePath parameters
agent_idcustomrequiredRequest body
No request body
Response
17 fields
idcustomrequiredusernamestringrequireddaily_input_tokensinteger | nullrequireddaily_output_tokensinteger | nullrequiredstatus"provisioning" | "sleeping" | "waking" | "upgrading" | "running" | "suspended" | "failed"requiredbilling_suspendedbooleanoptionalallowance_suspendedbooleanoptionalaccountcustomrequiredprincipalcustom | nullrequiredsandboxcustom | nullrequiredruntime"codex" | "claude"requiredmodelstringrequireddefault: "gpt-6-sol"reasoning_effortstring | nullrequireddefault: nulllast_errorstring | nullrequiredcreated_bycustomrequiredcreated_atcustomrequiredupdated_atcustomrequiredResume Agent provisioning without buying another seat
POST
/v1/agents/{agent_id}/provisionPath parameters
agent_idcustomrequiredRequest body
No request body
Response
17 fields
idcustomrequiredusernamestringrequireddaily_input_tokensinteger | nullrequireddaily_output_tokensinteger | nullrequiredstatus"provisioning" | "sleeping" | "waking" | "upgrading" | "running" | "suspended" | "failed"requiredbilling_suspendedbooleanoptionalallowance_suspendedbooleanoptionalaccountcustomrequiredprincipalcustom | nullrequiredsandboxcustom | nullrequiredruntime"codex" | "claude"requiredmodelstringrequireddefault: "gpt-6-sol"reasoning_effortstring | nullrequireddefault: nulllast_errorstring | nullrequiredcreated_bycustomrequiredcreated_atcustomrequiredupdated_atcustomrequiredRead individual Agent seat usage
GET
/v1/agents/{agent_id}/usagePath parameters
agent_idcustomrequiredQuery parameters
No query parameters
Response
object | null
object | null
Get available Agent seats
GET
/v1/agents/capacityQuery parameters
No query parameters
Response
3 fields
billing_enabledbooleanrequiredcapacityinteger | nullrequiredavailableinteger | nullrequiredCreate agent
POST
/v1/agentsRequest body
idempotency_keystringoptionalformat: 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)$usernamestringrequiredmin length: 1 · max length: 64 · pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$runtime"codex" | "claude"optionaldefault: "codex"daily_input_tokensinteger | nulloptionaldaily_output_tokensinteger | nulloptionalResponse
17 fields
idcustomrequiredusernamestringrequireddaily_input_tokensinteger | nullrequireddaily_output_tokensinteger | nullrequiredstatus"provisioning" | "sleeping" | "waking" | "upgrading" | "running" | "suspended" | "failed"requiredbilling_suspendedbooleanoptionalallowance_suspendedbooleanoptionalaccountcustomrequiredprincipalcustom | nullrequiredsandboxcustom | nullrequiredruntime"codex" | "claude"requiredmodelstringrequireddefault: "gpt-6-sol"reasoning_effortstring | nullrequireddefault: nulllast_errorstring | nullrequiredcreated_bycustomrequiredcreated_atcustomrequiredupdated_atcustomrequiredUpdate agent
PATCH
/v1/agents/{agent_id}Path parameters
agent_idcustomrequiredRequest body
usernamestringoptionalmin length: 1 · max length: 64 · pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$modelstringoptionalmin length: 1 · max length: 128reasoning_effortstring | nulloptionaldaily_input_tokensinteger | nulloptionaldaily_output_tokensinteger | nulloptionalResponse
17 fields
idcustomrequiredusernamestringrequireddaily_input_tokensinteger | nullrequireddaily_output_tokensinteger | nullrequiredstatus"provisioning" | "sleeping" | "waking" | "upgrading" | "running" | "suspended" | "failed"requiredbilling_suspendedbooleanoptionalallowance_suspendedbooleanoptionalaccountcustomrequiredprincipalcustom | nullrequiredsandboxcustom | nullrequiredruntime"codex" | "claude"requiredmodelstringrequireddefault: "gpt-6-sol"reasoning_effortstring | nullrequireddefault: nulllast_errorstring | nullrequiredcreated_bycustomrequiredcreated_atcustomrequiredupdated_atcustomrequiredList agents
GET
/v1/agentsQuery parameters
limitintegeroptionalmin: 1 · max: 100afterstringoptionalResponse
2 fields
dataobject[]required
dataobject[]requiredidcustomrequiredusernamestringrequireddaily_input_tokensinteger | nullrequireddaily_output_tokensinteger | nullrequiredstatus"provisioning" | "sleeping" | "waking" | "upgrading" | "running" | "suspended" | "failed"requiredbilling_suspendedbooleanoptionalallowance_suspendedbooleanoptionalaccountcustomrequiredprincipalcustom | nullrequiredsandboxcustom | nullrequiredruntime"codex" | "claude"requiredmodelstringrequireddefault: "gpt-6-sol"reasoning_effortstring | nullrequireddefault: nulllast_errorstring | nullrequiredcreated_bycustomrequiredcreated_atcustomrequiredupdated_atcustomrequiredhas_morebooleanrequiredGet agent
GET
/v1/agents/{agent_id}Path parameters
agent_idcustomrequiredQuery parameters
No query parameters
Response
17 fields
idcustomrequiredusernamestringrequireddaily_input_tokensinteger | nullrequireddaily_output_tokensinteger | nullrequiredstatus"provisioning" | "sleeping" | "waking" | "upgrading" | "running" | "suspended" | "failed"requiredbilling_suspendedbooleanoptionalallowance_suspendedbooleanoptionalaccountcustomrequiredprincipalcustom | nullrequiredsandboxcustom | nullrequiredruntime"codex" | "claude"requiredmodelstringrequireddefault: "gpt-6-sol"reasoning_effortstring | nullrequireddefault: nulllast_errorstring | nullrequiredcreated_bycustomrequiredcreated_atcustomrequiredupdated_atcustomrequiredRead agent activity
POST
/v1/agents/{agent_id}/activityPath parameters
agent_idcustomrequiredRequest body
afterintegeroptionaldefault: 0 · min: 0 · max: 9007199254740991Response
6 fields
statestringrequireddetailstring | nullrequiredqueuednumberrequiredactive_messagestring | nullrequiredcursornumberrequiredeventsobject[]required
eventsobject[]requiredseqnumberrequiredatstringrequiredtypestringrequiredtextstringrequiredmessage_idstring | nullrequiredWake agent
POST
/v1/agents/{agent_id}/wakePath parameters
agent_idcustomrequiredRequest body
No request body
Response
17 fields
idcustomrequiredusernamestringrequireddaily_input_tokensinteger | nullrequireddaily_output_tokensinteger | nullrequiredstatus"provisioning" | "sleeping" | "waking" | "upgrading" | "running" | "suspended" | "failed"requiredbilling_suspendedbooleanoptionalallowance_suspendedbooleanoptionalaccountcustomrequiredprincipalcustom | nullrequiredsandboxcustom | nullrequiredruntime"codex" | "claude"requiredmodelstringrequireddefault: "gpt-6-sol"reasoning_effortstring | nullrequireddefault: nulllast_errorstring | nullrequiredcreated_bycustomrequiredcreated_atcustomrequiredupdated_atcustomrequiredUpgrade agent
POST
/v1/agents/{agent_id}/upgradePath parameters
agent_idcustomrequiredRequest body
No request body
Response
17 fields
idcustomrequiredusernamestringrequireddaily_input_tokensinteger | nullrequireddaily_output_tokensinteger | nullrequiredstatus"provisioning" | "sleeping" | "waking" | "upgrading" | "running" | "suspended" | "failed"requiredbilling_suspendedbooleanoptionalallowance_suspendedbooleanoptionalaccountcustomrequiredprincipalcustom | nullrequiredsandboxcustom | nullrequiredruntime"codex" | "claude"requiredmodelstringrequireddefault: "gpt-6-sol"reasoning_effortstring | nullrequireddefault: nulllast_errorstring | nullrequiredcreated_bycustomrequiredcreated_atcustomrequiredupdated_atcustomrequiredDelete agent
DELETE
/v1/agents/{agent_id}Path parameters
agent_idcustomrequiredQuery parameters
No query parameters
Response
No response body
Agent secrets
Write-only credentials injected into new Agent sessions.
Create Agent secret
POST
/v1/agent-secretsRequest body
agent_idcustomrequirednamestringrequiredpattern: ^[A-Z][A-Z0-9_]{0,127}$valuestringrequiredmin length: 1 · max length: 4096Response
6 fields
idcustomrequiredagent_idcustomrequirednamestringrequiredreadybooleanrequiredcreated_atcustomrequiredupdated_atcustomrequiredList Agent secrets
GET
/v1/agent-secretsQuery parameters
agent_idcustomrequiredResponse
2 fields
dataobject[]required
dataobject[]requiredidcustomrequiredagent_idcustomrequirednamestringrequiredreadybooleanrequiredcreated_atcustomrequiredupdated_atcustomrequiredhas_morefalserequiredGet Agent secret metadata
GET
/v1/agent-secrets/{id}Path parameters
idcustomrequiredQuery parameters
No query parameters
Response
6 fields
idcustomrequiredagent_idcustomrequirednamestringrequiredreadybooleanrequiredcreated_atcustomrequiredupdated_atcustomrequiredRotate Agent secret
PATCH
/v1/agent-secrets/{id}Path parameters
idcustomrequiredRequest body
valuestringrequiredmin length: 1 · max length: 4096Response
6 fields
idcustomrequiredagent_idcustomrequirednamestringrequiredreadybooleanrequiredcreated_atcustomrequiredupdated_atcustomrequiredDelete Agent secret
DELETE
/v1/agent-secrets/{id}Path parameters
idcustomrequiredQuery parameters
No query parameters
Response
No response body
Agent messages
A durable event delivered to one managed Agent context.
List agent messages
GET
/v1/messagesQuery parameters
agent_idcustomrequiredstatus"queued" | "delivered" | "acknowledged"optionallimitintegeroptionalmin: 1 · max: 100afterstringoptionalResponse
2 fields
dataobject[]required
dataobject[]requiredidcustomrequiredagent_idcustomrequiredsource_event_idstringrequiredsourcestringrequiredtypestringrequiredsubjectstringrequiredpayloadobjectrequiredstatus"queued" | "delivered" | "acknowledged"requireddelivered_atcustom | nullrequiredacknowledged_atcustom | nullrequiredoutcome"succeeded" | "failed" | "canceled" | nullrequiredresultstring | nullrequirederrorstring | nullrequiredcreated_atcustomrequiredhas_morebooleanrequiredPull next agent message
POST
/v1/messages/pullRequest body
in_flightcustom[]optionalmax items: 1000Response
object | null
object | null
Acknowledge agent message
POST
/v1/messages/{message_id}/acknowledgePath parameters
message_idcustomrequiredRequest body
outcome"succeeded" | "failed" | "canceled"optionaldefault: "succeeded"resultstring | nulloptionalerrorstring | nulloptionalResponse
14 fields
idcustomrequiredagent_idcustomrequiredsource_event_idstringrequiredsourcestringrequiredtypestringrequiredsubjectstringrequiredpayloadobjectrequiredstatus"queued" | "delivered" | "acknowledged"requireddelivered_atcustom | nullrequiredacknowledged_atcustom | nullrequiredoutcome"succeeded" | "failed" | "canceled" | nullrequiredresultstring | nullrequirederrorstring | nullrequiredcreated_atcustomrequiredCancel agent message
POST
/v1/messages/{message_id}/cancelPath parameters
message_idcustomrequiredRequest body
No request body
Response
14 fields
idcustomrequiredagent_idcustomrequiredsource_event_idstringrequiredsourcestringrequiredtypestringrequiredsubjectstringrequiredpayloadobjectrequiredstatus"queued" | "delivered" | "acknowledged"requireddelivered_atcustom | nullrequiredacknowledged_atcustom | nullrequiredoutcome"succeeded" | "failed" | "canceled" | nullrequiredresultstring | nullrequirederrorstring | nullrequiredcreated_atcustomrequiredRetry agent message
POST
/v1/messages/{message_id}/retryPath parameters
message_idcustomrequiredRequest body
No request body
Response
14 fields
idcustomrequiredagent_idcustomrequiredsource_event_idstringrequiredsourcestringrequiredtypestringrequiredsubjectstringrequiredpayloadobjectrequiredstatus"queued" | "delivered" | "acknowledged"requireddelivered_atcustom | nullrequiredacknowledged_atcustom | nullrequiredoutcome"succeeded" | "failed" | "canceled" | nullrequiredresultstring | nullrequirederrorstring | nullrequiredcreated_atcustomrequiredGit hub connections
The GitHub App installation trusted by the current Account.
Get GitHub connection
GET
/v1/github/connectionQuery parameters
No query parameters
Response
7 fields
idcustomrequiredaccountcustomrequiredgithub_account_idstringrequiredgithub_account_loginstringrequiredcreated_bycustomrequiredcreated_atcustomrequiredupdated_atcustomrequiredStart GitHub connection
POST
/v1/github/connection/startRequest body
No request body
Response
2 fields
installation_urlstringrequiredformat: uriexpires_atcustomrequiredDisconnect GitHub
DELETE
/v1/github/connectionQuery parameters
No query parameters
Response
No response body
Repositories
A GitHub repository made available to managed Agents in an Account.
Add repository
POST
/v1/repositoriesRequest body
full_namestringrequiredpattern: ^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$Response
9 fields
idcustomrequiredaccountcustomrequiredprovider"github"requiredexternal_idstringrequiredfull_namestringrequiredpattern: ^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$clone_urlstringrequiredformat: uridefault_branchstringrequiredcreated_atcustomrequiredupdated_atcustomrequiredList repositories
GET
/v1/repositoriesQuery parameters
limitintegeroptionalmin: 1 · max: 100Response
2 fields
dataobject[]required
dataobject[]requiredidcustomrequiredaccountcustomrequiredprovider"github"requiredexternal_idstringrequiredfull_namestringrequiredpattern: ^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$clone_urlstringrequiredformat: uridefault_branchstringrequiredcreated_atcustomrequiredupdated_atcustomrequiredhas_morebooleanrequiredRemove repository
DELETE
/v1/repositories/{repository_id}Path parameters
repository_idcustomrequiredQuery 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-grantsRequest body
agentcustomrequiredrepositorycustomrequiredpermission"read" | "write"optionaldefault: "write"Response
6 fields
idcustomrequiredaccountcustomrequiredagentcustomrequiredrepositorycustomrequiredpermission"read" | "write"requiredcreated_atcustomrequiredList repository grants
GET
/v1/repository-grantsQuery parameters
agentcustomoptionalResponse
2 fields
dataobject[]required
dataobject[]requiredidcustomrequiredaccountcustomrequiredagentcustomrequiredrepositorycustomrequiredpermission"read" | "write"requiredcreated_atcustomrequiredhas_morebooleanrequiredRevoke repository access
DELETE
/v1/repository-grants/{grant_id}Path parameters
grant_idcustomrequiredQuery parameters
No query parameters
Response
No response body