Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.usemandate.io/llms.txt

Use this file to discover all available pages before exploring further.

Agents are the AI entities that act on behalf of your users or systems. You register an agent once, attach one or more mandates to it, and Mandate’s policy engine uses the agent’s identity to authorize every purchase the agent attempts. An agent can be revoked at any time, instantly blocking all future spend.

​
Create an agent


POST /v1/agents
Creates a new agent scoped to your account. The agent starts with status: "active" and can begin making policy-governed payments immediately. Request body
​
name
string
required
A human-readable name for the agent. Used in the dashboard and transaction records.
​
description
string
An optional description of what the agent does — for example, "Fetches company data from financial APIs".
​
capabilities
string[]
An optional list of capability tags that describe what actions this agent can perform, e.g. ["data-fetch", "financial-research"]. Not enforced by policy; used for organizational purposes.
curl --request POST https://api.kya.dev/v1/agents \
  --header "Authorization: Bearer ky_sand_••••••••••••••••" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Research Assistant",
    "description": "Fetches company data from financial APIs",
    "capabilities": ["data-fetch", "financial-research"]
  }'
Response 201
​
id
string
required
Unique agent identifier, prefixed with agent_.
​
name
string
required
The name you provided at creation.
​
description
string
The description you provided at creation, or null if omitted.
​
capabilities
string[]
required
The capabilities array you provided, or [] if omitted.
​
status
string
required
Always "active" for a newly created agent. Possible values: "active", "revoked".
​
sandbox
boolean
required
true if the agent was created with a sandbox API key.
​
revoked_at
string
ISO 8601 timestamp set when the agent is revoked. null while active.
​
created_at
string
required
ISO 8601 creation timestamp.
​
updated_at
string
required
ISO 8601 timestamp of the last update.
Example response
{
  "id": "agent_abc123",
  "name": "Research Assistant",
  "description": "Fetches company data from financial APIs",
  "capabilities": ["data-fetch", "financial-research"],
  "status": "active",
  "sandbox": true,
  "revoked_at": null,
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-15T10:00:00Z"
}

​
List agents


GET /v1/agents
Returns all agents belonging to your account, ordered by creation date descending. 
curl https://api.kya.dev/v1/agents \
  --header "Authorization: Bearer ky_sand_••••••••••••••••"
Response 200
​
agents
object[]
required
Array of agent objects. Each object has the same shape as the response from POST /v1/agents.
Example response
{
  "agents": [
    {
      "id": "agent_abc123",
      "name": "Research Assistant",
      "description": "Fetches company data from financial APIs",
      "capabilities": ["data-fetch", "financial-research"],
      "status": "active",
      "sandbox": true,
      "revoked_at": null,
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-15T10:00:00Z"
    }
  ]
}

​
Get an agent


GET /v1/agents/{agent_id}
Retrieves a single agent by ID. Returns 404 if the agent does not exist or does not belong to your account. Path parameters
​
agent_id
string
required
The agent ID to retrieve, e.g. agent_abc123.
curl https://api.kya.dev/v1/agents/agent_abc123 \
  --header "Authorization: Bearer ky_sand_••••••••••••••••"
Response 200 Returns the agent object. See Create an agent for the full field list. Error responses
StatusDetailCause
404not_foundAgent does not exist or belongs to a different account.

​
Revoke an agent


PATCH /v1/agents/{agent_id}/revoke
Permanently revokes an agent. After revocation, all policy evaluations and payment verifications for this agent are denied with agent_revoked. This action is irreversible — you cannot re-activate a revoked agent. Path parameters
​
agent_id
string
required
The agent ID to revoke.
Revoking an agent is permanent and cannot be undone. Any in-flight SDK calls that reference this agent will fail immediately. If you need to temporarily pause an agent, revoke its mandate instead.
curl --request PATCH https://api.kya.dev/v1/agents/agent_abc123/revoke \
  --header "Authorization: Bearer ky_sand_••••••••••••••••"
Response 200 Returns the updated agent object with status: "revoked" and revoked_at set to the revocation timestamp.
Example response
{
  "id": "agent_abc123",
  "name": "Research Assistant",
  "status": "revoked",
  "revoked_at": "2024-01-16T09:00:00Z",
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-16T09:00:00Z"
}
Error responses
StatusDetailCause
400Agent not found or already revokedAgent is already revoked or not found.