Conversations, Threads, Usage & Health API

These endpoints provide access to conversation history, threaded messaging, usage analytics, and system health status. Together they give you full programmatic control over your ClawHQ data and operational monitoring.

Conversations API

GET /api/v1/conversations

Retrieves a paginated list of conversations across your deployed agents. Each conversation represents a distinct interaction session between a user and an agent.

Query Parameters

Response

{
  "conversations": [
    {
      "id": "conv_abc123",
      "agent": "support-bot",
      "session_id": "user_12345",
      "message_count": 8,
      "started_at": "2026-03-16T09:00:00Z",
      "last_message_at": "2026-03-16T09:12:30Z",
      "status": "completed"
    }
  ],
  "total": 142,
  "limit": 20,
  "offset": 0
}

Code Example (cURL)

curl "https://app.clawhq.tech/api/v1/conversations?agent=support-bot&limit=10" \
  -H "Authorization: Bearer clw_your_api_key_here"

Code Example (Python)

import requests

API_KEY = "clw_your_api_key_here"

response = requests.get(
    "https://app.clawhq.tech/api/v1/conversations",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={"agent": "support-bot", "limit": 10},
)

data = response.json()
for conv in data["conversations"]:
    print(f"{conv['id']} - {conv['message_count']} messages ({conv['status']})")

Code Example (JavaScript)

const API_KEY = "clw_your_api_key_here";

const params = new URLSearchParams({ agent: "support-bot", limit: "10" });
const response = await fetch(
  `https://app.clawhq.tech/api/v1/conversations?${params}`,
  { headers: { "Authorization": `Bearer ${API_KEY}` } }
);

const { conversations, total } = await response.json();
console.log(`Showing ${conversations.length} of ${total} conversations`);

Threads API

List Threads

GET /api/v1/threads

Returns a list of message threads. Threads group related messages into a structured conversation that can be continued over time using the same thread ID.

{
  "threads": [
    {
      "id": "thr_xyz789",
      "title": "Product inquiry - Enterprise pricing",
      "agent": "sales-assistant",
      "message_count": 12,
      "created_at": "2026-03-15T14:00:00Z",
      "updated_at": "2026-03-16T08:30:00Z"
    }
  ]
}

Create Thread

POST /api/v1/threads

Creates a new message thread with an initial message.

// Request
{
  "title": "Integration help",
  "agent": "support-bot",
  "message": "How do I integrate the Chat API with my React app?"
}

// Response
{
  "thread": {
    "id": "thr_new123",
    "title": "Integration help",
    "agent": "support-bot",
    "message_count": 2,
    "created_at": "2026-03-16T10:00:00Z"
  },
  "response": "I'd be happy to help you integrate the Chat API with React..."
}

Add Message to Thread

POST /api/v1/threads/:id/messages

Appends a message to an existing thread and returns the agent's response. The agent has access to the full thread history for context.

// Request
{
  "message": "Can you show me a code example with TypeScript?"
}

// Response
{
  "message_id": "msg_abc456",
  "response": "Here's a TypeScript example using the fetch API...",
  "thread_id": "thr_new123"
}

Code Example (Python)

import requests

API_KEY = "clw_your_api_key_here"
BASE_URL = "https://app.clawhq.tech/api/v1"
headers = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

# Create a new thread
result = requests.post(
    f"{BASE_URL}/threads",
    headers=headers,
    json={
        "title": "Integration help",
        "agent": "support-bot",
        "message": "How do I integrate the Chat API?"
    },
).json()

thread_id = result["thread"]["id"]
print(f"Thread created: {thread_id}")
print(f"Response: {result['response']}")

# Continue the conversation
follow_up = requests.post(
    f"{BASE_URL}/threads/{thread_id}/messages",
    headers=headers,
    json={"message": "Show me a TypeScript example"},
).json()

print(f"Follow-up: {follow_up['response']}")

Usage API

GET /api/v1/usage

Returns API usage statistics for your account over a specified time period. Use this endpoint to monitor consumption, detect anomalies, and plan capacity.

Query Parameters

Response

{
  "usage": {
    "total_requests": 15420,
    "total_tokens": 2843000,
    "period_start": "2026-02-14T00:00:00Z",
    "period_end": "2026-03-16T00:00:00Z",
    "daily": [
      {
        "date": "2026-03-16",
        "requests": 520,
        "tokens": 96000,
        "avg_latency_ms": 1240
      }
    ],
    "by_agent": [
      {
        "agent": "support-bot",
        "requests": 12300,
        "tokens": 2100000
      },
      {
        "agent": "sales-assistant",
        "requests": 3120,
        "tokens": 743000
      }
    ]
  }
}

Code Example (cURL)

curl "https://app.clawhq.tech/api/v1/usage?days=7" \
  -H "Authorization: Bearer clw_your_api_key_here"

Code Example (JavaScript)

const API_KEY = "clw_your_api_key_here";

const response = await fetch(
  "https://app.clawhq.tech/api/v1/usage?days=7",
  { headers: { "Authorization": `Bearer ${API_KEY}` } }
);

const { usage } = await response.json();
console.log(`Total requests (7d): ${usage.total_requests.toLocaleString()}`);
console.log(`Total tokens (7d): ${usage.total_tokens.toLocaleString()}`);

usage.by_agent.forEach((a) => {
  console.log(`  ${a.agent}: ${a.requests} requests`);
});

Health API

GET /api/v1/health

Returns the current health status of your ClawHQ instance, including the API server, VPS, and deployed agents. Use this endpoint for uptime monitoring and alerting integrations.

Response

{
  "status": "healthy",
  "timestamp": "2026-03-16T10:30:00Z",
  "components": {
    "api": "operational",
    "vps": "operational",
    "agents": "operational",
    "gateway": "operational"
  },
  "uptime_seconds": 864000,
  "version": "3.2.1"
}

Status Values

Code Example (cURL)

curl https://app.clawhq.tech/api/v1/health \
  -H "Authorization: Bearer clw_your_api_key_here"

Error Responses

All endpoints on this page return standard error responses:

Next Steps

• Chat API — Send messages to agents
• Rate Limits — Understand rate limiting and best practices
• Authentication — API key management