API Reference

REST API for leads, campaigns, and AI agents. Use your API key to create leads, run campaigns, trigger agents, and receive real-time events via webhooks. Build integrations, automate workflows, or plug Cluetik into your existing stack.

Documentation

Base URL & authentication

All API requests use the base URL below and require a valid API key in the Authorization header. Create and rotate keys in the dashboard; never expose them in client-side code.

All requests use the base URL https://api.cluetik.com/v1. Send Content-Type: application/json for request bodies and include your API key in the Authorization header on every request.

curl -X GET "https://api.cluetik.com/v1/leads" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
Authorization: Bearer YOUR_API_KEY

Create and manage API keys in Dashboard → Settings → API Keys. Keys are secret—never expose them in client-side code or public repos. Use separate keys for development and production, and rotate them periodically. Invalid or missing keys return 401 Unauthorized.

Rate limits

Default: 100 requests per minute per API key. Response headers include X-RateLimit-Limit and X-RateLimit-Remaining. When exceeded you receive 429 Too Many Requests; check Retry-After and back off before retrying. Higher limits are available on paid plans.

Error responses

Errors return JSON with code and message. Common codes: 401 invalid/missing key, 403 forbidden, 404 resource not found, 422 validation error (invalid fields or missing required data).

{ "code": "validation_error", "message": "email is required" }

Endpoints

Click an endpoint to expand parameters, request body, and response examples. All paths are relative to the base URL. Required fields are indicated in the request body; omit optional fields or leave them null. Timestamps are in ISO 8601 (UTC).

Webhooks

Receive real-time events by registering a webhook URL. We send POST requests with a signed payload; verify the signature and respond with 2xx to acknowledge. Configure and manage webhooks in Settings → Webhooks.

Register a webhook URL in Settings → Webhooks. When an event occurs we send a POST request to your URL with a JSON body and the X-Cluetik-Signature header. The signature is HMAC-SHA256 of the raw request body using your webhook secret—always verify it before processing to avoid spoofed events.

Verifying the signature

Compute HMAC-SHA256(body, webhook_secret) and compare with the header value (we send the hex-encoded digest). If they match, the payload is authentic. Respond with 2xx within 10 seconds to acknowledge; otherwise we retry.

Event types

  • lead.createdEmitted when a new lead is created (API or UI)
  • lead.updatedLead fields or status changed
  • lead.deletedA lead was permanently deleted
  • campaign.startedCampaign was started and is now active
  • campaign.completedCampaign reached end condition or was stopped
  • campaign.pausedCampaign was paused; can be restarted later
  • email.sentAn outreach email was sent to a lead
  • email.repliedA lead replied to an outreach email
  • email.openedAn outreach email was opened (if tracking enabled)
  • call.completedAn AI call ended; payload includes outcome and duration

Example payload

{
  "id": "evt_abc123",
  "event": "lead.created",
  "created_at": "2024-01-15T10:00:00Z",
  "data": {
    "id": "lead_xyz",
    "email": "jane@company.com",
    "first_name": "Jane",
    "company": "Acme Inc"
  }
}

Retries: We retry failed deliveries with exponential backoff (e.g. 1m, 5m, 30m). Respond with 2xx within 10 seconds to acknowledge. Use idempotent handling—the same event may be delivered more than once. After repeated failures we may disable the webhook and notify you via email.