API Documentation

Complete reference for the comxbot API. All endpoints use JSON request/response bodies, return a consistent error envelope, and support idempotency keys for safe retries.

Base URL

https://app.comxbot.com

All API paths are relative to this base URL. Use HTTPS for all requests.

Authentication

Public endpoints

Routes under /api/public/v1/ do not require authentication. They are rate-limited by IP address. These endpoints power the embeddable chat widget and public forms.

Organisation endpoints

Routes under /api/org/v1/ require a valid Clerk session with an active organisation context. Include the session token via cookie or the Authorization: Bearer <token> header.

API Keys

For server-to-server integration, generate Organisation API Keys in Settings > API Keys. Pass the key as a Bearer token. Keys are scoped to the organisation and can be rotated at any time.

Webhook verification

All inbound webhooks must be verified against the raw request body. Clerk uses Svix signatures, Stripe uses Stripe-Signature. Never transform the body before verification.

Security note: Never expose Organisation API keys in client-side code. Use them only in server-to-server communication.

Public API

No authentication required. Rate-limited by IP address (20 requests/minute for chat, 5/minute for enquiries).

Method	Endpoint	Description
POST	`/api/public/v1/chat/sessions`	Create a new anonymous chat session with a public assistant. Returns a session ID and token for subsequent message calls.
POST	`/api/public/v1/chat/messages`	Send a message within an existing chat session. Returns the assistant's response with citations and proposed actions. Supports streaming via SSE.
POST	`/api/public/v1/enquiries`	Submit a public enquiry form with data minimisation. Creates an enquiry record and optionally triggers routing to the appropriate assistant or human team.
GET	`/api/public/v1/answers/{answerId}`	Retrieve a previously generated answer by ID, including full citations, confidence score, and source references.

Organisation API

Requires Clerk session with active organisation context or a valid Organisation API Key.

Method	Endpoint	Description
POST	`/api/org/v1/sources`	Create a new knowledge source. Specify type (url, pdf, sitemap, google_drive, onedrive, manual), configuration, and sync schedule.
POST	`/api/org/v1/ingest-jobs`	Trigger an ingestion job for one or more sources. Returns a job ID for tracking progress. Supports full re-ingest or incremental update.
GET	`/api/org/v1/sources/{sourceId}/health`	Get source health metrics: freshness score, citation rate, retrieval score, stale detection status, and last sync timestamp.
GET	`/api/org/v1/inbox/threads`	List inbox threads with filtering by status (open, in_progress, resolved), assignment, priority, and date range. Paginated.
POST	`/api/org/v1/handoffs`	Create a handoff packet with risk assessment. Includes transcript, summary, intent, sentiment, and routes to the appropriate team.
POST	`/api/org/v1/actions/proposals`	Create an action proposal with dry-run analysis. Includes action type, parameters, conversation context, and approval requirements.
POST	`/api/org/v1/actions/{proposalId}/approve`	Approve a pending action proposal. Optionally include parameter modifications. Moves the proposal to execution stage.
POST	`/api/org/v1/actions/{proposalId}/execute`	Execute an approved action. Calls the configured webhook or built-in handler. Returns execution result and logs to audit trail.
GET	`/api/org/v1/templates`	List all prompt templates for the organisation. Templates are reusable system prompt fragments for assistant configuration.
POST	`/api/org/v1/templates`	Create a new prompt template. Specify name, content, variables (mustache-style placeholders), and category.
GET	`/api/org/v1/safeguarding`	Get the current safeguarding configuration: detection keywords, response messages, escalation contacts, and severity thresholds.
PUT	`/api/org/v1/safeguarding`	Update safeguarding configuration. Requires admin role. Changes are logged in the audit trail.
POST	`/api/org/v1/thinkguide/sessions`	Create a new ThinkGuide guided learning session. Specify the module, difficulty ceiling and hint depth. Returns a session ID for subsequent step interactions.
POST	`/api/org/v1/thinkguide/sessions/{sessionId}/step`	Submit a learner response within a ThinkGuide session. Returns the next hint, follow-up question or confirmation depending on the learner's progress through the scaffolded steps.
GET	`/api/org/v1/thinkguide/sessions/{sessionId}`	Retrieve a ThinkGuide session including all steps, hints given, learner responses and time spent. Useful for tutor review dashboards.
GET	`/api/org/v1/learner-accessibility/{learnerId}`	Get the stored accessibility preferences for a learner: preferred mode (plain, chunked, guided), reading level ceiling and session persistence settings.
PUT	`/api/org/v1/learner-accessibility/{learnerId}`	Update a learner's accessibility preferences. Changes take effect on the next message in any active session.

Webhooks

Inbound webhooks from third-party services. Always verify signatures before processing.

Method	Endpoint	Description
POST	`/api/webhooks/clerk`	Receives Clerk webhook events: user.created, user.updated, user.deleted, organization.created, organization.updated, membership.created, membership.deleted. Verified via Svix signatures.
POST	`/api/webhooks/stripe`	Receives Stripe webhook events: checkout.session.completed, customer.subscription.updated, customer.subscription.deleted, invoice.payment_succeeded, invoice.payment_failed. Verified via Stripe-Signature header.

Webhook Verification Example

When comxbot sends webhooks to your custom action endpoints, each request includes a signature header:

const crypto = require('crypto');

function verifyComxbotWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your handler:
const signature = req.headers['x-comx-signature'];
const isValid = verifyComxbotWebhook(
  JSON.stringify(req.body),
  signature,
  process.env.COMX_WEBHOOK_SECRET
);

if (!isValid) {
  return res.status(401).json({ error: 'Invalid signature' });
}

The signature is HMAC-SHA256 of the raw request body using your webhook secret (found in Settings > Webhooks). Always verify before processing.

Error Codes

All errors follow a consistent envelope format:

{
  "error": {
    "code": "COMX_VALIDATION_ERROR",
    "message": "Human-readable description",
    "request_id": "req_abc123",
    "retryable": false,
    "details": { "field": "email" }
  }
}

Code	HTTP	Description
`COMX_VALIDATION_ERROR`	400	Request body failed schema validation. Check required fields and data types.
`COMX_UNAUTHENTICATED`	401	Missing or invalid authentication credentials.
`COMX_FORBIDDEN`	403	Authenticated but lacking required permissions for this operation.
`COMX_NOT_FOUND`	404	Requested resource does not exist in this workspace.
`COMX_IDEMPOTENCY_CONFLICT`	409	Request conflicts with a previous idempotent operation.
`COMX_POLICY_BLOCK`	403	Action blocked by a workspace policy (e.g. safeguarding not configured).
`COMX_RATE_LIMITED`	429	Too many requests. Check Retry-After header for wait time.
`COMX_PROVIDER_UNAVAILABLE`	503	Upstream AI provider is temporarily unavailable. Retryable with backoff.
`COMX_INTERNAL_ERROR`	500	Unexpected server error. Include the request_id when contacting support.

Rate Limiting

Public chat

requests per minute per IP

Public enquiries

requests per minute per IP

Org API

requests per minute per key

When rate-limited, the response includes a Retry-After header with the number of seconds to wait. All mutating endpoints accept an Idempotency-Key header for safe retries.

// Rate limit response headers
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 54
X-RateLimit-Reset: 1716550000
Retry-After: 42  // Only present on 429 responses

Need help? Contact support or visit the Help Centre.