REST API Endpoints for Mandates

A mandate is a scoped spending authorization attached to a specific agent. It defines the total budget, the per-transaction ceiling, which merchant domains and resource categories are permitted, and an expiry time. Mandate’s policy engine evaluates every payment attempt against these constraints before authorizing a charge. You can revoke a mandate at any point to immediately halt all further spending under it.

Create a mandate

POST /v1/mandates

Creates a new mandate for an agent. The mandate status begins as "active" and policy enforcement starts immediately. Request body

agent_id

string

required

The ID of the agent this mandate authorizes. The agent must belong to your account and be in "active" status.

purpose

string

required

A plain-language description of what this mandate permits, e.g. "Financial data research". Shown in the dashboard and audit log.

max_spend_total

string

required

The total budget across the lifetime of this mandate, as a decimal string (e.g. "10.00"). The mandate transitions to "exhausted" once spent_total reaches this value.

max_spend_per_transaction

string

required

The maximum amount allowed in a single transaction, as a decimal string (e.g. "0.50"). Any payment request exceeding this value is denied with amount_exceeds_per_transaction_limit.

currency

string

default:"USDC"

The currency for all spend accounting. Currently "USDC" only.

allowed_sellers

string[]

An allowlist of merchant domains this agent is permitted to pay. Pass ["*"] to allow any merchant. If you pass an empty array or omit this field, the mandate will block all merchant domains — you must provide at least one domain or ["*"] to allow payments.

allowed_categories

string[]

An allowlist of resource categories this mandate covers (e.g. ["data", "research"]). Pass ["*"] to allow all categories. An empty array ([]) also permits all categories — the policy engine treats an empty list as “no category restriction”.

expires_at

string

required

ISO 8601 expiry timestamp for this mandate. After this time, all policy evaluations return mandate_expired.

curl --request POST https://api.kya.dev/v1/mandates \
  --header "Authorization: Bearer ky_sand_••••••••••••••••" \
  --header "Content-Type: application/json" \
  --data '{
    "agent_id": "agent_abc123",
    "purpose": "Financial data research",
    "max_spend_total": "10.00",
    "max_spend_per_transaction": "0.50",
    "currency": "USDC",
    "allowed_sellers": ["data.example.com", "api.financials.io"],
    "allowed_categories": ["data", "research"],
    "expires_at": "2024-12-31T23:59:59Z"
  }'

Response 201

string

required

Unique mandate identifier.

agent_id

string

required

The agent this mandate is attached to.

purpose

string

required

The purpose description provided at creation.

max_spend_total

string

required

Total budget as a decimal string.

max_spend_per_transaction

string

required

Per-transaction ceiling as a decimal string.

currency

string

required

Currency code, e.g. "USDC".

allowed_sellers

string[]

required

The merchant domain allowlist for this mandate.

allowed_categories

string[]

required

The stored category allowlist.

expires_at

string

required

ISO 8601 expiry timestamp.

status

string

required

Mandate lifecycle status. One of "active", "revoked", or "exhausted".

spent_total

string

required

Running total of verified spend against this mandate, as a decimal string.

revoked_at

string

ISO 8601 timestamp set on revocation. 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": "mandate_xyz789",
  "agent_id": "agent_abc123",
  "purpose": "Financial data research",
  "max_spend_total": "10.000000",
  "max_spend_per_transaction": "0.500000",
  "currency": "USDC",
  "allowed_sellers": ["data.example.com", "api.financials.io"],
  "allowed_categories": ["data", "research"],
  "expires_at": "2024-12-31T23:59:59Z",
  "status": "active",
  "spent_total": "0.000000",
  "revoked_at": null,
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-15T10:00:00Z"
}

Error responses

Status	Detail	Cause
`404`	`agent_not_found`	The `agent_id` does not exist or is not yours.

List mandates

GET /v1/mandates

Returns all mandates for your account, ordered by creation date descending. Use the agent_id query parameter to filter to a specific agent’s mandates. Query parameters

agent_id

string

Optional. Filter results to mandates belonging to this agent.

curl "https://api.kya.dev/v1/mandates?agent_id=agent_abc123" \
  --header "Authorization: Bearer ky_sand_••••••••••••••••"

Response 200

mandates

object[]

required

Array of mandate objects. Each object has the same shape as the response from POST /v1/mandates.

Get a mandate

GET /v1/mandates/{mandate_id}

Retrieves a single mandate by ID. Returns 404 if it does not exist or does not belong to your account. Path parameters

mandate_id

string

required

The mandate ID to retrieve.

curl https://api.kya.dev/v1/mandates/mandate_xyz789 \
  --header "Authorization: Bearer ky_sand_••••••••••••••••"

Response 200 Returns the mandate object. See Create a mandate for the full field list. Error responses

Status	Detail	Cause
`404`	`not_found`	Mandate does not exist or belongs to a different account.

Revoke a mandate

PATCH /v1/mandates/{mandate_id}/revoke

Immediately revokes an active mandate. The mandate’s status transitions to "revoked" and all subsequent policy evaluations against it return mandate_expired. Path parameters

mandate_id

string

required

The mandate ID to revoke.

Revoking a mandate immediately blocks all future payments for the agent-and-mandate pair. This action is irreversible. If you need to adjust spending limits or extend expiry, you must create a new mandate instead.

curl --request PATCH https://api.kya.dev/v1/mandates/mandate_xyz789/revoke \
  --header "Authorization: Bearer ky_sand_••••••••••••••••"

Response 200 Returns the updated mandate object with status: "revoked" and revoked_at set.

Example response

{
  "id": "mandate_xyz789",
  "agent_id": "agent_abc123",
  "status": "revoked",
  "revoked_at": "2024-01-16T09:00:00Z",
  "spent_total": "3.500000",
  "updated_at": "2024-01-16T09:00:00Z"
}

Error responses

Status	Detail	Cause
`400`	`Mandate not found or already revoked`	Mandate is not active or does not exist.

Overview

Endpoints

Documentation Index

​Create a mandate

​List mandates

​Get a mandate

​Revoke a mandate

Create a mandate

List mandates

Get a mandate

Revoke a mandate