REST API

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 REST API	Use JavaScript SDK
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 API Keys in the sidebar

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 YOUR_API_KEY

Example Request

curl -X POST https://app.cueflow.so/api/v1/contacts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "name": "John Doe"}'

Rate Limiting

API requests are rate limited to protect service stability.

Limit	Value
Requests per minute	300
Per API key	Yes

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 295
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

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

Endpoints

Contacts

Method	Endpoint	Description
POST	/contacts	Create or update a contact
DELETE	/contacts/:identifier	Delete a contact by email or externalId

Events

Method	Endpoint	Description
POST	/events	Track an event

POST /api/v1/contacts

Create or update a contact. Uses email as the identifier.

Request Body

Field	Type	Required
email	string	Yes
externalId	string	No
name	string	No
phone	string	No
plan	string	No
role	string	No
signedUpAt	ISO string	No
customAttributes	object	No

Example

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

DELETE /api/v1/contacts/:identifier

Delete a contact by email or externalId.

Example

curl -X DELETE https://app.cueflow.so/api/v1/contacts/[email protected] \
  -H "Authorization: Bearer YOUR_API_KEY"

POST /api/v1/events

Track an event for a contact. The contact must exist first.

Request Body

Field	Type	Required
email	string	Yes
event	string	Yes
properties	object	No

Example

curl -X POST https://app.cueflow.so/api/v1/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "event": "purchase_made", "properties": {"amount": 99.99}}'

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