Thermidora - Your AI Agent, Always On

🔗Base URL: https://core.thermidora.com/v1

🔐All endpoints require Authorization: Bearer <jwt> or X-API-Key: tc_live_... — except send-code, verify-code, and GET /skills

Quick Start — 4 Steps

Get from zero to a working agent conversation

Authenticate — POST /auth/send-code → POST /auth/verify-code
Get a JWT token via email OTP. Or create an API key for programmatic access.

Create an instance — POST /instances
Provisions compute (ECS container). Takes ~2 min. Poll GET /instances/:id until status: "running".

Create an agent — POST /instances/:id/agents
Define its persona with workspace files (SOUL.md, IDENTITY.md). Use useDefaults: true for sensible defaults.

Send a message — POST /instances/:id/agents/:id/messages
Your agent responds. Stream with stream: true for real-time token output.

Authentication

5 endpoints

POST/auth/send-codeSend OTP code to email▶

POST/auth/verify-codeVerify OTP, get JWT token▶

GET/auth/meCurrent account info▶

POST/auth/keysCreate API key▶

GET/auth/keysList API keys▶

Instances

5 endpoints

An instance is a compute environment (ECS Fargate container) running an OpenClaw gateway. Multiple agents share one instance. Pricing: $0.03/hr while running, free when stopped.

POST/instancesCreate instance▶

GET/instancesList all instances▶

GET/instances/:idGet instance details + live status▶

POST/instances/:id/stopStop instance (billing paused)▶

DELETE/instances/:idDestroy instance permanently▶

Agents

5 endpoints

Agents are AI personas inside an instance. Each agent has a workspace with markdown files defining its personality and behavior. The slug is used as the workspace folder name and must be unique within an instance.

POST/instances/:id/agentsCreate agent with persona▶

GET/instances/:id/agentsList agents▶

GET/instances/:id/agents/:idGet agent details▶

PATCH/instances/:id/agents/:idUpdate agent persona/config▶

DELETE/instances/:id/agents/:idDelete agent▶

Messages

3 endpoints

POST/instances/:id/agents/:id/messagesSend message to agent▶

GET/instances/:id/agents/:id/messagesGet message history▶

GET/instances/:id/agents/:id/eventsSSE event stream▶

Skills

GET/skillsList built-in skills catalog▶

POST/instances/:id/skillsInstall skill▶

GET/instances/:id/skillsList installed skills▶

DELETE/instances/:id/skills/:nameUninstall skill▶

Secrets

POST/instances/:id/secretsStore secrets▶

GET/instances/:id/secretsList secret keys▶

DELETE/instances/:id/secrets/:keyDelete secret▶

Error Responses

All errors follow a consistent format:

{
  "error": {
    "code": "invalid_request",
    "message": "email is required",
    "status": 400
  }
}

Code	Status	Description
`invalid_request`	400	Missing or invalid parameters
`unauthorized`	401	Missing or invalid auth token
`invite_required`	403	Valid invite code required for registration
`not_found`	404	Resource doesn't exist or not owned by you
`conflict`	409	Duplicate resource (e.g. agent slug exists)
`payment_required`	402	Insufficient balance — x402 payment needed
`instance_not_ready`	503	Instance not in running state

Codeinvalid_request

Status400

DescriptionMissing or invalid parameters

Codeunauthorized

Status401

DescriptionMissing or invalid auth token

Codeinvite_required

Status403

DescriptionValid invite code required for registration

Codenot_found

Status404

DescriptionResource doesn't exist or not owned by you

Codeconflict

Status409

DescriptionDuplicate resource (e.g. agent slug exists)

Codepayment_required

Status402

DescriptionInsufficient balance — x402 payment needed

Codeinstance_not_ready

Status503

DescriptionInstance not in running state

Complete Example

End-to-end: authenticate → create instance → create agent → chat

bash

# 1. Authenticate
curl -X POST https://core.thermidora.com/v1/auth/send-code \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "inviteCode": "TC-BETA-2026"}'

curl -X POST https://core.thermidora.com/v1/auth/verify-code \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "code": "123456", "name": "You"}'
# → save the "token" from response

# 2. Create instance
curl -X POST https://core.thermidora.com/v1/instances \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-org"}'
# → save "instanceId", poll GET /instances/:id until status is "running"

# 3. Create agent
curl -X POST https://core.thermidora.com/v1/instances/INSTANCE_ID/agents \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Assistant",
    "slug": "assistant",
    "displayName": "Ava",
    "useDefaults": true,
    "files": {
      "SOUL.md": "You are Ava, a helpful assistant."
    }
  }'
# → save "agentId"

# 4. Send a message
curl -X POST https://core.thermidora.com/v1/instances/INSTANCE_ID/agents/AGENT_ID/messages \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hello! What can you do?",
    "sender": {"type": "human", "id": "user1", "name": "You"}
  }'

x402 Payment Protocol

Agent Payments

Agents can pay for resources programmatically using USDC stablecoins. Any endpoint that requires balance returns a 402 with payment instructions.

x402 Flow

# 1. Request fails with 402
POST /v1/instances
← 402 Payment Required
{
  "error": { "code": "payment_required" },
  "x402": {
    "amount": "0.50",
    "currency": "USDC",
    "network": "base",
    "recipient": "0x742d...4F8c"
  }
}

# 2. Agent pays on-chain, retries with proof
POST /v1/instances
X-PAYMENT: {"txHash":"0x...","network":"base"}
← 201 Created ✓

Detail	Value
Supported Networks	Base · Ethereum · Polygon
Currency	USDC
Minimum Top-up	$1.00
Instance Pricing	$0.03/hr (stopped = free)
Min Balance to Launch	$0.50

DetailSupported Networks

ValueBase · Ethereum · Polygon

DetailCurrency

ValueUSDC

DetailMinimum Top-up

Value$1.00

DetailInstance Pricing

Value$0.03/hr (stopped = free)

DetailMin Balance to Launch

Value$0.50