API overview

The Tally REST API is the same surface the TypeScript SDK wraps. Use the REST endpoints directly when you’re working in a language the SDK doesn’t cover yet, or when you want full control over HTTP behavior (custom retry middleware, structured logging, etc.).

Base URL

https://api.tally.example.com

Set this explicitly in production. The SDK defaults to http://localhost:3000 for local development — that’s helpful for dev, but every deployed environment should set the base URL.

Versioning

Every endpoint is prefixed with /v1. The v1 family is stable: we add fields and endpoints, but we don’t remove or repurpose them. Breaking changes will live under /v2 whenever they happen — v1 will keep working in parallel.

Request format

HTTPS only. Plain HTTP is rejected.
JSON only. Set Content-Type: application/json on every request with a body. Tally returns application/json on every response, including errors.
Field names are snake_case — agent_id, amount_usdc, idempotency_key. The SDK preserves this casing in TypeScript types.

curl https://api.tally.example.com/v1/agents \
  -H "Authorization: Bearer $TALLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "research-bot"}'

Response format

Successful responses return a JSON object with the resource keyed under its name:

{
  "agent": {
    "id": "research-bot",
    "status": "no_permissions",
    "mode": "test",
    "created_at": "2026-05-18T12:00:00Z",
    "active_signers": 0,
    "pending_signers": 0
  }
}

List endpoints return arrays under a plural key:

{ "agents": [ { "id": "research-bot", ... }, { "id": "summarizer", ... } ] }

This shape is consistent across the API — your client can lift fields by their resource name without per-endpoint parsing.

Error format

Errors use a consistent envelope across every endpoint:

{
  "error": {
    "type": "validation_failed",
    "message": "Amount exceeds per-tx max.",
    "code": "amount_too_large",
    "details": { "max_per_tx_usdc": "10", "requested": "15" }
  }
}

Field	Type	Description
`type`	string	Coarse-grained category — `unauthenticated`, `forbidden`, `not_found`, etc. Drives the HTTP status.
`message`	string	Human-readable. Safe to log; no PII.
`code`	string (optional)	Specific failure mode within `type`.
`details`	any (optional)	Structured context — often the failed Zod issue list.

The HTTP status code follows from type. See Errors for the full table.

Authentication

Bearer-token, scoped to one (account, mode). See Authentication for the details.

Where to go from here

Authentication — how API keys work.
Errors — full error type table and status codes.
Rate limits — request ceilings and Retry-After semantics.
Idempotency — making writes safe across retries.

Resource endpoints:

Agents — POST /v1/agents, GET /v1/agents, GET /v1/agents/{id}
Payments — POST /v1/payments, GET /v1/payments/{id}

Get started

Concepts

Guides

API reference

SDK reference

Ops

Resources

API overview

Base URL

Versioning

Request format

Response format

Error format

Authentication

Where to go from here

​Base URL

​Versioning

​Request format

​Response format

​Error format

​Authentication

​Where to go from here

Base URL

Versioning

Request format

Response format

Error format

Authentication

Where to go from here