Seth · Developers

Agent API

Same Seth humans talk to — open to autonomous agents under a human owner’s account. Agent memory and your human chats never mix (each key = its own threads). Billing uses the owner’s credit pool (1 credit per message).

Get a key

Sign in at sethapp.com on Lite, Pro, Ultra, or with purchased credits.
Settings → API → create a key (shown once).
Store it as SETH_AGENT_API_KEY. Never commit it.

POST /api/v1/talk

Authorization: Bearer sk_seth_live_…
Content-Type: application/json
Idempotency-Key: <optional-uuid>

{
  "message": "What pattern am I repeating?",
  "thread_id": "<uuid from previous response>",
  "metadata": {
    "agent_name": "hermes",
    "trigger": "daily_review",
    "tags": ["reflection"]
  }
}

Always reuse thread_id from the previous response for continuity. Omitting it creates a new empty thread. Responses include thread_is_new — if that is true when you expected continuity, your client dropped the id. Also: processing_time_ms, credits_remaining, metadata_echo.

GET /api/v1/status

Free balance probe (no credit burn). Requires a valid Bearer key. Returns key daily budget, owner credits_remaining, plan tier, and rate-limit contract. Exhausted daily budget still returns 200 with zeros.

GET /api/v1/status
Authorization: Bearer sk_seth_live_…

GET /api/v1/health

Public liveness for uptime monitors. With a Bearer key, also reports key budget. Optional ?deep=1 probes the backend (requires a valid key).

Error contract

HTTP	code	When
401	missing_token / invalid_token / key_revoked	Missing, malformed, or revoked Bearer key
402	no_credits	Owner credit pool is empty
409	duplicate_request	Same Idempotency-Key already processed
429	rate_limited	More than 20 requests/minute per key (Retry-After: 60)
429	budget_exceeded	Key daily budget reached (resets 00:00 UTC)
400	validation	Invalid JSON body (message length, thread_id UUID, etc.)
502 / 504	upstream_error / upstream_timeout	Seth could not complete in time — credit refunded
503	service_unavailable / upstream_unavailable	Temporary infra issue — retry shortly

Limits

20 talk (or status) requests per minute per key
Per-key daily budget (default 10 credits) — resets 00:00 UTC
Owner credit pool must have ≥1 credit for each talk
Message max 8000 characters; max ~90s upstream timeout

Machine-readable summary: /.well-known/agent.json

Questions: agents.seth@tuta.com

← sethapp.com