Create agent
Create a new agent instance. Returns the instance with a plain API token, or OAuth client credentials if `auth.type` is `oauth`.
Create a new agent instance. Returns the instance with a plain API token, or OAuth client credentials if auth.type is oauth.
ApiKeyAuthAuthorizationBearer <token>Bearer token authentication. Send an API key (a saai_api_-prefixed token) as Authorization: Bearer <token>.
Required permission
manage_agent_instancesapplication/json- body
One connected client of an agent, registered to the user who authorized it. A policy scoped to the agent applies to every instance; one scoped to an instance applies to that connection alone.
display_name*stringHuman-readable name for this connection, shown in the instance list.
1 <= length <= 255agent_slug?stringWhich agent this is an instance of, for example claude-code or cursor. May be set on create to label the agent; otherwise the gateway identifies it from the connecting client.
auth?|How a created agent instance authenticates to the gateway; tagged by type.
The request has succeeded and a new resource has been created as a result.
application/json- response
Response for agent instance creation; carries the one-time credentials.
id*stringuuiduser_id?stringuuiduser_display_name*stringDisplay name of the owning user.
display_name*stringHuman-readable name for this connection, shown in the instance list.
1 <= length <= 255metadata?Connection details reported by the client the last time it connected.
created_at*stringWhen the instance was first registered.
date-timeupdated_at*stringdate-timelast_used_at?stringWhen the instance last connected to the gateway; absent if it never has.
date-timerevoked_at?stringWhen this instance's access was revoked; absent while it remains active.
date-timeagent_slug?stringWhich agent this is an instance of, for example claude-code or cursor. May be set on create to label the agent; otherwise the gateway identifies it from the connecting client.
external_id?stringIdentifier assigned by the client's own system, when it supplies one.
token_endpoint_auth_method?stringis_dcr_managed?booleancredentials*|One-time credentials for a created agent instance; the shape is tagged by type.
curl -X POST "https://example.com/agent-instances" \ -H "Content-Type: application/json" \ -d '{ "display_name": "string" }'{ "id": null, "user_id": null, "user_display_name": "string", "display_name": "string", "metadata": { "client_name": "string", "client_version": "string", "protocol_version": "string", "user_agent": "string", "ip_address": "string" }, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "last_used_at": "2019-08-24T14:15:22Z", "revoked_at": "2019-08-24T14:15:22Z", "agent_slug": "string", "external_id": "string", "token_endpoint_auth_method": "string", "is_dcr_managed": true, "credentials": { "type": "api_key", "token": "string" }}