API resource

Accounts, groups and post review

One connected account in full, whether an Instagram user follows you, the account's webhook subscription with Meta (re-subscribe when lead ads stop arriving), account groups to post to a set of accounts at once, and approving, rejecting, pinning or unpinning posts.

Check whether an Instagram user follows the account

GET/v1/accounts/{accountId}/follow-status/{userId}

Works on: Every network

Resolves the follow relationship between an Instagram user and the connected account, plus their public profile counters. userId is the Instagram-scoped id (IGSID) Meta gives you on a webhook: sender.id on message.received, comment.author.id on comment.received. ### When it cannot be resolved Meta only answers for people who have MESSAGED the account. Commenting grants no consent, so a commenter who has never DMed you is unresolvable. That is a platform rule, not a limitation of this endpoint.

Path parameters

accountIdstringrequired

Instagram account ID

userIdstringrequired

Instagram-scoped user id (IGSID) from a webhook payload

Query parameters

refreshboolean

Bypass the cache and re-query Meta

curl "https://creatoros-production-5658.up.railway.app/v1/accounts/acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r/follow-status/6543210987654321" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
  "isFollower": true,
  "isFollowedByAccount": true,
  "followerCount": 0,
  "isVerified": true,
  "username": "string",
  "name": "string",
  "unavailableReason": "consent_required"
}

Read an account's webhook subscription

GET/v1/accounts/{accountId}/webhook-subscription

Works on: Every network

Returns the webhook fields Creator OS's app is subscribed to on the connected Page, read live from Meta. Use it to confirm leadgen is present: a Page missing it keeps delivering every other event while lead ads stop arriving, with nothing to indicate it. For an Instagram account connected through Instagram Login it returns the subscription record (subscriptionId) and the webhook fields Meta did not subscribe (missingFields). An Instagram account connected through Facebook Login returns 409: its webhooks ride the Facebook Page subscription.

Path parameters

accountIdstringrequired

curl "https://creatoros-production-5658.up.railway.app/v1/accounts/acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r/webhook-subscription" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "pageId": "112233445566",
  "appSubscribed": true,
  "leadgen": true,
  "subscribedFields": [
    "string"
  ],
  "warning": "string",
  "instagramUserId": "string",
  "subscriptionId": "string",
  "missingFields": [
    "string"
  ]
}

Re-subscribe an account to Creator OS's webhooks

POST/v1/accounts/{accountId}/webhook-subscription

Works on: Every network

Re-sends the full field set to Meta and returns the subscription read back afterwards. Meta only honours the field set sent at subscribe time, so a Page connected before a field existed stays without it until this runs. The response reflects what Meta actually granted, not what was requested. For an Instagram account connected through Instagram Login, Meta can keep listing a subscription while delivering nothing, and re-sending the fields over it changes nothing. So this call deletes the subscription and creates it again, and recreated is true when the record id moved.

Path parameters

accountIdstringrequired

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/accounts/acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r/webhook-subscription" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "resubscribed": true,
  "pageId": "112233445566",
  "appSubscribed": true,
  "leadgen": true,
  "subscribedFields": [
    "string"
  ],
  "warning": "string",
  "instagramUserId": "string",
  "subscriptionId": "string",
  "previousSubscriptionId": "string",
  "recreated": true,
  "missingFields": [
    "string"
  ]
}

Get account

GET/v1/accounts/{accountId}

Works on: Every network

Returns one connected account, in the same shape as an item of GET /v1/accounts. The same access rules apply: a key or a team member limited to some profiles gets a 404 for an account outside them. An account the list leaves out by default is still returned when you name it: - one over the plan's profile limit - one on a creator profile - an ad account listed behind its ads login A malformed accountId returns 400; an unknown account, or one you cannot access, returns 404.

Path parameters

accountIdstringrequired

curl "https://creatoros-production-5658.up.railway.app/v1/accounts/acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "account": {
    "id": "string",
    "platform": "social",
    "username": "string",
    "displayName": "string",
    "capabilities": {
      "sync": {
        "mode": "push",
        "typicalDelaySeconds": 0
      },
      "sentItems": {
        "mode": "push",
        "typicalDelaySeconds": 0
      },
      "drafts": {
        "supported": true,
        "clientEditsVisible": true,
        "versioned": true
      },
      "forward": {
        "native": true,
        "asAttachment": true
      },
      "sendAs": {
        "list": "provider",
        "sharedMailboxes": true
      },
      "signatures": {
        "provider": "read"
      },
      "labels": {
        "model": "labels"
      },
      "bounces": {
        "detection": true
      },
      "scheduledSend": {
        "holdAsDraft": true
      },
      "tracking": true
    },
    "platformUserId": "string",
    "scopeAreas": [
      "string"
    ],
    "oauthAppId": "string",
    "tiktokAccountType": "business",
    "profilePicture": "string",
    "profileUrl": "string",
    "isActive": true,
    "needsReconnection": true,
    "followersCount": 0,
    "followersLastUpdated": "2026-10-10T00:00:00.000Z",
    "parentAccountId": "string",
    "enabled": true,
    "metaAdsSyncEnabled": true,
    "rateLimitedUntil": "2026-10-10T00:00:00.000Z",
    "metadata": {},
    "inboundActivity": "string"
  }
}

Update account

PUT/v1/accounts/{accountId}

Works on: Every network

Updates a connected account's display name or username override. ### X capabilities For X accounts on usage-based billing, also accepts an xCapabilities object to toggle background API operations that incur X API pass-through costs. - Both fields are opt-in (default false). - When off, no analytics syncs or DM polling are performed for that account, and no API call is metered for those operations. - Publishing and deleting posts are always available regardless of these toggles. - Setting xCapabilities on a non-X account returns 400.

Path parameters

accountIdstringrequired

Body

usernamestring

displayNamestring

xCapabilitiesobject

X only. Per-account opt-in toggles for background API operations that incur X API pass-through costs. Each call is billed at the X tier rate. Either field can be sent independently; omitted fields are unchanged.

metaAdsSyncEnabledboolean

Facebook only (400 invalid_field_value on any other platform). Off by default for every Facebook account. true makes this account sync the Meta ads of the ad accounts it reaches, like a metaads connection.

curl -X PUT "https://creatoros-production-5658.up.railway.app/v1/accounts/acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "string"
  }'
Response 200
{
  "message": "string",
  "username": "string",
  "displayName": "string",
  "xCapabilities": {
    "analytics": true,
    "inbox": true
  },
  "metaAdsSyncEnabled": true
}

List groups

GET/v1/account-groups

Works on: Every network

Returns all account groups visible to the authenticated user. Groups can contain accounts from multiple profiles. For API keys scoped to specific profiles, only groups whose accounts all live in allowed profiles are returned.
curl "https://creatoros-production-5658.up.railway.app/v1/account-groups" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "groups": [
    {
      "id": "string",
      "name": "string",
      "accountIds": [
        "string"
      ],
      "createdBy": "string"
    }
  ]
}

Create group

POST/v1/account-groups

Works on: Every network

Creates a new account group with a name and a list of account IDs. Accounts can belong to different profiles; the caller must have access to every account's profile. Group names must be unique per user.

Body

namestringrequired

accountIdsstring[]required

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/account-groups" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "accountIds": [
      "string"
    ]
  }'
Response 200
{
  "message": "string",
  "group": {
    "id": "string",
    "name": "string",
    "accountIds": [
      "string"
    ]
  }
}

Update group

PUT/v1/account-groups/{groupId}

Works on: Every network

Updates the name or account list of an existing group. You can rename the group, change its accounts, or both.

Path parameters

groupIdstringrequired

Body

namestring

accountIdsstring[]

curl -X PUT "https://creatoros-production-5658.up.railway.app/v1/account-groups/obj_Gr5Lm9Rc2Hb7Js5Df0Ga8Ue4Ki1Oq6Kq8Vw1Nx6F" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string"
  }'
Response 200
{
  "message": "string",
  "group": {}
}

Delete group

DELETE/v1/account-groups/{groupId}

Works on: Every network

Permanently deletes an account group. The accounts themselves are not affected.

Path parameters

groupIdstringrequired

curl -X DELETE "https://creatoros-production-5658.up.railway.app/v1/account-groups/obj_Gr5Lm9Rc2Hb7Js5Df0Ga8Ue4Ki1Oq6Kq8Vw1Nx6F" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "message": "string"
}

Approve or reject a post

POST/v1/posts/{postId}/review

Works on: Every network

Approves or rejects a post saved with requiresApproval: true (status pending_approval). approve schedules the post for its scheduledFor and fires the post.scheduled webhook. When that time has already passed, the post publishes within a couple of minutes. reject returns the post to draft. Returns 409 when the post is not pending_approval.

Path parameters

postIdstringrequired

Body

decisionstringrequired

approve schedules the post; reject returns it to draft.

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/posts/post_V9cK2mQ7xL4pR8tN1wZ6bH3jF5dS0aG7eU2iO4kY9/review" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "approve"
  }'
Response 200
{
  "post": {
    "id": "string",
    "title": "string",
    "content": "string",
    "contentNotRetained": true,
    "mediaItems": [
      {
        "type": "image",
        "url": "string",
        "fileId": "string",
        "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
        "title": "string",
        "altText": "string",
        "filename": "string",
        "size": 0,
        "mimeType": "string",
        "thumbnail": "string",
        "instagramThumbnail": "string",
        "subtitles": [],
        "tiktokProcessed": true
      }
    ],
    "platforms": [
      {
        "platform": "twitter",
        "accountId": {},
        "customContent": "string",
        "customMedia": [],
        "scheduledFor": "2026-10-10T00:00:00.000Z",
        "platformSpecificData": {},
        "status": "pending",
        "platformPostId": "1234567890123456789",
        "platformPostUrl": "https://twitter.com/acmecorp/status/1234567890123456789",
        "publishedAt": "2026-10-10T00:00:00.000Z",
        "removedFromPlatformAt": "2026-10-10T00:00:00.000Z",
        "isTrialReel": true,
        "trialGraduationStrategy": "MANUAL",
        "publishAttempts": 0,
        "publishRetries": 0,
        "errorMessage": "string",
        "errorCategory": "auth_expired",
        "errorSource": "user",
        "platformError": {}
      }
    ],
    "scheduledFor": "2026-10-10T00:00:00.000Z",
    "timezone": "string",
    "status": "draft",
    "tags": [
      "string"
    ],
    "hashtags": [
      "string"
    ],
    "mentions": [
      "string"
    ],
    "visibility": "public",
    "metadata": {},
    "externalId": "string",
    "recycling": {
      "enabled": true,
      "gap": 0,
      "gapFreq": "week",
      "startDate": "2026-10-10T00:00:00.000Z",
      "expireCount": 0,
      "expireDate": "2026-10-10T00:00:00.000Z",
      "contentVariations": [
        "string"
      ],
      "contentVariationIndex": 0,
      "recycleCount": 0,
      "nextRecycleAt": "2026-10-10T00:00:00.000Z",
      "lastRecycledAt": "2026-10-10T00:00:00.000Z"
    },
    "recycledFromPostId": "string",
    "queuedFromProfile": "string",
    "queueId": "string",
    "createdAt": "2026-10-10T00:00:00.000Z",
    "updatedAt": "2026-10-10T00:00:00.000Z"
  }
}

Pin post

POST/v1/posts/{postId}/pin

Works on: Every network

Pins a published Facebook Page post to the top of its Page. Only Facebook posts can be pinned; any other platform answers 400 platform_not_supported. Works for posts on Pages connected through Facebook Login.

Path parameters

postIdstringrequired

Body

platformstringrequired

Must be facebook. Any other value answers 400 platform_not_supported.

accountIdstring

Which Facebook account's copy to change when the post was published to several Facebook accounts. Required in that case.

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/posts/post_V9cK2mQ7xL4pR8tN1wZ6bH3jF5dS0aG7eU2iO4kY9/pin" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "facebook"
  }'
Response 200
{
  "success": true,
  "pinned": true,
  "platformPostId": "string",
  "message": "string"
}

Unpin post

POST/v1/posts/{postId}/unpin

Works on: Every network

Unpins a published Facebook Page post from the top of its Page. Only Facebook posts can be unpinned; any other platform answers 400 platform_not_supported.

Path parameters

postIdstringrequired

Body

platformstringrequired

Must be facebook. Any other value answers 400 platform_not_supported.

accountIdstring

Which Facebook account's copy to change when the post was published to several Facebook accounts. Required in that case.

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/posts/post_V9cK2mQ7xL4pR8tN1wZ6bH3jF5dS0aG7eU2iO4kY9/unpin" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "facebook"
  }'
Response 200
{
  "success": true,
  "pinned": true,
  "platformPostId": "string",
  "message": "string"
}