Agent connections API Reference: Endpoints and Examples

OpenAPI YAML OpenAPI JSON problems YAML API overview

This group has 3 operations, generated from api/openapi.yaml. Filter by path, action, or authentication. Each endpoint lists its inputs; expand it for a request template and response codes. Templates need your own values and a schema-valid body.

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

Agent installations and connections

POST/api/agent-identity/revoke¶

Revoke Agent Identity

Revokes the global identity, all its identity credentials and project tokens, and its pending connections. An exact replay with a revoked identity credential succeeds without another transition. Project ownership and content remain. No cookie, Origin, query or body is accepted. This route does not debit the API meter.

An agent access JWT carrying the identity scope, whose grant holds identity access (Read only, Propose or Manage, whatever the access level of the token's project), revokes the same and every OAuth grant of the identity; its tokens are refused within seconds. A retry with the same JWT after the revocation is a no-op success.

Authentication: agentIdentityBearer
Request body: none
Operation ID: revokeAgentIdentity

Request template and responses

shell · request template

curl --request POST 'https://api.screenrig.ai/api/agent-identity/revoke'

Responses

Status	Meaning	Body and headers
204	Identity revoked.	no body; headers: Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/agents/self¶

Get Current Agent

Returns the agent installation linked to the calling project bearer plus connection_ready. A project is ready when at least one member has a passkey or password. Identity status is diagnostic and does not debit the API meter.

Authentication: projectBearer
Request body: none
Operation ID: getCurrentAgent

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.

Request template and responses

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/agents/self'

Responses

Status	Meaning	Body and headers
200	Current agent and project connection readiness.	AgentSelfStatus (application/json); headers: Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/agents/self/disconnect¶

Disconnect Current Agent

Revokes only the calling project membership and its project token, preserving the global identity, other memberships, project and content. Repeating with the same cryptographically valid revoked bearer is a no-op success. Disconnecting the last active agent returns agent_lockout_risk unless allow_last_agent is explicit. Does not debit the API meter.

An agent access JWT, Read only included, disconnects the agent from its token's project; the membership ends, the project's consent leaves the agent's grants and that identity/project pair is cut off for older access tokens. Other projects in the token keep working. A retry with the same JWT after the disconnect is a no-op success.

Authentication: revocableAgentBearer
Request body: AgentDisconnectRequest
Operation ID: disconnectCurrentAgent

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.

Request body fields

Field	Description
allow_last_agent (optional, boolean)	Explicitly accept loss of the last active agent bearer. A registered dashboard passkey remains independent administrative authority. default: false

Request template and responses

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/agents/self/disconnect'

Responses

Status	Meaning	Body and headers
204	Agent disconnected.	no body; headers: Cache-Control
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
409	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)