Base URL https://echo.relevanceai.io/api/v1. Send a workspace API key in every request:
export ECHO_API_KEY=... # from Settings, API
curl "https://echo.relevanceai.io/api/v1/campaigns" -H "Authorization: Bearer $ECHO_API_KEY"Successful responses are { "data": ... }; errors are { "error": "message" } with a status code. Settings, API shows cURL, JavaScript and Python examples for each endpoint.
Endpoints
| Method and path | Does | Key |
|---|---|---|
GET /campaigns | List campaigns with their funnel | Read |
GET /campaigns/{id} | One campaign: funnel, top leads, section attention | Read |
GET /campaigns/{id}/links | Each lead's link on your domain | Read |
GET /leads?campaign_id=&status=&min_heat=&q=&limit= | Leads with heat and signals, highest heat first (limit default 50, max 500) | Read |
GET /leads/{id} | One lead's visits and clicks | Read |
GET /signals?since_hours=24 | Recent signals | Read |
GET /groups | Lead groups | Read |
GET /designs | Designs | Read |
POST /groups | Import leads: {"group_name": "...", "rows": [...]} or {"group_id": "...", "rows": [...]} | Write |
POST /campaigns | Create campaign: {"name", "design_id", "group_id", "instruction"?, "research"?} | Write |
POST /campaigns/{id}/send-links | Send links: {"source", "list_id", "variable"?} | Write |
Example: import, publish, send
# 1. Import leads into a new group
curl -X POST "https://echo.relevanceai.io/api/v1/groups" \
-H "Authorization: Bearer $ECHO_API_KEY" -H "Content-Type: application/json" \
-d '{"group_name":"Webinar attendees","rows":[{"first_name":"Maya","company":"Helion","email":"maya@helion.io"}]}'
# 2. Create the campaign (spends AI on your key)
curl -X POST "https://echo.relevanceai.io/api/v1/campaigns" \
-H "Authorization: Bearer $ECHO_API_KEY" -H "Content-Type: application/json" \
-d '{"name":"Webinar follow-up","design_id":"DESIGN_ID","group_id":"GROUP_ID"}'
# 3. Write links into Lemlist
curl -X POST "https://echo.relevanceai.io/api/v1/campaigns/CAMPAIGN_ID/send-links" \
-H "Authorization: Bearer $ECHO_API_KEY" -H "Content-Type: application/json" \
-d '{"source":"lemlist","list_id":"cam_123","variable":"echo_link"}'Status codes
| Code | Meaning |
|---|---|
400 | Invalid request (for example no rows, an empty group, or a campaign name that already exists) |
401 | Missing, wrong or revoked key |
402 | Plan limit (for example tool features on Free) |
403 | Read-only key used for a write |
404 | Not found in this workspace |
409 | Needs a Live domain first |
429 | Over 120 requests a minute for this key |
Limits
Up to 2,000 rows per import call and 2,000 leads per campaign. For pushed events instead of polling, use Webhooks.