API resource

Comment-to-DM automations

When someone comments a keyword on your Instagram or Facebook post, Creator OS sends them a DM automatically, and optionally replies publicly. Runs on our servers; nothing needs to stay online on your side.

Create an automation

POST/v1/automations

Works on: Instagram, Facebook

Bind to one post with platformPostId (the network’s id from Retrieve a post), or leave it out to cover every post on the account.

Body

namestringrequired

Label for your own reference.

accountIdstringrequired

The account (acc_...) the post or conversation belongs to.

platformPostIdstring

The network’s post id. Omit for account-wide.

keywordsstring[]

Trigger words. Empty means any comment triggers.

matchModestring

contains (default), word or exact.

dmMessagestringrequired

The DM each commenter receives.

commentReplystring

Optional public reply under the trigger comment.

buttonsobject[]

Up to 3 DM buttons: { type: "url", title, url }, { type: "postback", title, payload } or (Facebook only) { type: "phone", title, phone }. Titles are 20 characters max; with buttons, dmMessage must be 640 characters or less. Pass [] to clear.

linkTrackingboolean

Count clicks on link buttons (on by default). Clicks show up in stats.

clickTagstring

Tag applied to a contact who clicks a tracked link.

dmMessageVariationsstring[]

Alternate DM texts, rotated at random with dmMessage.

commentReplyVariationsstring[]

Alternate public replies, rotated at random with commentReply.

excludeKeywordsstring[]

Comments containing any of these never trigger it.

alsoMatchInDmsboolean

Also fire when someone DMs a keyword directly.

dmDelaySecondsinteger

Wait this long before sending the DM. 0 sends immediately.

isActiveboolean

false pauses the automation without deleting it; true resumes it.

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/automations" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Guide funnel",
    "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
    "platformPostId": "18053924711234567",
    "keywords": [
      "GUIDE"
    ],
    "matchMode": "word",
    "dmMessage": "Here’s the guide: https://example.com/guide",
    "commentReply": "Sent it to your DMs!"
  }'

Response 201

{
  "id": "auto_Zp4Kq8Vw1Nx6Ty3Lm9Rc2Hb7Js5Df0Ga8Ue4Ki1Oq6",
  "name": "Guide funnel",
  "platform": "instagram",
  "trigger": "comment",
  "platformPostId": "18053924711234567",
  "keywords": [
    "GUIDE"
  ],
  "matchMode": "word",
  "dmMessage": "Here’s the guide: https://example.com/guide",
  "commentReply": "Sent it to your DMs!",
  "isActive": true
}

List automations

GET/v1/automations

Works on: Instagram, Facebook

Every automation in the workspace.

curl "https://creatoros-production-5658.up.railway.app/v1/automations" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "success": true,
  "automations": [
    {
      "id": "auto_Zp4Kq8Vw1Nx6Ty3Lm9Rc2Hb7Js5Df0Ga8Ue4Ki1Oq6",
      "name": "Guide funnel",
      "platform": "instagram",
      "trigger": "comment",
      "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
      "platformPostId": "18053924711234567",
      "keywords": [
        "GUIDE"
      ],
      "matchMode": "word",
      "dmMessage": "Here’s the guide: https://example.com/guide",
      "isActive": true
    }
  ]
}

Update an automation

PATCH/v1/automations/{automationId}

Works on: Instagram, Facebook

Change the message, keywords, buttons or reply, or pause it with isActive: false (send true to resume). Send only the fields that change. GET the same path to retrieve one automation, including its stats (triggered, DMs sent and failed, clicks).

Path parameters

automationIdstringrequired

The auto_ id.

Body

dmMessagestring

New DM text.

keywordsstring[]

New trigger words.

matchModestring

contains, word or exact.

commentReplystring

New public reply.

buttonsobject[]

linkTrackingboolean

Count clicks on link buttons (on by default). Clicks show up in stats.

clickTagstring

Tag applied to a contact who clicks a tracked link.

dmMessageVariationsstring[]

Alternate DM texts, rotated at random with dmMessage.

commentReplyVariationsstring[]

Alternate public replies, rotated at random with commentReply.

excludeKeywordsstring[]

Comments containing any of these never trigger it.

alsoMatchInDmsboolean

Also fire when someone DMs a keyword directly.

dmDelaySecondsinteger

Wait this long before sending the DM. 0 sends immediately.

isActiveboolean

false pauses the automation without deleting it; true resumes it.

curl -X PATCH "https://creatoros-production-5658.up.railway.app/v1/automations/auto_Zp4Kq8Vw1Nx6Ty3Lm9Rc2Hb7Js5Df0Ga8Ue4Ki1Oq6" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "isActive": false
  }'

Response 200

{
  "id": "auto_Zp4Kq8Vw1Nx6Ty3Lm9Rc2Hb7Js5Df0Ga8Ue4Ki1Oq6",
  "name": "Guide funnel",
  "keywords": [
    "GUIDE"
  ],
  "isActive": false
}

List automation runs

GET/v1/automations/{automationId}/logs

Works on: Instagram, Facebook

Every comment that triggered the automation, newest first, with what happened to the DM and the public reply. misses counts recent comments that reached the automation but matched no keyword, which is the quickest way to spot a keyword that’s too strict.

Path parameters

automationIdstringrequired

The auto_ id.

Query parameters

statusstring

pending, sent, failed, skipped or gated.

limitinteger

Page size.

skipinteger

Rows to skip, for paging.

curl "https://creatoros-production-5658.up.railway.app/v1/automations/auto_Zp4Kq8Vw1Nx6Ty3Lm9Rc2Hb7Js5Df0Ga8Ue4Ki1Oq6/logs?status=failed&limit=20" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "success": true,
  "logs": [
    {
      "id": "obj_Rv2Kc8Qm4Tz1Wx7Ny3Lb9Hs5Jd0Pf6Ga2Ue8Ki4Oq1",
      "commentId": "cmt_Lr5Tz8Qk2Wx7Ny4Bv1Hm9Jc6Pd3Fs0Ga8Ue5Ki2Oq7X",
      "commenterName": "Maya",
      "commentText": "GUIDE please!",
      "source": "comment",
      "status": "failed",
      "error": "The user has not messaged this account in the last 7 days.",
      "commentReplyStatus": "skipped",
      "createdAt": "2026-09-25T19:03:12.000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 20,
    "skip": 0,
    "hasMore": false
  },
  "misses": {
    "total": 3,
    "retentionDays": 7,
    "samples": [
      {
        "commentText": "guide?",
        "commenterName": "Leo"
      }
    ]
  }
}

Delete an automation

DELETE/v1/automations/{automationId}

Works on: Instagram, Facebook

Stops the automation. DMs already sent are unaffected.

Path parameters

automationIdstringrequired

The auto_ id.

curl -X DELETE "https://creatoros-production-5658.up.railway.app/v1/automations/auto_Zp4Kq8Vw1Nx6Ty3Lm9Rc2Hb7Js5Df0Ga8Ue4Ki1Oq6" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "success": true
}

PreviousValidation NextSkool communities