REST API reference (v1)

The API base URL is https://insta-production-b43e.up.railway.app/api/v1. Create keys in Settings → Developer; a key is shown once. Send it as Authorization: Bearer lfg_live_… (or the X-API-Key header). Each key allows 300 requests per minute.

Send a DM

curl -X POST https://insta-production-b43e.up.railway.app/api/v1/messages \
  -H "Authorization: Bearer lfg_live_XXXX" -H "Content-Type: application/json" \
  -d '{
    "username": "asha.rao",
    "text": "Your order #1042 has shipped!",
    "buttons": [{ "title": "Track order", "url": "https://shop.example.com/t/1042" }],
    "callback_data": "order-1042"
  }'

Identify the person by username or contact_id. buttons is optional (up to 3). A successful call returns 201 with { "result": true, "id": "…", "message_id": "…", "status": "sent" }; outside the reply window it returns 409.

Upsert a contact

curl -X POST https://insta-production-b43e.up.railway.app/api/v1/contacts \
  -H "Authorization: Bearer lfg_live_XXXX" -H "Content-Type: application/json" \
  -d '{ "username": "asha.rao", "email": "asha@example.com", "tags": ["vip"], "traits": { "city": "Pune" } }'

Update an existing contact by username or contact_id, or create/update one by phone (for leads from outside Instagram). Tags are added, never removed; traits are merged. Returns { "result": true, "id": "…", "created": false }.

Track an event

curl -X POST https://insta-production-b43e.up.railway.app/api/v1/events \
  -H "Authorization: Bearer lfg_live_XXXX" -H "Content-Type: application/json" \
  -d '{ "username": "asha.rao", "event": "order_placed", "properties": { "order_id": "1042", "total": "1499" } }'

Records the event on the contact and starts any published flow whose trigger listens for that event name. Returns 202.

List contacts

• GET /v1/contacts?limit=50&offset=0 — paginated, with has_next_page, including each contact's Instagram username

Errors