Agents

An agent is a registered AI coding agent — a delegated identity of one user, not an independent principal. Its captured sessions are attributed to its owner and inherit the owner’s workspace visibility. Registering an agent also issues its single Agent Access Token (AAT), the write-only credential the agent uses to ingest activity. See Agent ingest for the endpoints that consume that token.

Managing agents is an interactive surface: the mutating endpoints below require a logged-in session and operate only on the caller’s own agents. The plaintext token secret (spantail_aat_…) is returned exactly once — at creation and on rotation — and is never retrievable afterwards.

The agent object

Field	Type	Description
id	string	Unique identifier.
type	string	Agent kind: claude_code, codex, cursor, or other.
name	string	Display name (1–100 chars).
createdAt	string	ISO 8601 creation instant.
disabledAt	string | null	When set, the agent is paused and its token is rejected at ingest.
archivedAt	string | null	When set, the agent is archived (irreversible).
token	object | null	Summary of the access token (see below).

The token summary never exposes the secret or its hash:

Field	Type	Description
lastUsedAt	string | null	ISO 8601 instant the token was last used to ingest.
expiresAt	string | null	ISO 8601 expiry, or null if the token never expires.

List agents

GET /api/v1/agents

The required auth depends on the query:

• No query session only — returns the caller’s own agents (newest first). An interactive session is required.
• ?ownerUserId=<id> scope: admin — an instance admin reads another user’s agents.

The owning userId and the token hash are never returned.

Query parameters

Name	Type	Required	Description
ownerUserId	string	no	Instance admin only: list a specific user’s agents.

curl

curl "https://<your-instance>/api/v1/agents" \
  -H "Cookie: <your session cookie>"

Response

[
  {
    "id": "agt_bot",
    "type": "claude_code",
    "name": "Build bot",
    "createdAt": "2026-06-28T09:30:00.000Z",
    "disabledAt": null,
    "archivedAt": null,
    "token": {
      "lastUsedAt": "2026-06-28T10:15:00.000Z",
      "expiresAt": null
    }
  }
]

Register an agent

POST /api/v1/agents session only

Registers an agent owned by the caller and issues its single access token (agent and token are 1:1). No workspace is involved: where a session lands is named by each ingest payload (see Agent ingest). The plaintext secret is returned once in this response.

Request body

Field	Type	Required	Description
type	string	yes	Agent kind: claude_code, codex, cursor, or other.
name	string	yes	Display name (1–100 chars).
expiresInDays	integer	no	Token lifetime in days (1–3650). Omit for a token that never expires.

curl

curl -X POST "https://<your-instance>/api/v1/agents" \
  -H "Cookie: <your session cookie>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "claude_code",
    "name": "Build bot"
  }'

Response

{
  "id": "agt_bot",
  "type": "claude_code",
  "name": "Build bot",
  "createdAt": "2026-06-28T09:30:00.000Z",
  "disabledAt": null,
  "archivedAt": null,
  "token": {
    "lastUsedAt": null,
    "expiresAt": null
  },
  "secret": "spantail_aat_9f8c2b1a4d6e0f3c5a7b9d1e2f4a6c8e"
}

Returns 201 Created.

Caution

secret is shown only here. Store it where the agent runs; if you lose it, rotate the token to issue a new one.

Disable or enable an agent

PATCH /api/v1/agents/:id session only

Pauses or resumes the agent by toggling disabled. While disabled, the agent’s token is rejected at ingest; re-enabling restores it. This is reversible (unlike archiving). Returns the agent object.

Request body

Field	Type	Required	Description
disabled	boolean	yes	true to pause the agent, false to resume it.

curl -X PATCH "https://<your-instance>/api/v1/agents/agt_bot" \
  -H "Cookie: <your session cookie>" \
  -H "Content-Type: application/json" \
  -d '{ "disabled": true }'

Archive an agent

DELETE /api/v1/agents/:id session only

Archives the agent and kills its token immediately. Returns 204 No Content.

Caution

Archiving is irreversible: an archived agent cannot be un-archived, and its token is dead for good. The activity it already captured is retained. To pause an agent temporarily, use PATCH with disabled: true instead.

Rotate the access token

POST /api/v1/agents/:id/token/rotate session only

Regenerates the agent’s token secret in place, keeping its expiry. The old secret stops working immediately. The new plaintext secret is returned once.

curl

curl -X POST "https://<your-instance>/api/v1/agents/agt_bot/token/rotate" \
  -H "Cookie: <your session cookie>"

Response

{
  "secret": "spantail_aat_1d3f5a7c9e0b2d4f6a8c0e2b4d6f8a0c"
}