# Agent connections API reference

> Canonical HTML: https://screenrig.ai/docs/api/agents
> Source SHA-256: e0c997a2ab813502f0d99a41d2ed1d3d6b26dbaf1a3d7e514c1cce0278ff8422

Agent installations and connections. This group has 3 operations, each with its authentication, parameters, request body fields, request template and responses. The [API overview](https://screenrig.ai/docs/api.md) covers services, authentication, requests and retries, problem codes and versioning.

Replace uppercase placeholders. Save a schema-valid JSON body in request.json when required. 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.


Operation: revokeAgentIdentity.

- Authentication: agentIdentityBearer
- Request body: none

#### Request template

~~~sh
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.


Operation: getCurrentAgent.

- Authentication: projectBearer
- Request body: none

#### 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

~~~sh
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.


Operation: disconnectCurrentAgent.

- Authentication: revocableAgentBearer
- Request body: AgentDisconnectRequest

#### 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 | Required? | Type | 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

~~~sh
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) |


## Sitemap

See the [public documentation sitemap](https://screenrig.ai/sitemap.md).