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", then choose the permissions and expiry for the key.
4. Copy the generated key immediately - it is shown once and only a hash is stored, so a lost key can be replaced but never recovered.

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

Scopes

A key can be limited to the permissions an integration actually needs. Scopes are chosen when the key is created and cannot be changed afterwards - issue a new key to change them.

A write scope does not imply its read counterpart. An integration that only pushes data has no need to read conversation transcripts, so grant both explicitly when both are required.

Calling an endpoint outside a key's scopes returns 403 Forbidden, naming what was needed:

{
  "error": "This API key is missing the \"chatbots:write\" scope.",
  "requiredScope": "chatbots:write",
  "grantedScopes": ["chatbots:read", "responses:read"]
}

The same limits apply to the MCP server: a scoped key only sees the tools and resources it is allowed to use, so a read-only key exposes 27 of the 52 tools rather than failing at call time.

Expiry and rotation

A key can be given an expiry when it is created - 30, 90 or 365 days, or never. After it expires, requests return 401:

{
  "error": "API key has expired. Generate a new key.",
  "expiredAt": "2026-11-16T09:12:44.201Z"
}

The dashboard records when each key was last used, so you can tell a live key from a forgotten one before revoking it. Revocation takes effect immediately.

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, plus a tighter limit on one endpoint group:

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.

Email change

The three /account/email/* endpoints share a limit of 5 requests per hour per API key, because each one can send mail to an address the caller supplies.

Monthly quota + plan caps

One REST request costs one call. A JSON-RPC batch sent to the MCP endpoint costs one call per message, not one per HTTP request - so a batch of five tool calls draws five from the quota. Batches are capped at 20 messages.

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