API Reference

The Hatcher API lets you programmatically manage agents, send messages, and control agent lifecycle from your own applications.

Programmatic API Base URL: https://api.hatcher.host/api/v1

Authentication, billing, dashboard, and support routes use the regular API base URL: https://api.hatcher.host.

Interactive API Explorer — Browse, try, and download all endpoints in the live Swagger UI at api.hatcher.host/docs . Download the raw OpenAPI spec at api.hatcher.host/openapi.json .

Authentication

Hatcher supports two authentication methods: JWT tokens (from email/password login) and API keys (for programmatic access).

Register a new account


curl -X POST https://api.hatcher.host/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "username": "you", "password": "YourSecurePass123"}'

Response:


{
  "success": true,
  "data": {
    "registered": true,
    "requiresVerification": true,
    "message": "If this email can be registered, a verification email will be sent shortly."
  }
}

Registration does not authenticate the new account. Verify the email address, then sign in to receive JWT and refresh tokens.


curl -X POST https://api.hatcher.host/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "YourSecurePass123"}'

Response:


{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "hrt_...",
    "expiresIn": "7d",
    "user": {
      "id": "uuid",
      "email": "[email protected]",
      "username": "you",
      "tier": "free"
    }
  }
}

JWT tokens expire after 7 days. Refresh tokens last 30 days and are returned in the response and browser hatcher_refresh cookie. New email/password accounts must verify their email before sign-in and API-key creation.

API Keys

For programmatic access, use an API key instead of JWT:

Get your API key

Sign in at hatcher.host
Verify your email address
Go to Dashboard → Settings → API Keys
Create a named key. The full hk_ key is shown only once.

Use in requests

Include your API key as a Bearer token in the Authorization header:


curl -H "Authorization: Bearer hk_your_api_key_here" \
  https://api.hatcher.host/api/v1/me

Keep your API key secret. Never commit it to Git or expose it in client-side code. If compromised, revoke it and create a new key in dashboard settings.

Quick Start

Get up and running in seconds. These examples show how to list your agents and send a chat message.

cURL


# List your agents
curl -H "Authorization: Bearer hk_your_api_key" \
  https://api.hatcher.host/api/v1/agents
 
# Send a chat message
curl -X POST https://api.hatcher.host/api/v1/agents/AGENT_ID/chat \
  -H "Authorization: Bearer hk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, what can you do?"}'

Python


import requests
 
API_KEY = "hk_your_api_key"
BASE = "https://api.hatcher.host/api/v1"
headers = {"Authorization": f"Bearer {API_KEY}"}
 
# List your agents
agents = requests.get(f"{BASE}/agents", headers=headers).json()
for agent in agents["data"]["agents"]:
    print(f"{agent['name']} ({agent['status']})")
 
# Send a chat message
resp = requests.post(
    f"{BASE}/agents/{agents['data']['agents'][0]['id']}/chat",
    headers=headers,
    json={"message": "Hello, what can you do?"},
)
print(resp.json()["data"]["content"])

JavaScript


const API_KEY = "hk_your_api_key";
const BASE = "https://api.hatcher.host/api/v1";
const headers = { Authorization: `Bearer ${API_KEY}` };
 
// List your agents
const agents = await fetch(`${BASE}/agents`, { headers }).then(r => r.json());
for (const agent of agents.data.agents) {
  console.log(`${agent.name} (${agent.status})`);
}
 
// Send a chat message
const resp = await fetch(`${BASE}/agents/${agents.data.agents[0].id}/chat`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({ message: "Hello, what can you do?" }),
}).then(r => r.json());
 
console.log(resp.data.content);

Response Format

All responses use a consistent JSON envelope:

Success


{
  "success": true,
  "data": { ... }
}

Endpoints

GET /me

Returns the authenticated user’s profile.


curl -H "Authorization: Bearer hk_..." \
  https://api.hatcher.host/api/v1/me

Response:


{
  "success": true,
  "data": {
    "id": "uuid",
    "walletAddress": "AbcDef...",
    "referralCode": "ALICE2026",
    "hatchCredits": 0,
    "aiCreditsBalance": 500,
    "createdAt": "2026-03-01T00:00:00.000Z"
  }
}

walletAddress — Solana wallet linked to the account (null if not linked)
referralCode — Your unique referral code for sharing
hatchCredits — Legacy field kept for compatibility; always 0
aiCreditsBalance — Current hosted-usage AI Credit balance

GET /usage

Returns your current usage stats for today.


curl -H "Authorization: Bearer hk_..." \
  https://api.hatcher.host/api/v1/usage

Response:


{
  "success": true,
  "data": {
    "today": 12,
    "limit": 100,
    "remaining": 88,
    "resetAt": "2026-03-21T00:00:00.000Z"
  }
}

GET /agents

List all your agents.

cURL


curl -H "Authorization: Bearer hk_..." \
  https://api.hatcher.host/api/v1/agents

Python


resp = requests.get(f"{BASE}/agents", headers=headers)
agents = resp.json()["data"]["agents"]

JavaScript


const { data } = await fetch(`${BASE}/agents`, { headers }).then(r => r.json());
const agents = data.agents;

Response:


{
  "success": true,
  "data": {
    "agents": [
      {
        "id": "uuid",
        "name": "CryptoSage",
        "slug": "cryptosage-a1b2",
        "status": "active",
        "framework": "openclaw",
        "messageCount": 1234,
        "createdAt": "2026-03-10T00:00:00.000Z"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  }
}

GET /agents/:id

Get detailed information about a specific agent. Sensitive config values (API keys, tokens) are masked.


curl -H "Authorization: Bearer hk_..." \
  https://api.hatcher.host/api/v1/agents/AGENT_ID

Response:


{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "CryptoSage",
    "slug": "cryptosage-a1b2",
    "description": "Crypto market analysis bot",
    "status": "active",
    "framework": "openclaw",
    "config": {
      "personality": "Analytical and data-driven",
      "OPENAI_API_KEY": "***"
    },
    "integrations": ["telegram", "discord"],
    "messageCount": 1234,
    "createdAt": "2026-03-10T00:00:00.000Z"
  }
}

GET /agents/:id/status

Lightweight status check (faster than full details).


curl -H "Authorization: Bearer hk_..." \
  https://api.hatcher.host/api/v1/agents/AGENT_ID/status

Response:


{
  "success": true,
  "data": {
    "status": "active",
    "containerId": "abc123def456",
    "messageCount": 1234
  }
}

POST /agents/:id/chat

Send a message to your agent and get a response. Supports conversation history for multi-turn chat.

cURL


curl -X POST \
  -H "Authorization: Bearer hk_..." \
  -H "Content-Type: application/json" \
  -d '{"message": "What is the current BTC price?"}' \
  https://api.hatcher.host/api/v1/agents/AGENT_ID/chat

Python


resp = requests.post(
    f"{BASE}/agents/AGENT_ID/chat",
    headers=headers,
    json={
        "message": "What is the current BTC price?",
        "history": [
            {"role": "user", "content": "Tell me about Solana"},
            {"role": "assistant", "content": "Solana is a high-performance blockchain..."},
        ],
    },
)
print(resp.json()["data"]["content"])

JavaScript


const resp = await fetch(`${BASE}/agents/AGENT_ID/chat`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({
    message: "What is the current BTC price?",
    history: [
      { role: "user", content: "Tell me about Solana" },
      { role: "assistant", content: "Solana is a high-performance blockchain..." },
    ],
  }),
}).then(r => r.json());
 
console.log(resp.data.content);

Request body:


{
  "message": "What is the current BTC price?",
  "history": [
    { "role": "user", "content": "Tell me about Solana" },
    { "role": "assistant", "content": "Solana is a high-performance blockchain..." }
  ]
}

message (required): Your message, 1-4000 characters
history (optional): Previous conversation turns, max 40 entries

Response:


{
  "success": true,
  "data": {
    "content": "Based on the latest data, BTC is trading at...",
    "model": "openclaw"
  }
}

The chat endpoint first tries to route through the agent’s running container. Hosted fallback usage is routed through the Hatcher LLM proxy and spends AI Credits; BYOK usage is billed by your provider.

POST /agents/:id/start

Start an agent’s container.

cURL


curl -X POST \
  -H "Authorization: Bearer hk_..." \
  https://api.hatcher.host/api/v1/agents/AGENT_ID/start

Python


resp = requests.post(f"{BASE}/agents/AGENT_ID/start", headers=headers)
print(resp.json()["data"]["status"])  # "started"

JavaScript


const { data } = await fetch(`${BASE}/agents/AGENT_ID/start`, {
  method: "POST", headers,
}).then(r => r.json());
console.log(data.status); // "started"

Response:


{
  "success": true,
  "data": {
    "status": "started",
    "containerId": "abc123def456..."
  }
}

POST /agents/:id/stop

Stop an agent’s container. Config is preserved — start again anytime.

cURL


curl -X POST \
  -H "Authorization: Bearer hk_..." \
  https://api.hatcher.host/api/v1/agents/AGENT_ID/stop

Python


resp = requests.post(f"{BASE}/agents/AGENT_ID/stop", headers=headers)
print(resp.json()["data"]["status"])  # "stopped"

JavaScript


const { data } = await fetch(`${BASE}/agents/AGENT_ID/stop`, {
  method: "POST", headers,
}).then(r => r.json());
console.log(data.status); // "stopped"

Response:


{
  "success": true,
  "data": {
    "status": "stopped"
  }
}

POST /agents/:id/restart

Restart an agent’s container (stop + start). Useful after config changes.

cURL


curl -X POST \
  -H "Authorization: Bearer hk_..." \
  https://api.hatcher.host/api/v1/agents/AGENT_ID/restart

Python


resp = requests.post(f"{BASE}/agents/AGENT_ID/restart", headers=headers)
print(resp.json()["data"]["status"])  # "restarted"

JavaScript


const { data } = await fetch(`${BASE}/agents/AGENT_ID/restart`, {
  method: "POST", headers,
}).then(r => r.json());
console.log(data.status); // "restarted"

Response:


{
  "success": true,
  "data": {
    "status": "restarted",
    "containerId": "new123container..."
  }
}

Dashboard Agent Endpoints

The endpoints below use the regular dashboard API base URL: https://api.hatcher.host/agents. They require a JWT from the web app auth flow.

POST /agents/:id/pair-channel

Start a QR code pairing session for a messaging platform (currently WhatsApp, Signal planned).


curl -X POST \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"channel": "whatsapp"}' \
  https://api.hatcher.host/agents/AGENT_ID/pair-channel

Request body:


{
  "channel": "whatsapp"
}

Response:


{
  "success": true,
  "data": {
    "qrCode": "2@abc123...",
    "expiresIn": 60
  }
}

The qrCode value should be rendered as a QR code for the user to scan with their phone. The code expires after approximately 60 seconds. Call the endpoint again to generate a new one.

GET /agents/:id/container-files

List files in the agent’s container workspace. File Manager is included on every tier.


curl -H "Authorization: Bearer <jwt>" \
  "https://api.hatcher.host/agents/AGENT_ID/container-files?path=/"

Query parameters:

path (optional): Directory path to list, defaults to / (workspace root)

Response:


{
  "success": true,
  "data": {
    "files": [
      { "name": "config.json", "type": "file", "size": 1234 },
      { "name": "data", "type": "directory", "size": 0 }
    ]
  }
}

Returns 403 Forbidden if the agent does not belong to the authenticated user or the runtime cannot access the requested path.

GET /agents/:id/container-files/read

Read a file from the agent’s container workspace. Requires File Manager access.


curl -H "Authorization: Bearer <jwt>" \
  "https://api.hatcher.host/agents/AGENT_ID/container-files/read?path=/config.json"

Query parameters:

path (required): File path to read

Response:


{
  "success": true,
  "data": {
    "content": "{ \"key\": \"value\" }",
    "size": 1234
  }
}

PUT /agents/:id/container-files

Write or update a file in the agent’s container workspace. Requires File Manager access.


curl -X PUT \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"path": "/notes.txt", "content": "Hello world"}' \
  https://api.hatcher.host/agents/AGENT_ID/container-files/write

Response:


{
  "success": true,
  "data": {
    "path": "/notes.txt",
    "size": 11
  }
}

DELETE /agents/:id/container-files

Delete a file from the agent’s container workspace. Requires File Manager access.


curl -X DELETE \
  -H "Authorization: Bearer <jwt>" \
  "https://api.hatcher.host/agents/AGENT_ID/container-files/delete?path=/notes.txt"

Response:


{
  "success": true,
  "data": {
    "deleted": "/notes.txt"
  }
}

POST /agents/:id/chat/stream

Stream a response token-by-token using Server-Sent Events (SSE). Useful for building real-time chat UIs.


curl -X POST \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"message": "Explain Solana staking"}' \
  --no-buffer \
  https://api.hatcher.host/agents/AGENT_ID/chat/stream

Request body: Same as /chat — message (required), history (optional).

Response: text/event-stream — each event is a JSON token:


data: {"token":"Solana"}
data: {"token":" staking"}
data: {"token":" allows..."}
data: [DONE]

On error: data: {"error": "message"} followed by data: [DONE].

The streaming endpoint routes through the agent container when available and uses the configured hosted or BYOK model path.

GET /agents/:id/chat/history

Load the stored conversation history for this agent (last 200 messages, 30-day rolling window).


curl -H "Authorization: Bearer <jwt>" \
  https://api.hatcher.host/agents/AGENT_ID/chat/history

Response:


{
  "success": true,
  "data": {
    "messages": [
      { "role": "user", "content": "Hello!", "ts": 1711234567890 },
      { "role": "assistant", "content": "Hi there!", "ts": 1711234568000 }
    ]
  }
}

POST /agents/:id/chat/history

Replace the full conversation history (sync state from client to server).


curl -X POST \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Hi"}, {"role": "assistant", "content": "Hello!"}]}' \
  https://api.hatcher.host/agents/AGENT_ID/chat/history

Response:


{ "success": true, "data": { "saved": 2 } }

DELETE /agents/:id/chat/history

Clear the conversation history for this agent.


curl -X DELETE \
  -H "Authorization: Bearer <jwt>" \
  https://api.hatcher.host/agents/AGENT_ID/chat/history

Response:


{ "success": true, "data": { "cleared": true } }

POST /agents

Create a new agent.


curl -X POST \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CryptoSage",
    "framework": "openclaw",
    "description": "Analyzes crypto markets",
    "config": { "personality": "Analytical and concise" }
  }' \
  https://api.hatcher.host/agents

Request body:

Field	Type	Required	Description
`name`	string	Yes	Agent name, 2–50 characters
`framework`	string	Yes	`openclaw` or `hermes`
`description`	string	No	Short description
`avatarUrl`	string	No	Avatar image URL
`config`	object	No	Framework-specific config

Response: 201 Created with the new agent object.

Agent limits apply per tier: Free = 1, Starter = 1, Pro = 3, Business = 10, Founding Member = 10. Add-on packs can increase the limit. Exceeding the limit returns 400.

PATCH /agents/:id

Update an agent’s name, description, or config. Config is deep-merged with the existing config — you only need to send changed keys.


curl -X PATCH \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"config": {"personality": "Cheerful and helpful"}, "commitMessage": "Update personality"}' \
  https://api.hatcher.host/agents/AGENT_ID

Request body:

Field	Type	Description
`name`	string	New agent name
`description`	string	New description
`avatarUrl`	string	New avatar URL
`config`	object	Config fields to merge (deep merge)
`commitMessage`	string	Optional version commit message

Response: Updated agent object. Config changes automatically create a version snapshot.

DELETE /agents/:id

Delete an agent and stop its container. This action is irreversible.


curl -X DELETE \
  -H "Authorization: Bearer <jwt>" \
  https://api.hatcher.host/agents/AGENT_ID

Response:


{ "success": true, "data": { "deleted": true } }

GET /agents/by-slug/:slug

Look up an agent by its URL slug. Public endpoint — returns limited info for unauthenticated requests.


curl https://api.hatcher.host/agents/by-slug/cryptosage-a1b2

Response: Agent object. If authenticated as the owner, returns full config (with sensitive fields masked). Otherwise returns public fields only.

GET /agents/:id/logs

Stream or fetch container logs. Full Logs are included on every tier.


# Fetch last 100 lines
curl -H "Authorization: Bearer <jwt>" \
  "https://api.hatcher.host/agents/AGENT_ID/logs?tail=100"
 
# Stream live logs (SSE)
curl -H "Authorization: Bearer <jwt>" \
  "https://api.hatcher.host/agents/AGENT_ID/logs?stream=true"

Query parameters:

tail (number): Number of lines to return (default 100)
stream (boolean): Stream live via SSE
token (string): Container auth token (used internally)

Response: Plain text log lines, or SSE stream.

GET /agents/:id/feed

Recent activity feed for the agent (messages, status changes, errors).


curl -H "Authorization: Bearer <jwt>" \
  https://api.hatcher.host/agents/AGENT_ID/feed

Response:


{
  "success": true,
  "data": {
    "events": [
      { "type": "message", "content": "User asked about BTC", "ts": "2026-03-21T10:00:00.000Z" },
      { "type": "status_change", "content": "Agent started", "ts": "2026-03-21T09:55:00.000Z" }
    ]
  }
}

GET /agents/:id/memory

Read the agent’s internal memory (key-value store persisted inside the container).


curl -H "Authorization: Bearer <jwt>" \
  https://api.hatcher.host/agents/AGENT_ID/memory

Response:


{
  "success": true,
  "data": {
    "memory": {
      "user_preferences": "Prefers concise answers",
      "last_topic": "Solana DeFi"
    }
  }
}

GET /agents/:id/stats

Live stats for the agent: message count, uptime, last activity.


curl -H "Authorization: Bearer <jwt>" \
  https://api.hatcher.host/agents/AGENT_ID/stats

Response:


{
  "success": true,
  "data": {
    "messagesProcessed": 1234,
    "uptimeSecs": 86400,
    "lastActiveAt": "2026-03-21T10:00:00.000Z",
    "containerId": "abc123def456",
    "status": "active"
  }
}

GET /agents/:id/analytics

Message activity over the last 7 days for charts and dashboards.


curl -H "Authorization: Bearer <jwt>" \
  https://api.hatcher.host/agents/AGENT_ID/analytics

Response:


{
  "success": true,
  "data": {
    "days": [
      { "date": "2026-03-15", "messages": 45 },
      { "date": "2026-03-16", "messages": 102 }
    ],
    "total": 147,
    "peak": 102,
    "avgPerDay": 73.5
  }
}

GET /agents/:id/monitoring

Container resource usage (CPU, memory, restart count).


curl -H "Authorization: Bearer <jwt>" \
  https://api.hatcher.host/agents/AGENT_ID/monitoring

Response:


{
  "success": true,
  "data": {
    "cpuPercent": 12.4,
    "memoryMb": 128.3,
    "memoryLimitMb": 1024,
    "restartCount": 0,
    "status": "running"
  }
}

GET /agents/:id/channel-status

Check the connection status of all messaging platform integrations.


curl -H "Authorization: Bearer <jwt>" \
  https://api.hatcher.host/agents/AGENT_ID/channel-status

Response:


{
  "success": true,
  "data": {
    "telegram": { "connected": true, "username": "@mysagebot" },
    "discord": { "connected": false },
    "whatsapp": { "connected": true, "phone": "+1234567890" },
    "twitter": { "connected": false }
  }
}

POST /agents/:id/disconnect-channel

Disconnect a specific platform integration.


curl -X POST \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"channel": "telegram"}' \
  https://api.hatcher.host/agents/AGENT_ID/disconnect-channel

Response:


{ "success": true, "data": { "disconnected": "telegram" } }

GET /agents/:id/config-snapshots

List saved configuration snapshots (versions).


curl -H "Authorization: Bearer <jwt>" \
  https://api.hatcher.host/agents/AGENT_ID/config-snapshots

Response:


{
  "success": true,
  "data": [
    { "id": "snap_uuid", "version": 3, "message": "Added web search skill", "createdAt": "2026-03-20T00:00:00.000Z" },
    { "id": "snap_uuid2", "version": 2, "message": "Updated personality", "createdAt": "2026-03-19T00:00:00.000Z" }
  ]
}

POST /agents/:id/config-snapshots/:snapshotId/restore

Restore the agent’s config to a previous snapshot.


curl -X POST \
  -H "Authorization: Bearer <jwt>" \
  https://api.hatcher.host/agents/AGENT_ID/config-snapshots/SNAPSHOT_ID/restore

Response: Updated agent object with config restored to the snapshot state.

GET /agents/:id/webhook-url

Get the agent’s inbound webhook URL. Send a POST to this URL with {"message": "..."} to chat with the agent from any external system.


curl -H "Authorization: Bearer <jwt>" \
  https://api.hatcher.host/agents/AGENT_ID/webhook-url

Response:


{
  "success": true,
  "data": {
    "webhookUrl": "https://api.hatcher.host/webhooks/in/TOKEN",
    "method": "POST",
    "body": { "message": "your message here" }
  }
}

GET /agents/:id/schedules

List scheduled tasks for the agent.


curl -H "Authorization: Bearer <jwt>" \
  https://api.hatcher.host/agents/AGENT_ID/schedules

Response:


{
  "success": true,
  "data": [
    {
      "id": "job_uuid",
      "name": "Morning briefing",
      "cron": "0 9 * * *",
      "enabled": true,
      "lastRunAt": "2026-03-21T09:00:00.000Z",
      "nextRunAt": "2026-03-22T09:00:00.000Z"
    }
  ]
}

POST /agents/:id/schedules

Create a scheduled task.


curl -X POST \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Morning briefing",
    "cron": "0 9 * * *",
    "message": "Give me a morning crypto market briefing",
    "timezone": "UTC"
  }' \
  https://api.hatcher.host/agents/AGENT_ID/schedules

Request body:

Field	Type	Required	Description
`name`	string	Yes	Human-readable task name
`cron`	string	Yes	Cron expression (UTC)
`message`	string	Yes	Message to send to the agent
`timezone`	string	No	Timezone (default: `UTC`)

DELETE /agents/:id/schedules/:jobId

Delete a scheduled task.


curl -X DELETE \
  -H "Authorization: Bearer <jwt>" \
  https://api.hatcher.host/agents/AGENT_ID/schedules/JOB_ID

POST /agents/:id/schedules/:jobId/pause

Pause a scheduled task without deleting it.


curl -X POST \
  -H "Authorization: Bearer <jwt>" \
  https://api.hatcher.host/agents/AGENT_ID/schedules/JOB_ID/pause

POST /agents/:id/schedules/:jobId/resume

Resume a paused scheduled task.


curl -X POST \
  -H "Authorization: Bearer <jwt>" \
  https://api.hatcher.host/agents/AGENT_ID/schedules/JOB_ID/resume

GET /agents/:id/knowledge

List files in the agent’s knowledge base.


curl -H "Authorization: Bearer <jwt>" \
  https://api.hatcher.host/agents/AGENT_ID/knowledge

Response:


{
  "success": true,
  "data": [
    { "filename": "product-faq.txt", "size": 4096, "uploadedAt": "2026-03-20T00:00:00.000Z" }
  ]
}

POST /agents/:id/knowledge

Upload a file to the agent’s knowledge base (plain text, max 500KB).


curl -X POST \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"filename": "faq.txt", "content": "Q: What is Hatcher?\nA: An AI agent hosting platform."}' \
  https://api.hatcher.host/agents/AGENT_ID/knowledge

DELETE /agents/:id/knowledge/:filename

Remove a file from the knowledge base.


curl -X DELETE \
  -H "Authorization: Bearer <jwt>" \
  https://api.hatcher.host/agents/AGENT_ID/knowledge/faq.txt

GET /agents/:id/skills

List available and installed skills for the agent.


curl -H "Authorization: Bearer <jwt>" \
  https://api.hatcher.host/agents/AGENT_ID/skills

Response:


{
  "success": true,
  "data": {
    "installed": ["web_search", "calculator"],
    "available": ["web_fetch", "memory", "files"],
    "tier": "free",
    "maxSkills": 2
  }
}

POST /agents/:id/skills/install

Install a skill on the agent.


curl -X POST \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"skillId": "web_search"}' \
  https://api.hatcher.host/agents/AGENT_ID/skills/install

POST /agents/:id/skills/uninstall

Uninstall a skill from the agent.


curl -X POST \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"skillId": "web_search"}' \
  https://api.hatcher.host/agents/AGENT_ID/skills/uninstall

POST /agents/:id/scan-token

Scan a Solana token — returns on-chain metadata, live price, and an AI-generated risk analysis. Limited to 10 scans/day.


curl -X POST \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"mintAddress": "So11111111111111111111111111111111111111112"}' \
  https://api.hatcher.host/agents/AGENT_ID/scan-token

Response:


{
  "success": true,
  "data": {
    "mintAddress": "So11111...",
    "name": "Wrapped SOL",
    "symbol": "SOL",
    "decimals": 9,
    "price": 180.42,
    "marketCap": 82000000000,
    "aiSummary": "Wrapped SOL is the canonical wrapped version of native SOL...",
    "scannedAt": "2026-03-21T10:00:00.000Z"
  }
}

POST /agents/:id/research

Run a research task via the agent’s LLM. Limited to 20 tasks/day.


curl -X POST \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"query": "What are the key differences between Proof of Work and Proof of Stake?"}' \
  https://api.hatcher.host/agents/AGENT_ID/research

Response:


{
  "success": true,
  "data": {
    "query": "What are the key differences...",
    "result": "Proof of Work (PoW) requires miners to...",
    "model": "meta-llama/llama-4-scout-17b-16e-instruct",
    "completedAt": "2026-03-21T10:00:00.000Z"
  }
}

GET /agents/:id/wallet-watch

Get live data (balance + recent transactions) for all wallets the agent is watching.


curl -H "Authorization: Bearer <jwt>" \
  https://api.hatcher.host/agents/AGENT_ID/wallet-watch

Response:


{
  "success": true,
  "data": {
    "watchedWallets": [
      {
        "address": "AbcDef...",
        "balance": { "sol": 12.5, "usd": 2250 },
        "transactions": [
          { "signature": "5X...", "type": "TRANSFER", "amount": 1.0, "ts": 1711234567 }
        ]
      }
    ]
  }
}

POST /agents/:id/wallet-watch

Set the wallets the agent watches (max 3).


curl -X POST \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"wallets": ["AbcDef123...", "XyzWvU456..."]}' \
  https://api.hatcher.host/agents/AGENT_ID/wallet-watch

GET /agents/:id/versions

List configuration version history for the agent.


curl -H "Authorization: Bearer <jwt>" \
  "https://api.hatcher.host/agents/AGENT_ID/versions?limit=10&offset=0"

Response:


{
  "success": true,
  "data": [
    { "version": 5, "message": "Added Discord integration", "createdAt": "2026-03-21T00:00:00.000Z" },
    { "version": 4, "message": "Updated personality", "createdAt": "2026-03-20T00:00:00.000Z" }
  ]
}

GET /agents/:id/versions/:version

Get a specific version’s full config snapshot.


curl -H "Authorization: Bearer <jwt>" \
  https://api.hatcher.host/agents/AGENT_ID/versions/4

POST /agents/:id/versions/:version/restore

Restore the agent’s config to a specific version.


curl -X POST \
  -H "Authorization: Bearer <jwt>" \
  https://api.hatcher.host/agents/AGENT_ID/versions/4/restore

POST /agents/test-chat

Test an agent personality with a real LLM call before deploying. Hosted test calls spend AI Credits; BYOK calls are metered by your provider.


curl -X POST \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Tell me about yourself",
    "systemPrompt": "You are a helpful crypto analyst named CryptoSage."
  }' \
  https://api.hatcher.host/agents/test-chat

Response:


{ "success": true, "data": { "text": "I am CryptoSage, your dedicated..." } }

Auth Endpoints

All auth routes are under https://api.hatcher.host/auth/.

POST /auth/refresh

Get a new JWT token using a refresh token. Browser clients may omit the body when the hatcher_refresh httpOnly cookie is present.


curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "hrt_..."}' \
  https://api.hatcher.host/auth/refresh

Response:


{
  "success": true,
  "data": { "token": "eyJ...", "refreshToken": "hrt_...", "expiresIn": "7d" }
}

POST /auth/api-keys

Create a named API key. The full key is returned only once, so store it immediately. Email verification is required.


curl -X POST \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{"label": "Production backend"}' \
  https://api.hatcher.host/auth/api-keys

Response:


{
  "success": true,
  "data": {
    "id": "api_key_uuid",
    "label": "Production backend",
    "key": "hk_full_key_shown_once",
    "prefix": "hk_full_ke...",
    "createdAt": "2026-05-03T00:00:00.000Z"
  }
}

There is no regenerate endpoint. Revoke a compromised key with DELETE /auth/api-keys/:id, then create a replacement key.

GET /auth/notifications

List unread in-app notifications.


curl -H "Authorization: Bearer <jwt>" \
  https://api.hatcher.host/auth/notifications

PATCH /auth/notifications/read

Mark notifications as read.


curl -X PATCH \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["notif_uuid1", "notif_uuid2"]}' \
  https://api.hatcher.host/auth/notifications/read

POST /auth/export-data

Request a GDPR data export. Returns a download URL for a ZIP archive containing all your account data (profile, agents, conversations, configurations, payments).


curl -X POST \
  -H "Authorization: Bearer eyJ..." \
  https://api.hatcher.host/auth/export-data

Response:


{
  "success": true,
  "data": {
    "status": "processing",
    "message": "Your data export is being prepared. You will receive an email with a download link."
  }
}

Data exports typically complete within a few minutes. The download link is valid for 7 days.

Billing Endpoints

All billing routes are under https://api.hatcher.host/features/.

GET /features

List available subscription plans, add-ons, and Founding Member slot availability.


curl https://api.hatcher.host/features

Response:


{
  "success": true,
  "data": {
    "tiers": {
      "free": { "key": "free", "name": "Free", "usdPrice": 0, "includedAgents": 1, "aiCreditsMonthly": 500 },
      "starter": { "key": "starter", "name": "Starter", "usdPrice": 6.99, "includedAgents": 1, "aiCreditsMonthly": 3000 },
      "pro": { "key": "pro", "name": "Pro", "usdPrice": 19.99, "includedAgents": 3, "aiCreditsMonthly": 15000 },
      "business": { "key": "business", "name": "Business", "usdPrice": 49.99, "includedAgents": 5, "aiCreditsMonthly": 40000 },
      "founding_member": { "key": "founding_member", "name": "Founding Member", "usdPrice": 99, "includedAgents": 10, "aiCreditsMonthly": 25000 }
    },
    "tierOrder": ["free", "starter", "pro", "business", "founding_member"],
    "addons": [
      { "key": "addon.agents.3", "name": "+3 Agents", "usdPrice": 6.99, "type": "subscription" },
      { "key": "addon.ai_credits.25000", "name": "25,000 AI Credits", "usdPrice": 30, "type": "one_time" }
    ],
    "founding": { "maxSlots": 20, "taken": 2, "remaining": 18 }
  }
}

GET /features/account

Get your current subscription status and active features.


curl -H "Authorization: Bearer <jwt>" \
  https://api.hatcher.host/features/account

Response:


{
  "success": true,
  "data": {
    "tier": "pro",
    "tierConfig": { "key": "pro", "name": "Pro", "includedAgents": 3 },
    "activeAddons": [
      { "key": "addon.agents.3", "name": "+3 Agents", "extraAgents": 3, "expiresAt": "2026-06-02T00:00:00.000Z" }
    ],
    "agentLimit": 6,
    "agentCount": 3,
    "hatchCredits": 0,
    "aiCredits": {
      "balance": 14500,
      "monthlyGrant": 15000,
      "tier": "pro"
    },
    "subscriptionExpiresAt": "2026-06-02T00:00:00.000Z",
    "chatLimit": 0,
    "searchLimit": 0
  }
}

POST /features/subscribe

Subscribe to a paid tier (starter, pro, business, or founding_member) using SOL, USDC, or $HATCHER on Solana.


curl -X POST \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "tier": "pro",
    "txSignature": "5X9abc...solana_tx_signature",
    "paymentToken": "sol",
    "billingPeriod": "monthly"
  }' \
  https://api.hatcher.host/features/subscribe

Request body:

Field	Type	Required	Description
`tier`	string	Yes	`starter`, `pro`, `business`, or `founding_member`
`txSignature`	string	Yes	Solana transaction signature for payment
`paymentToken`	string	No	`sol`, `usdc`, or `hatch` (defaults to `sol`)
`billingPeriod`	string	No	`monthly` or `annual` (defaults to `monthly`; Founding Member is lifetime)
`solAmount`	number	No	Optional client-side SOL amount hint; the server recomputes the expected amount

The API verifies the on-chain transaction before activating the subscription.

POST /features/addon

Purchase an add-on. Supported add-ons are account-level extra agent slots and one-time AI Credit packs.


curl -X POST \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "addonKey": "addon.agents.3",
    "txSignature": "5X9abc...",
    "paymentToken": "sol",
    "billingPeriod": "monthly"
  }' \
  https://api.hatcher.host/features/addon

POST /features/subscribe-with-credits

Retired. Cash-equivalent credits are no longer a payment rail; this endpoint returns 410 Gone.


curl -X POST \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"tier": "starter", "billingPeriod": "monthly"}' \
  https://api.hatcher.host/features/subscribe-with-credits

POST /features/addon-with-credits

Retired. Cash-equivalent credits are no longer a payment rail; this endpoint returns 410 Gone.

There is no /features/cancel endpoint. Current billing uses fixed-period or one-time purchases; tier access naturally expires at subscriptionExpiresAt.

Support Endpoints

All support routes are under https://api.hatcher.host/support/.

GET /support/tickets

List your support tickets.


curl -H "Authorization: Bearer <jwt>" \
  https://api.hatcher.host/support/tickets

POST /support/tickets

Submit a new support ticket.


curl -X POST \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Agent container not starting",
    "body": "My agent stays in paused state after clicking Start.",
    "category": "technical"
  }' \
  https://api.hatcher.host/support/tickets

WebSocket Chat

For real-time bidirectional chat, connect via WebSocket:


wss://api.hatcher.host/agents/AGENT_ID/ws

Include your API key in the Authorization header (or JWT for dashboard sessions).

Send messages:


{ "type": "chat", "payload": { "message": "Hello!" } }

Receive responses:


{ "type": "chat_response", "payload": { "content": "Hi! How can I help?" } }

Code Examples

JavaScript


const API_KEY = 'hk_your_key_here';
const BASE = 'https://api.hatcher.host/api/v1';
 
// List agents
const agents = await fetch(`${BASE}/agents`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
}).then(r => r.json());
 
// Chat with an agent
const chat = await fetch(`${BASE}/agents/${agentId}/chat`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ message: 'Hello!' }),
}).then(r => r.json());
 
console.log(chat.data.content);

Python


import requests
 
API_KEY = "hk_your_key_here"
BASE = "https://api.hatcher.host/api/v1"
headers = {"Authorization": f"Bearer {API_KEY}"}
 
# List agents
agents = requests.get(f"{BASE}/agents", headers=headers).json()
 
# Chat with an agent
response = requests.post(
    f"{BASE}/agents/{agent_id}/chat",
    headers=headers,
    json={"message": "Hello!"}
).json()
 
print(response["data"]["content"])

cURL


# Set your API key
export HATCHER_API_KEY="hk_your_key_here"
 
# List agents
curl -s -H "Authorization: Bearer $HATCHER_API_KEY" \
  https://api.hatcher.host/api/v1/agents | jq
 
# Chat with an agent
curl -s -X POST \
  -H "Authorization: Bearer $HATCHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello!"}' \
  https://api.hatcher.host/api/v1/agents/AGENT_ID/chat | jq

Referrals Endpoints

All referral routes are under https://api.hatcher.host/referrals/.

Reward: When eligible, both the referrer and referred user receive 500 AI Credits. Eligibility requires the referred user to verify email and create at least one agent.

GET /referrals/my-code

Get your unique referral code and share link. Requires JWT.


curl -H "Authorization: Bearer <jwt>" \
  https://api.hatcher.host/referrals/my-code

Response:


{
  "success": true,
  "data": {
    "referralCode": "ALICE2026",
    "shareLink": "https://hatcher.host/register?ref=ALICE2026",
    "username": "alice"
  }
}

GET /referrals/stats

Get your referral statistics: total referred, total earned, per-referral details. Requires JWT.


curl -H "Authorization: Bearer <jwt>" \
  https://api.hatcher.host/referrals/stats

Response:


{
  "success": true,
  "data": {
    "totalReferred": 5,
    "totalEarned": 500,
    "rewardPerReferral": 100,
    "rewardUnit": "ai_credits",
    "referrals": [
      { "username": "bob", "date": "2026-03-20T12:00:00Z", "rewardClaimed": true }
    ]
  }
}

POST /referrals/claim

Claim pending referral rewards for all eligible referrals. Requires JWT.


curl -X POST \
  -H "Authorization: Bearer <jwt>" \
  https://api.hatcher.host/referrals/claim

Response:


{
  "success": true,
  "data": {
    "claimed": 2,
    "totalCredited": 200,
    "referredCredited": 200,
    "totalAiCreditsGranted": 400,
    "unit": "ai_credits",
    "message": "Claimed 200 AI Credits for you and 200 AI Credits for referred user(s)."
  }
}

GET /referrals/validate/:code

Validate a referral code (public, no auth required). Used on the registration page.


curl https://api.hatcher.host/referrals/validate/ALICE2026

Response:


{ "success": true, "data": { "valid": true, "referrerUsername": "alice" } }

AI Credits Endpoints

All AI Credit routes are under https://api.hatcher.host/ai-credits/. Requires JWT.

Legacy cash-equivalent credit routes under /credits/* are retired and return 410 Gone.

GET /ai-credits/balance

Get the current AI Credit balance, monthly grant size, and normalized tier.


curl -H "Authorization: Bearer <jwt>" \
  https://api.hatcher.host/ai-credits/balance

Response:


{
  "success": true,
  "data": {
    "balance": 14500,
    "monthlyGrant": 15000,
    "tier": "pro"
  }
}

GET /ai-credits/history

Get hosted usage history. Optional ?limit=N (1-100, default 20).


curl -H "Authorization: Bearer <jwt>" \
  "https://api.hatcher.host/ai-credits/history?limit=10"

Response:


{
  "success": true,
  "data": {
    "usage": [
      {
        "kind": "llm",
        "provider": "openrouter",
        "model": "deepseek/deepseek-v4-flash",
        "credits": 12,
        "inputTokens": 420,
        "outputTokens": 180,
        "createdAt": "2026-05-13T10:00:00.000Z"
      }
    ]
  }
}

POST /ai-credits/grant

Admin-only endpoint to grant AI Credits manually.


curl -X POST \
  -H "Authorization: Bearer <admin-jwt>" \
  -H "Content-Type: application/json" \
  -d '{"userId": "user_id", "credits": 1000, "reason": "Manual adjustment"}' \
  https://api.hatcher.host/ai-credits/grant

Error Codes

Status	Meaning
`400`	Bad request — check your input
`401`	Unauthorized — invalid or missing API key / JWT
`403`	Forbidden — you don’t own this agent
`404`	Not found — agent doesn’t exist
`422`	Content blocked by safety filter
`429`	Rate limit exceeded — wait or upgrade
`500`	Server error — try again or contact support

API Reference

Authentication

Sign up and sign in

Register a new account

Sign in

API Keys

Get your API key

Use in requests

Quick Start

cURL

Python

JavaScript

Response Format

Success

Error

Endpoints

GET /me

GET /usage

GET /agents

cURL

Python

JavaScript

GET /agents/:id

GET /agents/:id/status

POST /agents/:id/chat

cURL

Python

JavaScript

POST /agents/:id/start

cURL

Python

JavaScript

POST /agents/:id/stop

cURL

Python

JavaScript

POST /agents/:id/restart

cURL

Python

JavaScript

Dashboard Agent Endpoints

POST /agents/:id/pair-channel

GET /agents/:id/container-files

GET /agents/:id/container-files/read

PUT /agents/:id/container-files

DELETE /agents/:id/container-files

POST /agents/:id/chat/stream

GET /agents/:id/chat/history

POST /agents/:id/chat/history

DELETE /agents/:id/chat/history

POST /agents

PATCH /agents/:id

DELETE /agents/:id

GET /agents/by-slug/:slug

GET /agents/:id/logs

GET /agents/:id/feed

GET /agents/:id/memory

GET /agents/:id/stats

GET /agents/:id/analytics

GET /agents/:id/monitoring

GET /agents/:id/channel-status

POST /agents/:id/disconnect-channel

GET /agents/:id/config-snapshots

POST /agents/:id/config-snapshots/:snapshotId/restore

GET /agents/:id/webhook-url

GET /agents/:id/schedules

POST /agents/:id/schedules

DELETE /agents/:id/schedules/:jobId

POST /agents/:id/schedules/:jobId/pause

POST /agents/:id/schedules/:jobId/resume

GET /agents/:id/knowledge

POST /agents/:id/knowledge

DELETE /agents/:id/knowledge/:filename

GET /agents/:id/skills

POST /agents/:id/skills/install

POST /agents/:id/skills/uninstall

POST /agents/:id/scan-token

POST /agents/:id/research

GET /agents/:id/wallet-watch

POST /agents/:id/wallet-watch