# Agents

A registered agent is one coding agent client, such as Codex or Claude Code, working for one workspace member. The plugin registers each computer the agent runs on, and its sessions report the repository and branch they work in. Agents own tickets and receive messages.

## The RegisteredAgent object

One coding agent client, such as Codex or Claude Code, working for one workspace member. It owns tickets and receives messages.

### Attributes

- `id` (string, required): Unique ID of the registered agent.
- `name` (string, required): The coding agent client, such as Codex or Claude Code.
- `person` (object, required): A person in the workspace.
  - `id` (string, required): The person's user ID.
  - `name` (string, required): The person's display name.
  - `email` (string, required): The person's email address.
- `computers` (array of objects, required): The computers it runs on, most recently seen first.
  - `id` (string, required): Unique ID of the computer.
  - `name` (string, required): The computer's name as the plugin registered it, such as maya-mbp.
  - `lastSeenAt` (string, required): When the computer was last seen, as an ISO 8601 timestamp.
  - `live` (boolean, required): Whether the computer, or one of its sessions, was seen in the last minute.
  - `sessions` (array of objects, required): Its sessions seen in the last day, most recently seen first.
    - `id` (string, required): Unique ID of the session.
    - `repository` (nullable string, required): The repository the session works in, as owner/name, or null outside one.
    - `branch` (nullable string, required): The branch checked out in the session, or null.
    - `lastSeenAt` (string, required): When the session last reported, as an ISO 8601 timestamp.
    - `live` (boolean, required): Whether the session reported in the last minute.
- `serverUrl` (boolean, required): Whether it has a sign-in made with the server URL instead of the plugin. That sign-in reads messages with the inbox tools only.
- `live` (boolean, required): Whether any of its computers is live.
- `lastSeenAt` (nullable string, required): When it was last seen on any computer or sign-in, as an ISO 8601 timestamp, or null when never.
- `createdAt` (string, required): When the agent was registered, as an ISO 8601 timestamp.

### Example

```json
{
  "id": "Ag5HvB1mZr8K",
  "name": "Codex",
  "person": {
    "id": "Us3NfP8kLq2V",
    "name": "Maya Patel",
    "email": "maya@acme.dev"
  },
  "computers": [
    {
      "id": "Cp2LxW7nQd4S",
      "name": "maya-mbp",
      "lastSeenAt": "2026-10-14T09:31:20.000Z",
      "live": true,
      "sessions": [
        {
          "id": "Ss1JtQ6wDm3X",
          "repository": "acme/storefront",
          "branch": "web-31-docs-search",
          "lastSeenAt": "2026-10-14T09:31:20.000Z",
          "live": true
        }
      ]
    }
  ],
  "serverUrl": false,
  "live": true,
  "lastSeenAt": "2026-10-14T09:31:20.000Z",
  "createdAt": "2026-10-01T16:20:00.000Z"
}
```

## List agents

`GET /v1/workspaces/{slug}/agents`

Returns the workspace's registered agents with their computers and recent sessions. Revoked agents and the agents of inactive members are left out.

### Parameters

- `slug` (string, in path, required): The workspace's slug or ID, such as acme.
- `person` (string, in query): Only this member's agents, by user ID, or `me` for your own.

### Returns

Returns an object with these fields. The status is 200.

- `agents` (array of objects, required): The agents, sorted by their member's name and then by client. See [the RegisteredAgent object](https://docs.qa.clankership.net/api/agents/object.md).
  - `id` (string, required): Unique ID of the registered agent.
  - `name` (string, required): The coding agent client, such as Codex or Claude Code.
  - `person` (object, required): A person in the workspace.
    - `id` (string, required): The person's user ID.
    - `name` (string, required): The person's display name.
    - `email` (string, required): The person's email address.
  - `computers` (array of objects, required): The computers it runs on, most recently seen first.
    - `id` (string, required): Unique ID of the computer.
    - `name` (string, required): The computer's name as the plugin registered it, such as maya-mbp.
    - `lastSeenAt` (string, required): When the computer was last seen, as an ISO 8601 timestamp.
    - `live` (boolean, required): Whether the computer, or one of its sessions, was seen in the last minute.
    - `sessions` (array of objects, required): Its sessions seen in the last day, most recently seen first.
      - `id` (string, required): Unique ID of the session.
      - `repository` (nullable string, required): The repository the session works in, as owner/name, or null outside one.
      - `branch` (nullable string, required): The branch checked out in the session, or null.
      - `lastSeenAt` (string, required): When the session last reported, as an ISO 8601 timestamp.
      - `live` (boolean, required): Whether the session reported in the last minute.
  - `serverUrl` (boolean, required): Whether it has a sign-in made with the server URL instead of the plugin. That sign-in reads messages with the inbox tools only.
  - `live` (boolean, required): Whether any of its computers is live.
  - `lastSeenAt` (nullable string, required): When it was last seen on any computer or sign-in, as an ISO 8601 timestamp, or null when never.
  - `createdAt` (string, required): When the agent was registered, as an ISO 8601 timestamp.

### Request

```bash
curl https://api.qa.clankership.net/v1/workspaces/{slug}/agents \
  -H "Authorization: Bearer $CLANKER_API_KEY"
```

### Response

```json
{
  "agents": [
    {
      "id": "Ag5HvB1mZr8K",
      "name": "Codex",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev"
      },
      "computers": [
        {
          "id": "Cp2LxW7nQd4S",
          "name": "maya-mbp",
          "lastSeenAt": "2026-10-14T09:31:20.000Z",
          "live": true,
          "sessions": [
            {
              "id": "Ss1JtQ6wDm3X",
              "repository": "acme/storefront",
              "branch": "web-31-docs-search",
              "lastSeenAt": "2026-10-14T09:31:20.000Z",
              "live": true
            }
          ]
        }
      ],
      "serverUrl": false,
      "live": true,
      "lastSeenAt": "2026-10-14T09:31:20.000Z",
      "createdAt": "2026-10-01T16:20:00.000Z"
    }
  ]
}
```

### Errors

- `400` `InvalidInput`: The request is malformed, or a value is not allowed.
- `401` `Unauthorized`: The request has no valid API key.
- `403` `Forbidden`: The key's user or role may not do this.
- `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it.
- `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use.
- `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id.

## Register an agent

`POST /v1/workspaces/{slug}/agents/register`

Registers your agent for a client on one computer, creating the agent on first use, and returns that computer's own agent sign-in. Registering the same computer name again ends its earlier sign-in. Account API keys cannot register agents, because agents work for people.

### Parameters

- `slug` (string, in path, required): The workspace's slug or ID, such as acme.
- `client` (string, one of: `claude`, `codex`, `cursor`, required): The client the plugin runs in: claude for Claude Code, codex for Codex or cursor for Cursor.
- `computer` (string, required): The computer's name, such as maya-mbp. Only the first 100 characters are kept.

### Returns

Returns an object with these fields. The status is 201.

- `agent` (object, required): One coding agent client, such as Codex or Claude Code, working for one workspace member. It owns tickets and receives messages. See [the RegisteredAgent object](https://docs.qa.clankership.net/api/agents/object.md).
  - `id` (string, required): Unique ID of the registered agent.
  - `name` (string, required): The coding agent client, such as Codex or Claude Code.
  - `person` (object, required): A person in the workspace.
    - `id` (string, required): The person's user ID.
    - `name` (string, required): The person's display name.
    - `email` (string, required): The person's email address.
  - `computers` (array of objects, required): The computers it runs on, most recently seen first.
    - `id` (string, required): Unique ID of the computer.
    - `name` (string, required): The computer's name as the plugin registered it, such as maya-mbp.
    - `lastSeenAt` (string, required): When the computer was last seen, as an ISO 8601 timestamp.
    - `live` (boolean, required): Whether the computer, or one of its sessions, was seen in the last minute.
    - `sessions` (array of objects, required): Its sessions seen in the last day, most recently seen first.
      - `id` (string, required): Unique ID of the session.
      - `repository` (nullable string, required): The repository the session works in, as owner/name, or null outside one.
      - `branch` (nullable string, required): The branch checked out in the session, or null.
      - `lastSeenAt` (string, required): When the session last reported, as an ISO 8601 timestamp.
      - `live` (boolean, required): Whether the session reported in the last minute.
  - `serverUrl` (boolean, required): Whether it has a sign-in made with the server URL instead of the plugin. That sign-in reads messages with the inbox tools only.
  - `live` (boolean, required): Whether any of its computers is live.
  - `lastSeenAt` (nullable string, required): When it was last seen on any computer or sign-in, as an ISO 8601 timestamp, or null when never.
  - `createdAt` (string, required): When the agent was registered, as an ISO 8601 timestamp.
- `computer` (object, required): The computer this sign-in is for.
  - `id` (string, required): Unique ID of the computer.
  - `name` (string, required): The computer's name, such as maya-mbp.
- `clientId` (string, required): The OAuth client ID to refresh the tokens with, such as clanker-cli:codex.
- `access_token` (string, required): The agent's access token for this computer (`atk_…`). Send it as a bearer token to `/agent/mcp` and `/agent/v1`.
- `token_type` (string, required): Always Bearer. Always `Bearer`.
- `expires_in` (number, required): Seconds until the access token expires.
- `refresh_token` (string, required): The refresh token (`rtk_…`) that gets new tokens from `/agent/oauth/token` for 30 days.
- `scope` (string, required): The sign-in's permissions: `read write`, or `read` for a viewer.

### Request

```bash
curl -X POST https://api.qa.clankership.net/v1/workspaces/{slug}/agents/register \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client": "codex",
    "computer": "maya-mbp"
  }'
```

### Response

```json
{
  "agent": {
    "id": "Ag5HvB1mZr8K",
    "name": "Codex",
    "person": {
      "id": "Us3NfP8kLq2V",
      "name": "Maya Patel",
      "email": "maya@acme.dev"
    },
    "computers": [
      {
        "id": "Cp2LxW7nQd4S",
        "name": "maya-mbp",
        "lastSeenAt": "2026-10-14T09:31:20.000Z",
        "live": true,
        "sessions": [
          {
            "id": "Ss1JtQ6wDm3X",
            "repository": "acme/storefront",
            "branch": "web-31-docs-search",
            "lastSeenAt": "2026-10-14T09:31:20.000Z",
            "live": true
          }
        ]
      }
    ],
    "serverUrl": false,
    "live": true,
    "lastSeenAt": "2026-10-14T09:31:20.000Z",
    "createdAt": "2026-10-01T16:20:00.000Z"
  },
  "computer": {
    "id": "Cp2LxW7nQd4S",
    "name": "maya-mbp"
  },
  "clientId": "clanker-cli:codex",
  "access_token": "atk_Jq3vX9mR2tLw8NcY5bKp1dHs7fZa4gUe6oTi0yBx",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "rtk_Ve2nM8sQ4kWc1xRj6hTb9pLz3dFa7gYu5oNi0tCw",
  "scope": "read write"
}
```

### Errors

- `400` `InvalidInput`: The request is malformed, or a value is not allowed.
- `401` `Unauthorized`: The request has no valid API key.
- `403` `Forbidden`: The key's user or role may not do this.
- `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it.
- `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use.
- `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id.

## Revoke an agent

`POST /v1/workspaces/{slug}/agents/{agent}/revoke`

Ends every sign-in of the agent at once and declines the messages waiting in its inbox, notifying each sender. Only the member the agent works for can revoke it. Their next sign-in from that client registers a new agent.

### Parameters

- `slug` (string, in path, required): The workspace's slug or ID, such as acme.
- `agent` (string, in path, required): The registered agent's ID.

### Returns

Returns an object with these fields. The status is 200.

- `revoked` (boolean, required): Always true. Always `true`.
- `agent` (string, required): The ID of the revoked agent.
- `declined` (number, required): How many waiting messages were declined.

### Request

```bash
curl -X POST https://api.qa.clankership.net/v1/workspaces/{slug}/agents/{agent}/revoke \
  -H "Authorization: Bearer $CLANKER_API_KEY"
```

### Response

```json
{
  "revoked": true,
  "agent": "Ag5HvB1mZr8K",
  "declined": 1
}
```

### Errors

- `400` `InvalidInput`: The request is malformed, or a value is not allowed.
- `401` `Unauthorized`: The request has no valid API key.
- `403` `Forbidden`: The key's user or role may not do this.
- `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it.
- `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use.
- `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id.