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_. Stack-managed agents use the operator's authenticated connection. Customer-managed agents enroll an Ed25519 public key and authenticate with short-lived agent JWTs.
Send an operator-scoped bearer token for management calls. Enrollment endpoints use their documented enrollment ticket or signed challenge.
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": "proxy_only",
"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: "proxy_only" - the agent never receives a raw secret.
- profile (string, optional) - Registration preset. Explicit fields override preset values.
- skill_access_mode (string, optional) - Skill access policy. Default: "none".
- allowed_skills (string[], optional) - Skills permitted by the selected skill access policy.
- key_mode (string, optional) - "stack_managed", "customer_managed", or "co_signed". Default: "stack_managed".
- twin_policy (string, optional) - Digital-twin execution policy.
- twin_llm_model (string or null, optional) - LLM override for twin execution.
- 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": "proxy_only",
"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 - This bearer bucket exceeded 60 registrations per minute on one API machine.
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. Checkout keeps critical flags. The configured critical escalation action can still block the agent.
standard
Does not accept checkpoints or checkouts. Use it only when your application does not need STACK accountability reports.
Credential Access Modes
The credential_access field controls how the agent interacts with stored service credentials:
- proxy_only (default) - STACK refuses raw credential retrieval for this agent. Calls made through the STACK proxy receive the host, scope and constraint checks that apply to that Passport, plus an approval check when the agent uses enforced mode.
- proxy_preferred - Also refuses raw credential retrieval. Use it when the runtime normally calls through the proxy but the label needs to distinguish that operating preference from a hard deployment policy.
- direct - The agent can retrieve raw credentials via the credentials API and call the provider itself. Those calls leave STACK entirely, so nothing on the proxy path applies to them. Choose this only when you trust the agent runtime and accept that its outbound calls are unmediated.
This setting controls access to credentials stored in STACK. It does not sandbox the agent process or stop it reaching the internet with credentials obtained elsewhere.
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 passport context, including agent identity, authorized services, and active mission, to each gateway call.
- 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.
Disabling llm_redact_pii means user-supplied PII flows to the LLM provider unredacted. The audit log records pii_hits: -1 on those calls so "redaction skipped" is distinguishable from "scanned, zero hits".
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": "proxy_only",
"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 its name or key mode. 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.
- skill_access_mode (string, optional) - Skill access policy.
- allowed_skills (string[], optional) - Skills allowed by that policy.
- identity_claim_ids (string[], optional) - Identity claims assigned to the agent.
- twin_policy (string, optional) - Digital-twin execution policy.
- twin_llm_model (string or null, optional) - Twin LLM override, or null to clear it.
- is_synthetic (boolean, optional) - Mark test traffic for default event filtering.
- 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
Clear an agent block after the incident has been reviewed. When STACK blocks an agent, it also revokes that agent's active Passports and every active Passport delegated from them in the same database transaction. This endpoint permits future issuance; it does not restore any revoked Passport.
Request Example
curl -X POST https://api.getstack.run/v1/agents/agt_7kx9m2nq4p/unblock \
-H "Authorization: Bearer sk_live_op_abc123"Unblocking is a governance action. Agent and Passport contexts are refused. A direct API key or user OAuth call returns403 GOVERNANCE_APPROVAL_REQUIRED with an approval id. A human approves at /governance/approvals in the dashboard, then the same call is retried with theX-Governance-Approval header. Dashboard sessions unblock directly. Full protocol: /docs/api/security-events.
Unblocking neither restores revoked Passports nor approves a flagged checkout. New access requires a newly issued Passport, and checkout reviews remain in the review queue.
Delete Agent
DELETE /v1/agents/:id
Permanently delete an agent and mark its active Passports as revoked. The next STACK-verified call rejects those Passports. 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"Deleting an agent is irreversible. Pending drop-offs assigned to it become uncollectable, and offline signature-only verifiers may still accept its existing Passports until their signed expiry.
Tier Limits
There is no cap on agents, on any tier, and registering one is not a metered action. A cap here would mean a customer at their limit runs the next twenty agents outside STACK, and an unregistered agent is an unaudited agent.
Registration allows 60 requests per minute per bearer bucket, per API machine. It does not use the monthly action allowance.