Getting Started

This guide walks you through generating an API key, making your first API call, understanding authentication, rate limits, and error handling.

Prerequisites

• A Conferbot account on the Starter plan or above. API access is not available on the Free plan. View plans
• At least one chatbot created in your workspace.

Step 1: Generate an API Key

1. Log in to your Conferbot dashboard.
2. Navigate to Workspace → API Keys tab.
3. Click "Generate API Key".
4. Copy the generated key immediately - it will be partially masked after creation.

Keys are plain 32-character hex strings with no prefix, for example a3f8c2e91b4d7f60a1b2c3d4e5f60718.

Step 2: Authentication

All API requests must include your API key in the x-api-key header:

curl -X GET "https://api-v2.conferbot.com/api/v1/external/v1/chatbots" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

If the key is missing or invalid, the API returns 401 Unauthorized:

{
  "error": "Missing API key. Include x-api-key header."
}

{
  "error": "Invalid API key"
}

Step 3: Make Your First Request

Let's verify your setup by listing all chatbots in your workspace:

curl -X GET "https://api-v2.conferbot.com/api/v1/external/v1/chatbots" \
  -H "x-api-key: YOUR_API_KEY"

A successful response looks like:

{
  "data": [
    {
      "id": "64f8a2b3c1d4e5f6a7b8c9d0",
      "name": "Customer Support Bot",
      "disabled": false,
      "responseCount": 12847,
      "createdAt": "2024-09-01T10:30:00.000Z",
      "updatedAt": "2024-12-15T14:22:00.000Z"
    }
  ]
}

Base URL

All API endpoints use the following base URL:

https://api-v2.conferbot.com/api/v1

External API endpoints are prefixed with /external/v1/. For example, the full URL for listing chatbots is:

https://api-v2.conferbot.com/api/v1/external/v1/chatbots

Rate Limits

The API enforces two types of rate limiting:

Per-minute burst

60 requests per minute per API key, shared across our cluster. Exceeding this returns 429 Too Many Requests with a Retry-After header. Burst 429s do NOT consume your monthly quota - only successful (2xx) and server-error (5xx) calls are billed.

Monthly quota + plan caps

Response headers

Every response carries both sets so you can throttle accordingly:

# Per-minute burst (IETF draft headers)
RateLimit-Policy:     60;w=60
RateLimit-Limit:      60
RateLimit-Remaining:  47
RateLimit-Reset:      32          # seconds until window resets

# Monthly quota
X-Quota-Limit:        200000
X-Quota-Remaining:    198650
X-Quota-Reset:        1782864000  # Unix epoch of next month start
X-Quota-Period:       month

Check your current usage anytime via the Usage endpoint.

curl -X GET "https://api-v2.conferbot.com/api/v1/external/v1/usage" \
  -H "x-api-key: YOUR_API_KEY"

{
  "data": {
    "month": "2025-01",
    "plan": "Starter",
    "used": 1423,
    "limit": 10000,
    "remaining": 8577
  }
}

Error Handling

The API uses standard HTTP status codes. Error responses include a descriptive error field:

Error response format

Every error response uses the same envelope: a string error message. Specific error classes (e.g. rate limit) also set a machine-readable code.

{
  "error": "Chatbot not found"
}

{
  "error": "External API rate limit exceeded. Max 60 requests per minute.",
  "code": "RATE_LIMIT_ERROR"
}

Next Steps