Synaptiq API

Authentication

Public endpoints (/api/chat, /api/widget, /api/health) require no authentication.

All other endpoints require an API key. Include it as a Bearer token in the Authorization header, or authenticate via the admin token flow to obtain a session cookie.

curl https://app.synaptiq.ai/api/admin/leads \
  -H "Authorization: Bearer YOUR_API_KEY"

Session-based Authentication

curl -X POST https://app.synaptiq.ai/api/admin/auth \
  -H "Content-Type: application/json" \
  -d '{"token": "your-admin-token"}'

Leads API

Create, retrieve, update, and search leads captured by the Synaptiq chat agent. All leads endpoints require authentication.

curl https://app.synaptiq.ai/api/leads \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "leads": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "company": "Acme Corp",
      "status": "qualified",
      "qualificationScore": 78,
      "createdAt": "2026-04-01T14:30:00.000Z"
    }
  ]
}

curl https://app.synaptiq.ai/api/leads/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X POST https://app.synaptiq.ai/api/admin/leads \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "email": "jane@example.com",
    "company": "Acme Corp"
  }'

curl -X PATCH https://app.synaptiq.ai/api/leads/550e8400... \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "booked", "qualificationScore": 92}'

curl "https://app.synaptiq.ai/api/leads?q=acme" \
  -H "Authorization: Bearer YOUR_API_KEY"

Conversations API

Access the full message history of AI chat conversations.

curl https://app.synaptiq.ai/api/leads/550e8400.../conversations \
  -H "Authorization: Bearer YOUR_API_KEY"

curl https://app.synaptiq.ai/api/conversations/660e8400... \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "conversation": {
    "id": "660e8400-e29b-41d4-a716-446655440000",
    "leadId": "550e8400-e29b-41d4-a716-446655440000",
    "channel": "web_chat",
    "status": "completed",
    "summary": "Prospect asked about pricing and integration.",
    "messages": [
      {
        "role": "assistant",
        "content": "Hey there! What brings you here today?",
        "createdAt": "2026-04-01T14:30:01.000Z"
      },
      {
        "role": "user",
        "content": "I need help handling inbound leads faster.",
        "createdAt": "2026-04-01T14:30:15.000Z"
      }
    ]
  }
}

Knowledge Base API

Upload, list, and manage documents that the AI agent uses to answer questions. Supports PDF, DOCX, and plain text formats.

curl -X POST https://app.synaptiq.ai/api/admin/knowledge-base \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Product FAQ",
    "content": "Q: What is Synaptiq?\nA: An AI-powered SDR agent...",
    "type": "faq"
  }'

curl https://app.synaptiq.ai/api/admin/knowledge-base \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X DELETE https://app.synaptiq.ai/api/admin/knowledge-base/doc-id \
  -H "Authorization: Bearer YOUR_API_KEY"

Analytics API

Access performance metrics, funnel data, and daily activity for your pipeline.

curl https://app.synaptiq.ai/api/analytics/overview \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "funnel": {
    "new": 45,
    "qualifying": 32,
    "qualified": 28,
    "booked": 21,
    "disqualified": 12,
    "nurturing": 4
  }
}

{
  "activity": [
    { "date": "2026-03-06", "count": 3 },
    { "date": "2026-03-07", "count": 7 },
    { "date": "2026-03-08", "count": 0 }
  ]
}

Webhooks

Receive real-time notifications when events happen in your Synaptiq account. Configure webhook URLs in your dashboard under Settings → Webhooks.

Event Types

Payloads

All webhook payloads follow the same envelope format:

{
  "event": "lead.created",
  "timestamp": "2026-04-01T14:30:00.000Z",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "company": "Acme Corp",
    "status": "new",
    "qualificationScore": 0
  }
}

Signature Verification

Each webhook request includes an X-Synaptiq-Signature header containing an HMAC-SHA256 signature of the request body using your webhook secret.

import crypto from 'crypto';

function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected),
  );
}

Retry Policy

If your endpoint returns a non-2xx status code or times out (30s), Synaptiq retries with exponential backoff: 1 min, 5 min, 30 min, 2 hours, 24 hours. After 5 failed attempts the event is dropped and logged in your dashboard.

SDK Quickstart

Get Synaptiq running on your site in under 2 minutes.

1. 1
   Install the widget

   Add the embed script to your site. No npm package required for the basic widget.

<script
  src="https://app.synaptiq.ai/widget.js"
  data-tenant="YOUR_TENANT_ID"
></script>

2. 2
   Listen for events

   React to lead qualification and meeting events from the widget.

// Listen for Synaptiq events
window.addEventListener('synaptiq:lead.qualified', (e) => {
  console.log('Lead qualified:', e.detail);
  // Push to your CRM, trigger a Slack notification, etc.
});

window.addEventListener('synaptiq:meeting.booked', (e) => {
  console.log('Meeting booked:', e.detail);
});

3. 3
   Control programmatically (optional)

   Use the global SynaptiqWidget API to open, close, or update the widget at runtime.

// Open the chat when a CTA button is clicked
document.getElementById('talk-to-ai')
  .addEventListener('click', () => SynaptiqWidget.open());

// Dynamically switch tenant
SynaptiqWidget.setTenant('new-tenant-id');

// Remove the widget entirely
SynaptiqWidget.destroy();

Rate Limits

Requests are rate-limited per API key based on your plan tier. Exceeding the limit returns a 429 Too Many Requests response with a Retry-After header.

Error Codes

All errors return a JSON body with an error field.

{
  "error": "Description of what went wrong"
}