Sessions

No session API exists. They are enforced on every open and read back through agents.

There is no session endpoint. Spend sessions are enforced on every warrant open and readable only as part of GET /v1/console/agents.

# There is no POST /v1/sessions, no GET /v1/sessions, and no DELETE.
GET /v1/console/agents   →   data[].session

This page documents an absence

A spend session is a real, enforced object — it has a table, four limits and a policy engine that checks all of them before a warrant can open. What it does not have is an API surface of its own. Creating, extending and revoking one are console actions.

The route table has no path matching sessions. If you are looking for one, you are looking for something that is not built rather than something you have missed.

Not the session that signs you in

Two different things share the word:

	Spend session	Auth session
Belongs to	An agent	A person
Carries	Amount ceiling, counts, budgets	Identity and role
Created by	The console	`POST /auth/session`
Documented in	This page	Authentication

POST /auth/session and DELETE /auth/session exist and are the sign-in and sign-out for a person. They have nothing to do with spending.

What is enforced, and when

Before a warrant opens, four limits are checked. Each failure is a 403 — the caller is authenticated and their API key is fine; the envelope is what is exhausted.

Limit	Refused with
Amount ceiling, cumulative across the session	`session_ceiling_exceeded`
Warrant count, if `warrant_limit` is set	`session_warrant_limit_reached`
Consecutive failures	`session_failure_budget_spent`
Expiry	`session_expired`
Revoked	`session_revoked`

The ceiling error reports the ceiling, the amount spent and the amount requested, so an agent can tell how close it came rather than guessing.

Read one back

The only way to see a session over the API is through the agent that owns it.

GET /v1/console/agents HTTP/1.1
Host: api.gowarrant.xyz
Cookie: warrant_session=…

200

{
"object": "list",
"data": [
  {
    "id": "agt_01J8Z3M4YQ7K2V9XABCDEFGHJK",
    "name": "invoice-reconciler",
    "identity": "did:key:z6Mk…",
    "status": "active",
    "failure_budget": 3,
    "failure_count": 0,
    "created_at": "2026-08-01T09:14:22.000Z",
    "policy": null,
    "session": {
      "id": "ses_01J8Z3M4YQ7K2V9XABCDEFGHJK",
      "amount_ceiling": "50000000",
      "amount_spent": "8400000",
      "warrant_limit": 20,
      "warrant_count": 3,
      "failure_budget": 3,
      "failure_count": 0,
      "expires_at": "2026-08-16T12:00:00.000Z"
    },
    "warrants": { "total": 12, "by_state": { "released": 9, "escalated": 3 } }
  }
]
}

curl -sS https://api.gowarrant.xyz/v1/console/agents \
-b "warrant_session=$WARRANT_SESSION"

session is null when the agent has no unrevoked session. Only unrevoked sessions are returned, so a null means "nothing live", not "never had one".

Attaching a session to spend

There is no call that starts a session for a warrant. Pass agent_id to POST /v1/warrants and the agent's live session is found and charged automatically. Omit it and no session ceiling applies.

Amounts

amount_ceiling and amount_spent are integer strings of the asset's smallest unit, ^[0-9]+$, and are compared as 64-bit integers.

"50000000"   50.00 USDC
50000000     rejected — a JSON number
"50.00"      rejected — not the smallest unit

A ceiling you can drift past through floating-point rounding is not a ceiling, which is why nothing here is ever a float.