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, using letters, digits, hyphens, or underscores, matching the pattern /^[a-z0-9_][a-z0-9_\-]*[a-z0-9_]$/ and at most 64 characters. Examples: my-agent, my_agent, research-pipeline. 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. Letters, digits, hyphens, or underscores. 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.
• llm_inject_system_prompt (boolean, optional) - Prepend the STACK passport-context system message to every /v1/llm/* gateway call this agent makes. Default: true.
• llm_redact_pii (boolean, optional) - Scan user-role messages on /v1/llm/* calls and replace detected PII with [REDACTED:<category>] before forwarding. Default: true. When false, user-supplied PII reaches the LLM provider unredacted.

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,
  "llm_inject_system_prompt": true,
  "llm_redact_pii": true,
  "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.

LLM Gateway Controls

Two per-agent booleans control what STACK does to the agent's /v1/llm/* gateway calls before forwarding them to the provider. Both default to true.

• llm_inject_system_prompt - STACK prepends a passport-context system message (agent identity, authorised services, active mission) to every gateway call. Costs roughly 150-250 input tokens per call; the message is stable for the life of the passport, so provider prompt caching still applies.
• llm_redact_pii - STACK scans user-role messages and replaces detected PII (email, phone, SSN, credit card, IBAN, IP address) with [REDACTED:<category>] before the call leaves STACK. A no-op when a message contains no PII.

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,
    "llm_inject_system_prompt": true,
    "llm_redact_pii": true,
    "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, LLM gateway toggles, 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.
• llm_inject_system_prompt (boolean, optional) - Toggle the STACK passport-context system message on /v1/llm/* calls. See LLM Gateway Controls above.
• llm_redact_pii (boolean, optional) - Toggle PII redaction on /v1/llm/* calls. Setting false sends user-supplied PII to the provider unredacted.
• eval_traffic (boolean, optional) - Mark this agent as eval/benchmark traffic. Detection stays fully on and events stay visible, but warning-and-below events insert pre-resolved with no notification, the L3 LLM classifier is skipped, and the daily digest excludes the noise. Criticals stay fully live, including auto-block. Operator-set only: not settable from agent contexts or partner grants. See /docs/api/security-events.

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.