API Reference

Thermidora REST API v1 — Complete Integration Guide

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

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 a compute environment. 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

Instances

5 endpoints

An instance is a dedicated compute environment running an OpenClaw gateway. Multiple agents share one instance.

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.

Messages

3 endpoints

Skills

Secrets

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

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
Min Balance to Launch	$0.50