Skip to main content
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" }
  }
}
FieldTypeDescription
typestringCoarse-grained category — unauthenticated, forbidden, not_found, etc. Drives the HTTP status.
messagestringHuman-readable. Safe to log; no PII.
codestring (optional)Specific failure mode within type.
detailsany (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

Resource endpoints:
  • Agents — POST /v1/agents, GET /v1/agents, GET /v1/agents/{id}
  • Payments — POST /v1/payments, GET /v1/payments/{id}