Agents API

Agents are the core identity primitive in STACK. Every AI agent that needs a passport, credentials, or access to drop-offs must first be registered. Each agent receives a unique ID prefixed with agt_. Agents do not receive their own API keys — all agent operations are performed using the operator or team member API key that registered them.

Register Agent

POST /v1/agents/register

Register a new agent under your operator account. The agent name must be lowercase alphanumeric with hyphens, matching the pattern /^[a-z0-9][a-z0-9\-]*[a-z0-9]$/ and at most 64 characters. The response returns the full agent object.

Request Body

{
  "name": "invoice-processor",
  "description": "Processes incoming invoices and extracts line items",
  "accountability_mode": "enforced",
  "on_warning": "notify",
  "on_critical": "block",
  "credential_access": "direct",
  "icon_url": "https://example.com/icon.png"
}

• name (string, required) — Lowercase alphanumeric with hyphens. Must match /^[a-z0-9][a-z0-9\-]*[a-z0-9]$/. Max 64 characters.
• description (string, optional) — Human-readable description. Max 256 characters.
• accountability_mode (string, optional) — One of "enforced", "logged", or "standard". Default: "enforced".
• on_warning (string, optional) — Escalation action when a warning flag is raised: "notify" or "block".
• on_critical (string, optional) — Escalation action when a critical flag is raised: "notify" or "block".
• credential_access (string, optional) — How the agent accesses credentials: "direct", "proxy_preferred", or "proxy_only". Default: "direct".
• icon_url (string, optional) — URL or data URI for the agent icon. Max 100,000 characters. Can be null.

Request Example

curl -X POST https://api.getstack.run/v1/agents/register \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_op_abc123" \
  -d '{
    "name": "invoice-processor",
    "description": "Processes incoming invoices and extracts line items",
    "accountability_mode": "enforced",
    "on_critical": "block"
  }'

Response — 201 Created

{
  "id": "agt_7kx9m2nq4p",
  "operator_id": "op_abc123",
  "name": "invoice-processor",
  "description": "Processes incoming invoices and extracts line items",
  "status": "active",
  "accountability_mode": "enforced",
  "on_warning": "notify",
  "on_critical": "block",
  "credential_access": "direct",
  "passport_blocked": false,
  "passport_blocked_reason": null,
  "passport_blocked_at": null,
  "icon_url": null,
  "created_at": "2026-04-15T10:30:00.000Z",
  "updated_at": "2026-04-15T10:30:00.000Z"
}

Error Responses

• 400 Bad Request — Invalid name format, description too long, or invalid field values.
• 401 Unauthorized — Missing or invalid Authorization header.
• 409 Conflict — An agent with this name already exists under your account.
• 429 Too Many Requests — Agent limit exceeded for your tier.

Accountability Modes

Every agent has an accountability mode that controls how passport activity is monitored and reviewed. This is one of the most important configuration choices for production agents.

enforced (default)

The strictest mode. Agents must submit checkpoints at regular intervals during passport use and perform a checkout when done. If checkpoints are missed or the checkout report raises flags, the agent can be automatically blocked from receiving new passports until an operator reviews and approves the activity.

logged

Checkpoints and checkouts are recorded and flagged the same way as enforced mode, but the agent is never automatically blocked. All activity is available for review in the review queue, but the agent continues operating. Good for staging and monitoring.

standard

Minimal accountability. Checkpoints and checkouts are accepted if submitted but not required. No automatic blocking or review queue entries are generated. Use this only for low-risk internal agents.

Credential Access Modes

The credential_access field controls how the agent interacts with stored service credentials:

• direct — The agent can retrieve raw credentials via the credentials API. Simplest mode, suitable when you trust the agent runtime.
• proxy_preferred — The agent uses the STACK proxy by default but can fall back to direct access if the proxy does not support the target service.
• proxy_only — The agent can only access services through the STACK proxy. Raw credentials are never exposed to the agent. Most secure mode.

List Agents

GET /v1/agents

Retrieve all agents registered under your operator account.

Request Example

curl https://api.getstack.run/v1/agents \
  -H "Authorization: Bearer sk_live_op_abc123"

Response — 200 OK

[
  {
    "id": "agt_7kx9m2nq4p",
    "operator_id": "op_abc123",
    "name": "invoice-processor",
    "description": "Processes incoming invoices and extracts line items",
    "status": "active",
    "accountability_mode": "enforced",
    "on_warning": "notify",
    "on_critical": "block",
    "credential_access": "direct",
    "passport_blocked": false,
    "passport_blocked_reason": null,
    "passport_blocked_at": null,
    "icon_url": null,
    "created_at": "2026-04-15T10:30:00.000Z",
    "updated_at": "2026-04-15T10:30:00.000Z"
  }
]

Get Agent

GET /v1/agents/:id

Retrieve a single agent by its ID. Returns the full agent object.

Request Example

curl https://api.getstack.run/v1/agents/agt_7kx9m2nq4p \
  -H "Authorization: Bearer sk_live_op_abc123"

Error Responses

• 401 Unauthorized — Missing or invalid Authorization header.
• 404 Not Found — Agent does not exist or belongs to a different operator.

Update Agent

PATCH /v1/agents/:id

Update an agent's configuration. You cannot change the agent's name — only status, accountability settings, credential access mode, and icon can be updated. At least one field must be provided.

Request Body

{
  "status": "suspended",
  "accountability_mode": "logged",
  "on_warning": "notify",
  "on_critical": "block",
  "credential_access": "proxy_only",
  "icon_url": "https://example.com/new-icon.png"
}

• status (string, optional) — Must be "active" or "suspended". Cannot set to "revoked" via update.
• accountability_mode (string, optional) — "enforced", "logged", or "standard".
• on_warning (string, optional) — "notify" or "block".
• on_critical (string, optional) — "notify" or "block".
• credential_access (string, optional) — "direct", "proxy_preferred", or "proxy_only".
• icon_url (string | null, optional) — New icon URL or null to clear.

Request Example

curl -X PATCH https://api.getstack.run/v1/agents/agt_7kx9m2nq4p \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_op_abc123" \
  -d '{
    "accountability_mode": "logged",
    "credential_access": "proxy_only"
  }'

Error Responses

• 400 Bad Request — No fields provided, or invalid status value.
• 401 Unauthorized — Missing or invalid Authorization header.
• 404 Not Found — Agent does not exist or belongs to a different operator.

Unblock Agent

POST /v1/agents/:id/unblock

Unblock an agent that has been blocked from passport issuance. When an agent in enforced accountability mode triggers critical flags (e.g., missed checkpoints, undeclared service usage), it gets automatically blocked. This endpoint clears the block so the agent can receive new passports again.

Request Example

curl -X POST https://api.getstack.run/v1/agents/agt_7kx9m2nq4p/unblock \
  -H "Authorization: Bearer sk_live_op_abc123"

Delete Agent

DELETE /v1/agents/:id

Permanently delete an agent. All active passports issued to this agent will be immediately revoked. This action cannot be undone.

Request Example

curl -X DELETE https://api.getstack.run/v1/agents/agt_7kx9m2nq4p \
  -H "Authorization: Bearer sk_live_op_abc123"

Tier Limits

The number of agents you can register depends on your plan:

• Free — 5 agents
• Developer ($9.99/mo) — 25 agents
• Studio ($99/mo) — 100 agents
• Enterprise — Unlimited

Attempting to register agents beyond your tier limit will return a 429 error.