CueDMDocs
API reference

API

API reference

Every endpoint under /api/v1: the workspace, accounts and posts, automations, the knowledge base, webhook subscriptions and sample payloads.

Basics

All endpoints are under https://cuedm.com/api/v1, take and return JSON, and need a workspace API key. Everything a key can see or change belongs to that key's workspace.

POST /hooksWebhooks
Subscribe a URL to events.
DELETE /hooks/:idWebhooks
Unsubscribe.
GET /events/:event/sampleEvents
Recent payloads for one event.
GET /accountsAccounts
Connected Instagram accounts.
GET /accounts/:id/postsAccounts
An account's recent posts and reels.
GET /automationsAutomations
List automations.
POST /automationsAutomations
Create an automation.
GET /automations/:idAutomations
Get one automation.
PATCH /automations/:idAutomations
Change it, or turn it on or off.
GET /automations/:id/resultsAutomations
How it's doing.
GET /accounts/:id/knowledgeKnowledge
The knowledge base's sources.
POST /accounts/:id/knowledgeKnowledge
Add to the knowledge base.
GET /accounts/:id/prospectsOutreach
Outreach prospects and the funnel.
POST /accounts/:id/prospectsOutreach
Enroll prospects by handle.
POST /accounts/:id/prospects/removeOutreach
Take prospects out of outreach.

Every endpoint, generated

The full reference, with every field and a request builder, is generated from the API itself at cuedm.com/api/v1/docs, and the OpenAPI document is at /api/v1/openapi.json. Contacts and messages aren't available through the API yet (the MCP server has them); email support@cuedm.com if you need them.

Get the workspace

GET/api/v1/me

Returns the workspace the key belongs to and its connected Instagram accounts. Use it to check that a key works and to label the connection with the workspace's name.

cURL
curl https://cuedm.com/api/v1/me \
  -H "Authorization: Bearer $CUEDM_API_KEY"
Response
{
  "workspace": {
    "id": "cmfz8o3gq0000l50gk3ah2d9e",
    "name": "Your Brand",
    "plan": "STUDIO"
  },
  "accounts": [
    {
      "id": "cmfz8p1aa0002l50g3n7c5k2x",
      "username": "yourbrand"
    }
  ]
}
workspace.idstring
The same ID as workspaceId in webhook payloads.
workspace.namestring
The workspace's name.
workspace.planstring
FREE, CREATOR or STUDIO.
accounts[].idstring
The Instagram account in CueDM, as in account.id in events.
accounts[].usernamestring
Its Instagram handle. Only connected accounts are listed.

Accounts and posts

GET/api/v1/accounts

The workspace's connected Instagram accounts, newest first.

Response
[
  {
    "id": "cmfz8p1aa0002l50g3n7c5k2x",
    "username": "yourbrand",
    "name": "Your Brand"
  }
]
GET/api/v1/accounts/:id/posts

The account's recent posts and reels, newest first, up to 50: the IDs an automation's postId takes. Add ?refresh=true to read Instagram first, for a post published in the last few minutes.

Response
{
  "instagramAccountId": "cmfz8p1aa0002l50g3n7c5k2x",
  "refreshedAt": "2026-10-08T09:58:00.000Z",
  "posts": [
    {
      "id": "17900000000000001",
      "type": "VIDEO",
      "caption": "5-minute ab finisher. Comment GUIDE for the full routine",
      "permalink": "https://www.instagram.com/reel/abc/",
      "thumbnailUrl": "https://…",
      "postedAt": "2026-10-07T18:00:00.000Z"
    }
  ]
}

List and get automations

GET/api/v1/automations

Every automation in the workspace, newest first. Add ?instagramAccountId= for one account's. GET /api/v1/automations/:id returns one.

An automation
{
  "id": "cmh2k9q0a0007l50g1b2c3d4e",
  "name": "Free guide",
  "isActive": false,
  "instagramAccountId": "cmfz8p1aa0002l50g3n7c5k2x",
  "trigger": {
    "post": {
      "id": "17900000000000001"
    },
    "keywords": [
      "guide"
    ],
    "matchAnyWord": false,
    "dms": false
  },
  "dmMessage": "Here's the guide!",
  "links": [
    {
      "url": "https://example.com/guide",
      "label": "Get the guide"
    }
  ],
  "publicReplies": [
    "Sent you a DM!"
  ],
  "url": "https://cuedm.com/automations/cmh2k9q0a0007l50g1b2c3d4e",
  "createdAt": "2026-10-08T10:00:00.000Z"
}
isActiveboolean
Whether it answers comments now.
trigger.postobject | string
A post as { id }, "any" for every post, or "next_reel" for the next reel posted.
trigger.keywordsstring[]
Words that set it off. Empty with matchAnyWord: true means any comment.
trigger.dmsboolean
Also fires on a DM containing a keyword.
linksobject[]
The DM's buttons. Clicks are tracked.
publicRepliesstring[]
Replies posted under the comment, one picked at random. Empty when off.
urlstring
Where a person reviews it in CueDM.

Create an automation

POST/api/v1/automations

The body takes the same fields as the automation builder; the OpenAPI document lists all of them. The common ones:

namestringrequired
Up to 100 characters.
dmMessagestringrequired
The DM, up to 1,000 characters.
instagramAccountIdstring
Defaults to the most recently connected account.
postIdstring
A post from the posts list. Or send matchAnyPost: true or pendingNextReel: true.
keywordsstring[]
Up to 10. Or send matchAnyWord: true.
trackedDestinationUrlstring
A link the DM shows as a button; linkButtonLabel names it.
publicReplyEnabledboolean
With publicReplyMessages, replies under the comment.
isActiveboolean
Defaults to true. Send false to leave it for a person to review first.
curl https://cuedm.com/api/v1/automations \
  -H "Authorization: Bearer $CUEDM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name": "Free guide", "postId": "17900000000000001", "keywords": ["guide"], "dmMessage": "Here is the guide!", "trackedDestinationUrl": "https://example.com/guide", "linkButtonLabel": "Get the guide", "isActive": false}'

Answers 201 with { automation, warning }. warning is set when the automation saved but something on Instagram's side didn't, such as a conversation starter. A plan that can't turn on another automation answers 403.

Update, turn on or pause

PATCH/api/v1/automations/:id

Only the fields you send change. { "isActive": true } turns it on and false pauses it. Answers with { automation, warning }.

cURL
curl -X PATCH https://cuedm.com/api/v1/automations/cmh2k9q0a0007l50g1b2c3d4e \
  -H "Authorization: Bearer $CUEDM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"isActive": true}'

Automation results

GET/api/v1/automations/:id/results

How it's doing over the last ?days=7, 30 (the default) or 90.

Response
{
  "automation": {
    "id": "cmh2k9q0a0007l50g1b2c3d4e",
    "name": "Free guide",
    "isActive": true
  },
  "days": 30,
  "triggered": 146,
  "sent": 122,
  "failed": 5,
  "skipped": 19,
  "clicks": 44,
  "ctr": 36.1,
  "keywords": [
    {
      "keyword": "guide",
      "count": 122
    }
  ]
}
triggeredinteger
Comments (or DMs) that matched.
skippedinteger
Matched but not sent: already DMed, over a limit, or not a match on a closer look.
ctrnumber
Link taps per DM sent, as a percentage.

Knowledge base

GET/api/v1/accounts/:id/knowledge

What the account's AI agents answer from, with how full it is. Needs a plan with AI (Creator or Studio).

POST/api/v1/accounts/:id/knowledge

Add one of: a Q&A ({ kind: "QA", question, answer }), some text ({ kind: "TEXT", title, text }), web pages ({ kind: "URL", urls }), or the account's last 50 captions ({ kind: "INSTAGRAM" }). Answers 202: pages and captions are read in the background, so list the sources to see when they're ready.

Outreach

For people you message first. Instagram doesn't let apps send someone the first DM, so you enroll their handles here, then message each of them from the Instagram app. CueDM recognises that first message, and when they answer, the agent you named replies (auto) or drafts a reply for you to send (draft, the default). The prospect.opener_sent and prospect.replied events follow each one.

POST/api/v1/accounts/:id/prospects

Up to 500 at a time: { prospects: [{ username, context?, externalId? }], agentId?, mode? }. context is what the agent should know about them; externalId is your own id, sent back in events. A handle already enrolled is left as it is, so a list can be sent again safely. Without agentId, the account's DM agent answers.

cURL
curl -X POST https://cuedm.com/api/v1/accounts/ACCOUNT_ID/prospects \
  -H "Authorization: Bearer $CUEDM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode":"draft","prospects":[{"username":"maya.fits","context":"Runs a running club in Leeds","externalId":"row-42"}]}'
GET/api/v1/accounts/:id/prospects

Most recently changed first, with totals: enrolled (not yet messaged), opened, replied and closed. Filter with status or search; page with cursor.

POST/api/v1/accounts/:id/prospects/remove

{ usernames }. Anyone not yet messaged is deleted; anyone already messaged is closed, and their replies go back to the account's usual DM handling.

Retrying safely

POST and PATCH requests take an Idempotency-Key header, any unique string up to 255 characters. If the same key comes again within 24 hours, CueDM answers with the first response, marked Idempotent-Replayed: true, instead of doing it twice. The same key with a different body is a 400, and a repeat while the first is still running is a 409. A request that failed can be retried with the same key.

List webhooks

GET/api/v1/hooks

Every webhook in the workspace, oldest first. This includes webhooks added in Settings. Signing secrets are never returned here.

cURL
curl https://cuedm.com/api/v1/hooks \
  -H "Authorization: Bearer $CUEDM_API_KEY"
Response
[
  {
    "id": "cmg51b2c90003l50g6q0v1d3z",
    "url": "https://example.com/webhooks/cuedm",
    "events": [
      "dm.sent",
      "contact.email_captured"
    ],
    "enabled": true,
    "description": "example.com",
    "createdAt": "2026-09-29T10:00:00.000Z"
  }
]

Create a webhook

POST/api/v1/hooks

Subscribes a URL to one or more events. The webhook appears in Settings like any other and is signed the same way. This is the REST hook “subscribe” call that Zapier and Make use.

Body

urlstringrequired
A public https:// URL, up to 2,048 characters.
eventsstring[]
The events to send. Send events, event or both; at least one is required.
eventstring
One event, for callers that subscribe to a single event.
descriptionstring
A label for Settings, up to 120 characters. Defaults to “Zapier”, “Make” or the URL's host.

Events: dm.sent, dm.failed, link.clicked, contact.created, contact.email_captured, bio.subscribed, bio.unsubscribed, message.received, conversation.needs_reply, ai.draft_created, comment.received, post.published, post.failed, broadcast.finished, prospect.opener_sent, prospect.replied, prospect.window_closing, campaign.goal_reached.

curl https://cuedm.com/api/v1/hooks \
  -H "Authorization: Bearer $CUEDM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/webhooks/cuedm", "events": ["dm.sent", "contact.email_captured"]}'

Answers 201 Created with the webhook and its signing secret. This is the only time the secret is returned, so store it now.

201 Created
{
  "id": "cmg51b2c90003l50g6q0v1d3z",
  "url": "https://example.com/webhooks/cuedm",
  "events": [
    "dm.sent",
    "contact.email_captured"
  ],
  "enabled": true,
  "description": "example.com",
  "createdAt": "2026-09-29T10:00:00.000Z",
  "secret": "whsec_…"
}

A 400 means the URL or events were missing or invalid; the message lists the valid event names. It's also returned when the workspace already has 10 webhooks.

Delete a webhook

DELETE/api/v1/hooks/:id

Removes the webhook and stops its deliveries, including any retries still waiting. It answers 200 even if the webhook was already gone, so an unsubscribe can safely run twice.

cURL
curl -X DELETE https://cuedm.com/api/v1/hooks/cmg51b2c90003l50g6q0v1d3z \
  -H "Authorization: Bearer $CUEDM_API_KEY"
Response
{
  "id": "cmg51b2c90003l50g6q0v1d3z",
  "deleted": true
}

Sample payloads

GET/api/v1/events/:event/sample

The last three payloads this workspace sent for an event, newest first, in the same shape a webhook receives. If the event has never fired, you get one example payload instead, so you can still map fields in a Zap or scenario. An unknown event answers 404.

cURL
curl https://cuedm.com/api/v1/events/contact.email_captured/sample \
  -H "Authorization: Bearer $CUEDM_API_KEY"
Response
[
  {
    "id": "sample_contact_email_captured",
    "event": "contact.email_captured",
    "workspaceId": "cmfz8o3gq0000l50gk3ah2d9e",
    "occurredAt": "2026-09-21T10:02:00.000Z",
    "data": {
      "contact": {
        "id": "contact_sample",
        "igUserId": "1234567890",
        "username": "maya.fits",
        "email": "maya@example.com",
        "accountId": "acct_sample",
        "automationId": "auto_sample"
      }
    }
  }
]

Stuck, or something here is wrong? Email support@cuedm.com and a person will answer.