API Overview

Cueflow provides a REST API for server-to-server integration. Use it to sync contacts, track events, and manage user data from your backend.

When to Use the API

Use API	Use Embed Script
Backend/server-side operations	Frontend/browser operations
Webhook handlers	User-initiated actions
Batch operations	Real-time user tracking
Database sync	Displaying messages

Base URL

https://app.cueflow.so/api/v1

Authentication

All API requests require authentication via API key.

Getting an API Key

1. Go to Settings > API Keys in the dashboard

2. Click Create API Key

3. Copy the key (shown only once)

Using Your Key

Include the API key in the Authorization header:

Authorization: Bearer sk_your_api_key_here

Example Request

curl -X GET https://app.cueflow.so/api/v1/contacts/user-123 \
  -H "Authorization: Bearer sk_a1b2c3d4e5f6..."

Response Format

Success Response

{
  "success": true,
  "contact": {
    "id": "clx123...",
    "externalId": "user-123",
    "email": "[email protected]",
    "name": "Jane Smith"
  }
}

Error Response

{
  "error": "Not found",
  "message": "Contact not found"
}

HTTP Status Codes

Code	Description
200	Success
201	Created
400	Bad Request - Invalid input
401	Unauthorized - Invalid or missing API key
404	Not Found - Resource doesn't exist
409	Conflict - Resource already exists
429	Rate Limited - Too many requests
500	Server Error

Rate Limiting

API requests are rate limited to protect service stability.

Limit	Value
Requests per minute	100
Per API key	Yes

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1702500000

Handling Rate Limits

If you exceed the limit, you'll receive a 429 response:

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please retry after 60 seconds."
}

Best practices:

• Add delays between batch operations

• Implement exponential backoff

• Cache responses when possible

Endpoints

Contacts

Method	Endpoint	Description
POST	/contacts	Create or update a contact
GET	/contacts/:externalId	Get a contact
PATCH	/contacts/:externalId	Update a contact
DELETE	/contacts/:externalId	Delete a contact

Events

Method	Endpoint	Description
POST	/events	Track an event

Quick Start

1. Create a Contact

curl -X POST https://app.cueflow.so/api/v1/contacts \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "user-123",
    "email": "[email protected]",
    "name": "Jane Smith",
    "plan": "pro"
  }'

2. Track an Event

curl -X POST https://app.cueflow.so/api/v1/events \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "user-123",
    "eventKey": "purchase_completed",
    "properties": {
      "amount": 99.99,
      "plan": "pro"
    }
  }'

3. Update a Contact

curl -X PATCH https://app.cueflow.so/api/v1/contacts/user-123 \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "enterprise"
  }'

SDKs & Libraries

Currently, we provide a REST API. Official SDKs are coming soon.

For now, use any HTTP client:

• Node.js: axios, node-fetch

• Python: requests, httpx

• Ruby: httparty, faraday

• Go: net/http

• PHP: Guzzle

Next Steps

• Contacts API - Full contacts endpoint reference

• Events API - Full events endpoint reference

• API Keys - Managing your API keys