Skip to content
Skip to content

API Access PRO

The API Access module lets you interact with your ClawHQ instance programmatically. Create and manage API keys, set per-key rate limits, test endpoints in the interactive playground, and integrate with any language or framework using the REST API.

API Key Management

API keys are managed from the API Access page in your dashboard. Each key is a credential that grants programmatic access to your ClawHQ instance.

Key Format

All API keys use the clw_ prefix followed by 32 random alphanumeric characters, for a total of 36 characters. Example:

clw_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

The clw_ prefix makes it easy to identify ClawHQ keys in your codebase and prevents accidental use of keys from other services. Secret scanners and credential detectors can also use this prefix to flag exposed keys.

Creating Keys

When creating a key, you provide a descriptive name (e.g., "production-backend", "staging-test", "mobile-app"). The name is for your reference only — it does not affect the key's permissions. After creation, the full key is shown once. Copy it immediately, as it cannot be retrieved later.

Per-Key Rate Limits

Each key can be assigned its own rate limit to control how many requests per minute it is allowed to make. Available rate limit tiers:

  • 30 RPM — Suitable for development and testing
  • 60 RPM — Standard production usage (default for the /v1/chat endpoint)
  • 120 RPM — High-throughput applications
  • 300 RPM — Maximum throughput for high-volume integrations
Note: Rate limits are applied per API key, not per endpoint. The configured RPM for a key applies uniformly across all endpoints. The /v1/chat endpoint defaults to 60 RPM for new keys.

When a key exceeds its rate limit, the API returns a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait before retrying.

Revoking Keys

Revoke a key at any time from the dashboard. Revocation is immediate — any request using the revoked key will receive a 401 Unauthorized response. Revoked keys cannot be restored; create a new key if needed.

Security best practice: Create separate API keys for each environment (development, staging, production) and each integration. This way, if a key is compromised, you can revoke it without affecting other systems.

Authentication

Include your API key in the Authorization header using the Bearer scheme:

Authorization: Bearer $CLAWHQ_API_KEY

All API requests must be made over HTTPS. Requests over plain HTTP are rejected. For detailed endpoint documentation, see the API Authentication reference.

Interactive API Playground

The API Playground is built into your dashboard, so you can test API calls without leaving the browser. Select an endpoint from the dropdown, fill in the parameters, and send the request. The playground shows the full request (method, URL, headers, body) and the complete response (status code, headers, body) side by side.

The playground uses your selected API key for authentication, so you can verify that each key has the correct rate limits and access. Response bodies are syntax-highlighted and formatted for readability.

SSE Streaming

For chat endpoints, you can enable Server-Sent Events (SSE) streaming by setting the stream parameter to true. When streaming is enabled, the response is delivered as a series of SSE events, with each event containing a chunk of the agent's response as it is generated.

POST /api/v1/chat
Content-Type: application/json
Authorization: Bearer $CLAWHQ_API_KEY

{
  "message": "Explain how webhooks work",
  "agent": "support-bot",
  "stream": true
}

The response is a stream of text/event-stream events. Each chunk contains acontent field with the generated text. The stream terminates with adata: [DONE] sentinel:

data: {"content": "Webhooks are "}
data: {"content": "HTTP callbacks "}
data: {"content": "that notify your server..."}
data: [DONE]
Note: If a stream error occurs, an error event is sent as {"error": {"code": "stream_error", "message": "..."}} followed by data: [DONE].

Code Examples

JavaScript / Node.js

const CLAWHQ_API_KEY = process.env.CLAWHQ_API_KEY;

const response = await fetch("https://app.clawhq.tech/api/v1/chat", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${CLAWHQ_API_KEY}`
  },
  body: JSON.stringify({
    message: "What are your business hours?",
    agent: "support-bot"
  })
});

const data = await response.json();
console.log(data.response);

Python

import os
import requests

API_KEY = os.environ["CLAWHQ_API_KEY"]

response = requests.post(
    "https://app.clawhq.tech/api/v1/chat",
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {API_KEY}"
    },
    json={
        "message": "What are your business hours?",
        "agent": "support-bot"
    }
)

data = response.json()
print(data["response"])

cURL

curl -X POST https://app.clawhq.tech/api/v1/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $CLAWHQ_API_KEY" \
  -d '{"message": "What are your business hours?", "agent": "support-bot"}'

Go

apiKey := os.Getenv("CLAWHQ_API_KEY")

payload := map[string]string{
    "message": "What are your business hours?",
    "agent":   "support-bot",
}
body, _ := json.Marshal(payload)

req, _ := http.NewRequest("POST",
    "https://app.clawhq.tech/api/v1/chat",
    bytes.NewBuffer(body))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+apiKey)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
Tip: Use the interactive playground to build and test your request, then copy the generated code snippet in your preferred language. The playground generates working code for all four languages shown above.

Error Handling

The API uses standard HTTP status codes. Common responses:

  • 200 OK — Request succeeded
  • 400 Bad Request — Invalid parameters or missing required fields
  • 401 Unauthorized — Missing, invalid, or revoked API key
  • 429 Too Many Requests — Rate limit exceeded; check the Retry-After header
  • 500 Internal Server Error — Server-side error; retry with exponential backoff

All error responses return a nested JSON structure with an error object containing a machine-readable code, human-readable message, error type, and a unique request_id:

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry after 60 seconds.",
    "type": "rate_limit_error",
    "request_id": "req_abc123"
  }
}

Related Documentation