Developers

API reference

Every endpoint in the Distinctful REST API with its parameters, fields, and responses, and a request you can copy in cURL, JavaScript, or Python.

Base URL
https://app.distinctful.com/api/v1
Send on every request
Authorization: Bearer $DISTINCTFUL_API_KEY

Scale plan. Authenticate with Authorization: Bearer <key> from Settings → Integrations → API keys. A key acts as its creator with their role: an Editor's key schedules only approved, unchanged drafts. Limits per person, each a minute: 60 reads, 20 writes, 60 media calls, and 10 schedule, publish, or cancel calls. Every response reports its budget in RateLimit headers.

Accounts

The social accounts a draft can go to, and the groups they post in.

Connected social accounts

GET/accounts

Responses

  • 200Accounts a draft can go to.
    ›Response fields
    • dataobjectrequired
      ›3 fields
      • accountsAccount[]required
        ›7 fields
        • accountIduuidrequired

          Pass in accountIds to schedule or publish.

        • platformstringrequired
          • THREADS
          • LINKEDIN
          • TWITTER
          • INSTAGRAM
          • YOUTUBE
          • TIKTOK
          • BLUESKY
          • FACEBOOK
          • PINTEREST
          • MASTODON
          • DISCORD
        • displayNamestringrequired
        • connectionStatusstringrequired
          • CONNECTED
          • ERROR
        • publishingStatusstringrequired
          • AVAILABLE
          • TEMPORARILY_UNAVAILABLE
          • ACTION_REQUIRED
        • requiredActionstringrequired
          • NONE
          • RECONNECT
          • SELECT_ACCOUNT
          • UPDATE_PERMISSIONS
          • WAIT
          • CONTACT_SUPPORT
        • groupIduuid | nullrequired

          The group this account is in, from groups.

      • groupsAccountGroup[]required

        Sets of accounts the team posts to together.

        ›3 fields
        • groupIduuidrequired
        • namestringrequired
        • notestring | nullrequired

          Who the group speaks to and how it sounds.

      • truncatedbooleanrequired
  • 400The body, query, or path did not validate.
  • 401Missing, mistyped, or revoked key.
  • 403Not on Scale, or the key's role cannot do this.
  • 429Over a limit. Wait Retry-After seconds.
  • 503Plan status or storage could not be reached; nothing ran. Wait Retry-After seconds.
curl https://app.distinctful.com/api/v1/accounts \
  -H "Authorization: Bearer $DISTINCTFUL_API_KEY"
Response200
{
  "data": {
    "accounts": [
      {
        "accountId": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
        "platform": "LINKEDIN",
        "displayName": "Distinctful",
        "connectionStatus": "CONNECTED",
        "publishingStatus": "AVAILABLE",
        "requiredAction": "NONE",
        "groupId": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10"
      }
    ],
    "groups": [
      {
        "groupId": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
        "name": "string",
        "note": "Lead with the client quote."
      }
    ],
    "truncated": true
  }
}

Drafts

Create, read, edit, and delete drafts. A planned date never publishes on its own.

Drafts, most recently changed first

GET/drafts

Query parameters

  • cursorstring

Responses

  • 200A page of 50 drafts.
    ›Response fields
    • dataobjectrequired
      ›2 fields
      • dataDraft[]required
        ›13 fields
        • iduuidrequired
        • titlestringrequired
        • typestringrequired
          • TIKTOK
          • REEL
          • THREAD
          • NEWSLETTER
          • YOUTUBE_VIDEO
          • YOUTUBE_SHORT
          • ARTICLE
          • PODCAST
          • POST
        • statusstringrequired

          Where the draft sits on the board.

          • NEXT_UP
          • IN_PROGRESS
          • REVIEW
          • SHIPPED
          • ARCHIVED
        • scheduledDatedate-time | nullrequired

          The planned date; it never publishes on its own.

        • destinationPlatformsstring[]required
        • updatedAtdate-timerequired
        • versioninteger

          Counts edits to the draft. Send it back as expectedVersion so your edit never replaces a newer one. Returned by single-draft reads.

        • reviewstring | nullrequired

          The latest review round; EDITED_SINCE_REVIEW once the draft changed after it, so its approval no longer covers it. Null before any review.

          • IN_REVIEW
          • APPROVED
          • CHANGES_REQUESTED
          • EDITED_SINCE_REVIEW
        • contentstring

          The text that schedule and publish send. Returned by single-draft reads.

        • threadPostsobject[] | null

          A thread’s posts in order, with the ids media and edits refer to; null for a single post. Returned by single-draft reads.

          ›4 fields
          • idstringrequired
          • positionintegerrequired
          • bodystringrequired
          • mediaIdsstring[]required
        • mediaMedia[]

          Attached media in carousel order. Returned by single-draft reads.

          ›8 fields
          • iduuidrequired
          • typestringrequired
            • image
            • video
          • urlstringrequired
          • altTextstring | nullrequired
          • threadPostIdstring | nullrequired

            On a thread, the post it belongs to.

          • widthinteger | nullrequired
          • heightinteger | nullrequired
          • durationMsinteger | nullrequired
        • postsDraftPost[]

          Posts scheduled or sent from this draft, newest first. Returned by single-draft reads.

          ›7 fields
          • iduuidrequired

            The post id: cancel it with /posts/{id}/cancel, and match it to postId in events.

          • accountIduuidrequired
          • platformstringrequired

            The platform, such as LINKEDIN.

          • statusstringrequired
            • PENDING
            • SCHEDULED
            • PUBLISHING
            • RETRYING
            • PUBLISHED
            • FAILED
            • CANCELLED
          • scheduledFordate-time | nullrequired
          • publishedAtdate-time | nullrequired
          • urlstring | nullrequired

            The live post, once published.

      • nextCursorstring | nullrequired

        Pass as cursor for the next page; null on the last page.

  • 400The body, query, or path did not validate.
  • 401Missing, mistyped, or revoked key.
  • 403Not on Scale, or the key's role cannot do this.
  • 429Over a limit. Wait Retry-After seconds.
  • 503Plan status or storage could not be reached; nothing ran. Wait Retry-After seconds.
curl https://app.distinctful.com/api/v1/drafts \
  -H "Authorization: Bearer $DISTINCTFUL_API_KEY"
Response200
{
  "data": {
    "data": [
      {
        "id": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
        "title": "Launch post",
        "type": "POST",
        "status": "NEXT_UP",
        "scheduledDate": "2026-11-16T15:00:00.000Z",
        "destinationPlatforms": [
          "LINKEDIN"
        ],
        "updatedAt": "2026-11-16T15:00:00.000Z",
        "version": 3,
        "review": "IN_REVIEW",
        "content": "We just shipped client approvals that never need an account.",
        "threadPosts": [
          {
            "id": "string",
            "position": 0,
            "body": "We just shipped client approvals that never need an account.",
            "mediaIds": []
          }
        ],
        "media": [
          {
            "id": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
            "type": "image",
            "url": "https://example.com",
            "altText": "The new approvals screen",
            "threadPostId": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
            "width": 1080,
            "height": 1350,
            "durationMs": 0
          }
        ],
        "posts": [
          {
            "id": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
            "accountId": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
            "platform": "LINKEDIN",
            "status": "PENDING",
            "scheduledFor": "2026-11-16T15:00:00.000Z",
            "publishedAt": "2026-11-16T15:00:00.000Z",
            "url": "https://example.com"
          }
        ]
      }
    ],
    "nextCursor": "string"
  }
}

Create a draft; a planned date never publishes

POST/drafts

Headers

  • Idempotency-Keystring

    A retry with the same key returns the first result instead of creating a second one.

Body

  • titlestringrequired
  • typestringrequired
    • POST
    • THREAD
  • contentstring
  • threadPostsobject[]
    ›4 fields
    • idstringrequired
    • positionintegerrequired
    • bodystringrequired
    • mediaIdsstring[]
  • scheduledDatedate-time
  • destinationPlatformsstring[]
    • THREADS
    • TWITTER
    • LINKEDIN
    • BLUESKY
    • INSTAGRAM
    • TIKTOK
    • YOUTUBE
    • FACEBOOK
    • PINTEREST
    • MASTODON
    • DISCORD

Responses

  • 201The new draft.
    ›Response fields
    • dataDraftrequired
      ›13 fields
      • iduuidrequired
      • titlestringrequired
      • typestringrequired
        • TIKTOK
        • REEL
        • THREAD
        • NEWSLETTER
        • YOUTUBE_VIDEO
        • YOUTUBE_SHORT
        • ARTICLE
        • PODCAST
        • POST
      • statusstringrequired

        Where the draft sits on the board.

        • NEXT_UP
        • IN_PROGRESS
        • REVIEW
        • SHIPPED
        • ARCHIVED
      • scheduledDatedate-time | nullrequired

        The planned date; it never publishes on its own.

      • destinationPlatformsstring[]required
      • updatedAtdate-timerequired
      • versioninteger

        Counts edits to the draft. Send it back as expectedVersion so your edit never replaces a newer one. Returned by single-draft reads.

      • reviewstring | nullrequired

        The latest review round; EDITED_SINCE_REVIEW once the draft changed after it, so its approval no longer covers it. Null before any review.

        • IN_REVIEW
        • APPROVED
        • CHANGES_REQUESTED
        • EDITED_SINCE_REVIEW
      • contentstring

        The text that schedule and publish send. Returned by single-draft reads.

      • threadPostsobject[] | null

        A thread’s posts in order, with the ids media and edits refer to; null for a single post. Returned by single-draft reads.

        ›4 fields
        • idstringrequired
        • positionintegerrequired
        • bodystringrequired
        • mediaIdsstring[]required
      • mediaMedia[]

        Attached media in carousel order. Returned by single-draft reads.

        ›8 fields
        • iduuidrequired
        • typestringrequired
          • image
          • video
        • urlstringrequired
        • altTextstring | nullrequired
        • threadPostIdstring | nullrequired

          On a thread, the post it belongs to.

        • widthinteger | nullrequired
        • heightinteger | nullrequired
        • durationMsinteger | nullrequired
      • postsDraftPost[]

        Posts scheduled or sent from this draft, newest first. Returned by single-draft reads.

        ›7 fields
        • iduuidrequired

          The post id: cancel it with /posts/{id}/cancel, and match it to postId in events.

        • accountIduuidrequired
        • platformstringrequired

          The platform, such as LINKEDIN.

        • statusstringrequired
          • PENDING
          • SCHEDULED
          • PUBLISHING
          • RETRYING
          • PUBLISHED
          • FAILED
          • CANCELLED
        • scheduledFordate-time | nullrequired
        • publishedAtdate-time | nullrequired
        • urlstring | nullrequired

          The live post, once published.

  • 400The body, query, or path did not validate.
  • 401Missing, mistyped, or revoked key.
  • 403Not on Scale, or the key's role cannot do this.
  • 409Idempotency-Key reused for a different request, or still running.
  • 413The body is larger than 1 MB.
  • 429Over a limit. Wait Retry-After seconds.
  • 503Plan status or storage could not be reached; nothing ran. Wait Retry-After seconds.
curl -X POST https://app.distinctful.com/api/v1/drafts \
  -H "Authorization: Bearer $DISTINCTFUL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Launch post",
    "type": "POST",
    "content": "We just shipped client approvals that never need an account.",
    "destinationPlatforms": [
      "LINKEDIN",
      "THREADS"
    ]
  }'
Response201
{
  "data": {
    "id": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
    "title": "Launch post",
    "type": "POST",
    "status": "NEXT_UP",
    "scheduledDate": "2026-11-16T15:00:00.000Z",
    "destinationPlatforms": [
      "LINKEDIN"
    ],
    "updatedAt": "2026-11-16T15:00:00.000Z",
    "version": 3,
    "review": "IN_REVIEW",
    "content": "We just shipped client approvals that never need an account.",
    "threadPosts": [
      {
        "id": "string",
        "position": 0,
        "body": "We just shipped client approvals that never need an account.",
        "mediaIds": [
          "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10"
        ]
      }
    ],
    "media": [
      {
        "id": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
        "type": "image",
        "url": "https://example.com",
        "altText": "The new approvals screen",
        "threadPostId": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
        "width": 1080,
        "height": 1350,
        "durationMs": 0
      }
    ],
    "posts": [
      {
        "id": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
        "accountId": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
        "platform": "LINKEDIN",
        "status": "PENDING",
        "scheduledFor": "2026-11-16T15:00:00.000Z",
        "publishedAt": "2026-11-16T15:00:00.000Z",
        "url": "https://example.com"
      }
    ]
  }
}

A draft with its text, media, posts, and review status

GET/drafts/{id}

Path parameters

  • iduuidrequired

Responses

  • 200The draft.
    ›Response fields
    • dataDraftrequired
      ›13 fields
      • iduuidrequired
      • titlestringrequired
      • typestringrequired
        • TIKTOK
        • REEL
        • THREAD
        • NEWSLETTER
        • YOUTUBE_VIDEO
        • YOUTUBE_SHORT
        • ARTICLE
        • PODCAST
        • POST
      • statusstringrequired

        Where the draft sits on the board.

        • NEXT_UP
        • IN_PROGRESS
        • REVIEW
        • SHIPPED
        • ARCHIVED
      • scheduledDatedate-time | nullrequired

        The planned date; it never publishes on its own.

      • destinationPlatformsstring[]required
      • updatedAtdate-timerequired
      • versioninteger

        Counts edits to the draft. Send it back as expectedVersion so your edit never replaces a newer one. Returned by single-draft reads.

      • reviewstring | nullrequired

        The latest review round; EDITED_SINCE_REVIEW once the draft changed after it, so its approval no longer covers it. Null before any review.

        • IN_REVIEW
        • APPROVED
        • CHANGES_REQUESTED
        • EDITED_SINCE_REVIEW
      • contentstring

        The text that schedule and publish send. Returned by single-draft reads.

      • threadPostsobject[] | null

        A thread’s posts in order, with the ids media and edits refer to; null for a single post. Returned by single-draft reads.

        ›4 fields
        • idstringrequired
        • positionintegerrequired
        • bodystringrequired
        • mediaIdsstring[]required
      • mediaMedia[]

        Attached media in carousel order. Returned by single-draft reads.

        ›8 fields
        • iduuidrequired
        • typestringrequired
          • image
          • video
        • urlstringrequired
        • altTextstring | nullrequired
        • threadPostIdstring | nullrequired

          On a thread, the post it belongs to.

        • widthinteger | nullrequired
        • heightinteger | nullrequired
        • durationMsinteger | nullrequired
      • postsDraftPost[]

        Posts scheduled or sent from this draft, newest first. Returned by single-draft reads.

        ›7 fields
        • iduuidrequired

          The post id: cancel it with /posts/{id}/cancel, and match it to postId in events.

        • accountIduuidrequired
        • platformstringrequired

          The platform, such as LINKEDIN.

        • statusstringrequired
          • PENDING
          • SCHEDULED
          • PUBLISHING
          • RETRYING
          • PUBLISHED
          • FAILED
          • CANCELLED
        • scheduledFordate-time | nullrequired
        • publishedAtdate-time | nullrequired
        • urlstring | nullrequired

          The live post, once published.

  • 400The body, query, or path did not validate.
  • 401Missing, mistyped, or revoked key.
  • 403Not on Scale, or the key's role cannot do this.
  • 404Nothing with that id in this Distinctful.
  • 429Over a limit. Wait Retry-After seconds.
  • 503Plan status or storage could not be reached; nothing ran. Wait Retry-After seconds.
curl https://app.distinctful.com/api/v1/drafts/$DRAFT_ID \
  -H "Authorization: Bearer $DISTINCTFUL_API_KEY"
Response200
{
  "data": {
    "id": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
    "title": "Launch post",
    "type": "POST",
    "status": "NEXT_UP",
    "scheduledDate": "2026-11-16T15:00:00.000Z",
    "destinationPlatforms": [
      "LINKEDIN"
    ],
    "updatedAt": "2026-11-16T15:00:00.000Z",
    "version": 3,
    "review": "IN_REVIEW",
    "content": "We just shipped client approvals that never need an account.",
    "threadPosts": [
      {
        "id": "string",
        "position": 0,
        "body": "We just shipped client approvals that never need an account.",
        "mediaIds": [
          "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10"
        ]
      }
    ],
    "media": [
      {
        "id": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
        "type": "image",
        "url": "https://example.com",
        "altText": "The new approvals screen",
        "threadPostId": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
        "width": 1080,
        "height": 1350,
        "durationMs": 0
      }
    ],
    "posts": [
      {
        "id": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
        "accountId": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
        "platform": "LINKEDIN",
        "status": "PENDING",
        "scheduledFor": "2026-11-16T15:00:00.000Z",
        "publishedAt": "2026-11-16T15:00:00.000Z",
        "url": "https://example.com"
      }
    ]
  }
}

Change a draft’s title, content, thread posts, or destinations

PATCH/drafts/{id}

Send only the fields to change. On a THREAD draft the text lives in threadPosts: read them from GET /drafts/{id}, change what you need, and send the whole list back with each id kept; thread posts you leave out lose their media. Any edit after approval leaves the draft EDITED_SINCE_REVIEW. Send expectedVersion, the version you read, to be refused with 409 (details.code stale_version) when someone changed the draft since; without it the edit applies to whatever is saved.

Path parameters

  • iduuidrequired

Body

  • titlestring
  • contentstring
  • threadPostsobject[]
    ›4 fields
    • idstringrequired
    • positionintegerrequired
    • bodystringrequired
    • mediaIdsstring[]
  • destinationPlatformsstring[]
    • THREADS
    • TWITTER
    • LINKEDIN
    • BLUESKY
    • INSTAGRAM
    • TIKTOK
    • YOUTUBE
    • FACEBOOK
    • PINTEREST
    • MASTODON
    • DISCORD
  • expectedVersioninteger

    The version you read. The edit is refused with 409 when the draft has changed since, so a newer edit is never replaced.

Responses

  • 200The draft as saved.
    ›Response fields
    • dataDraftrequired
      ›13 fields
      • iduuidrequired
      • titlestringrequired
      • typestringrequired
        • TIKTOK
        • REEL
        • THREAD
        • NEWSLETTER
        • YOUTUBE_VIDEO
        • YOUTUBE_SHORT
        • ARTICLE
        • PODCAST
        • POST
      • statusstringrequired

        Where the draft sits on the board.

        • NEXT_UP
        • IN_PROGRESS
        • REVIEW
        • SHIPPED
        • ARCHIVED
      • scheduledDatedate-time | nullrequired

        The planned date; it never publishes on its own.

      • destinationPlatformsstring[]required
      • updatedAtdate-timerequired
      • versioninteger

        Counts edits to the draft. Send it back as expectedVersion so your edit never replaces a newer one. Returned by single-draft reads.

      • reviewstring | nullrequired

        The latest review round; EDITED_SINCE_REVIEW once the draft changed after it, so its approval no longer covers it. Null before any review.

        • IN_REVIEW
        • APPROVED
        • CHANGES_REQUESTED
        • EDITED_SINCE_REVIEW
      • contentstring

        The text that schedule and publish send. Returned by single-draft reads.

      • threadPostsobject[] | null

        A thread’s posts in order, with the ids media and edits refer to; null for a single post. Returned by single-draft reads.

        ›4 fields
        • idstringrequired
        • positionintegerrequired
        • bodystringrequired
        • mediaIdsstring[]required
      • mediaMedia[]

        Attached media in carousel order. Returned by single-draft reads.

        ›8 fields
        • iduuidrequired
        • typestringrequired
          • image
          • video
        • urlstringrequired
        • altTextstring | nullrequired
        • threadPostIdstring | nullrequired

          On a thread, the post it belongs to.

        • widthinteger | nullrequired
        • heightinteger | nullrequired
        • durationMsinteger | nullrequired
      • postsDraftPost[]

        Posts scheduled or sent from this draft, newest first. Returned by single-draft reads.

        ›7 fields
        • iduuidrequired

          The post id: cancel it with /posts/{id}/cancel, and match it to postId in events.

        • accountIduuidrequired
        • platformstringrequired

          The platform, such as LINKEDIN.

        • statusstringrequired
          • PENDING
          • SCHEDULED
          • PUBLISHING
          • RETRYING
          • PUBLISHED
          • FAILED
          • CANCELLED
        • scheduledFordate-time | nullrequired
        • publishedAtdate-time | nullrequired
        • urlstring | nullrequired

          The live post, once published.

  • 400The body, query, or path did not validate.
  • 401Missing, mistyped, or revoked key.
  • 403Not on Scale, or the key's role cannot do this.
  • 404Nothing with that id in this Distinctful.
  • 409The draft changed since expectedVersion (details.code stale_version), or an Editor tried to remove media a scheduled post still uses.
  • 413The body is larger than 1 MB.
  • 429Over a limit. Wait Retry-After seconds.
  • 503Plan status or storage could not be reached; nothing ran. Wait Retry-After seconds.
curl -X PATCH https://app.distinctful.com/api/v1/drafts/$DRAFT_ID \
  -H "Authorization: Bearer $DISTINCTFUL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "We just shipped client approvals. No account needed.",
    "expectedVersion": 3
  }'
Response200
{
  "data": {
    "id": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
    "title": "Launch post",
    "type": "POST",
    "status": "NEXT_UP",
    "scheduledDate": "2026-11-16T15:00:00.000Z",
    "destinationPlatforms": [
      "LINKEDIN"
    ],
    "updatedAt": "2026-11-16T15:00:00.000Z",
    "version": 3,
    "review": "IN_REVIEW",
    "content": "We just shipped client approvals that never need an account.",
    "threadPosts": [
      {
        "id": "string",
        "position": 0,
        "body": "We just shipped client approvals that never need an account.",
        "mediaIds": [
          "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10"
        ]
      }
    ],
    "media": [
      {
        "id": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
        "type": "image",
        "url": "https://example.com",
        "altText": "The new approvals screen",
        "threadPostId": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
        "width": 1080,
        "height": 1350,
        "durationMs": 0
      }
    ],
    "posts": [
      {
        "id": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
        "accountId": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
        "platform": "LINKEDIN",
        "status": "PENDING",
        "scheduledFor": "2026-11-16T15:00:00.000Z",
        "publishedAt": "2026-11-16T15:00:00.000Z",
        "url": "https://example.com"
      }
    ]
  }
}

Delete a draft

DELETE/drafts/{id}

Refused with 409 when the draft has a published post (details.code published), is linked to a deal (deal_linked), or has a post still scheduled or retryable. Deleting again succeeds, so a retry is safe.

Path parameters

  • iduuidrequired

Responses

  • 200Deleted.
    ›Response fields
    • dataobjectrequired
      ›2 fields
      • iduuidrequired
      • deletedbooleanrequired
        • true
  • 400The body, query, or path did not validate.
  • 401Missing, mistyped, or revoked key.
  • 403Not on Scale, or the key's role cannot do this.
  • 404Nothing with that id in this Distinctful.
  • 409The draft is published, deal-linked, or has a live post.
  • 429Over a limit. Wait Retry-After seconds.
  • 503Plan status or storage could not be reached; nothing ran. Wait Retry-After seconds.
curl -X DELETE https://app.distinctful.com/api/v1/drafts/$DRAFT_ID \
  -H "Authorization: Bearer $DISTINCTFUL_API_KEY"
Response200
{
  "data": {
    "id": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
    "deleted": true
  }
}

Media

Upload images and video to a draft.

Start an image or video upload

POST/drafts/{id}/media

Images: PUT the file to uploadUrl, then complete. Videos (send sha256): follow uploadMethod, calling start again with the returned uploadId to resume or fetch more parts, until it answers complete; then complete. A draft holds up to 10 files.

Path parameters

  • iduuidrequired

Body

  • fileNamestringrequired

    With its extension, such as launch.png or reel.mp4.

  • mimeTypestringrequired

    One of image/jpeg, image/png, image/gif, image/webp, video/mp4, video/quicktime, video/webm.

  • sizeBytesintegerrequired

    The exact file size in bytes.

  • sha256string

    Lowercase hex SHA-256 of the whole file. Required for video.

  • uploadIduuid

    Video only: the uploadId a previous call returned, to resume or get the next parts.

  • threadPostIdstring

    On a thread, the id of the post the file belongs to.

Responses

  • 201Where to send the bytes.
    ›Response fields
    • dataMediaUploadrequired
      ›13 fields
      • mediaIduuidrequired
      • uploadMethodstringrequired

        PUT the whole file to uploadUrl with these headers.

        • put
        • parts
        • tus
        • complete
      • uploadUrlstring
      • headersmap

        Send these headers exactly.

      • expiresInSecondsinteger
      • uploadIduuid
      • sizeBytesinteger
      • partBytesinteger
      • storedPartNumbersinteger[]
      • partsobject[]
        ›4 fields
        • partNumberintegerrequired
        • offsetBytesintegerrequired
        • sizeBytesintegerrequired
        • urlstringrequired
      • chunkBytesinteger
      • endpointstring
      • uploadMetadatastring
  • 400The body, query, or path did not validate.
  • 401Missing, mistyped, or revoked key.
  • 403Not on Scale, or the key's role cannot do this.
  • 404Nothing with that id in this Distinctful.
  • 409The draft already holds 10 files, or the upload is being changed.
  • 413The body is larger than 1 MB.
  • 429Over a limit. Wait Retry-After seconds.
  • 503Plan status or storage could not be reached; nothing ran. Wait Retry-After seconds.
curl -X POST https://app.distinctful.com/api/v1/drafts/$DRAFT_ID/media \
  -H "Authorization: Bearer $DISTINCTFUL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "launch.png",
    "mimeType": "image/png",
    "sizeBytes": 482113
  }'
Response201
{
  "data": {
    "mediaId": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
    "uploadMethod": "put",
    "uploadUrl": "https://example.com",
    "headers": {},
    "expiresInSeconds": 0
  }
}

Attach an uploaded file to its draft

POST/drafts/{id}/media/{mediaId}/complete

Checks the stored file against what was started. Completing again returns the same media.

Path parameters

  • iduuidrequired
  • mediaIduuidrequired

Body

  • altTextstring
  • widthinteger

    Pixels. Required for video.

  • heightinteger

    Pixels. Required for video.

  • durationMsinteger

    Video only, and required for it.

Responses

  • 200The attached media.
    ›Response fields
    • dataMediarequired
      ›8 fields
      • iduuidrequired
      • typestringrequired
        • image
        • video
      • urlstringrequired
      • altTextstring | nullrequired
      • threadPostIdstring | nullrequired

        On a thread, the post it belongs to.

      • widthinteger | nullrequired
      • heightinteger | nullrequired
      • durationMsinteger | nullrequired
  • 400The body, query, or path did not validate.
  • 401Missing, mistyped, or revoked key.
  • 403Not on Scale, or the key's role cannot do this.
  • 404Nothing with that id in this Distinctful.
  • 409The upload expired or changed; start it again.
  • 413The body is larger than 1 MB.
  • 429Over a limit. Wait Retry-After seconds.
  • 503Plan status or storage could not be reached; nothing ran. Wait Retry-After seconds.
curl -X POST https://app.distinctful.com/api/v1/drafts/$DRAFT_ID/media/$MEDIA_ID/complete \
  -H "Authorization: Bearer $DISTINCTFUL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "altText": "The new approvals screen"
  }'
Response200
{
  "data": {
    "id": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
    "type": "image",
    "url": "https://example.com",
    "altText": "The new approvals screen",
    "threadPostId": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
    "width": 1080,
    "height": 1350,
    "durationMs": 0
  }
}

Remove media from a draft, or cancel a video upload

DELETE/drafts/{id}/media/{mediaId}

Path parameters

  • iduuidrequired
  • mediaIduuidrequired

Responses

  • 200Removed.
    ›Response fields
    • dataobjectrequired
      ›2 fields
      • iduuidrequired
      • deletedbooleanrequired
        • true
  • 400The body, query, or path did not validate.
  • 401Missing, mistyped, or revoked key.
  • 403Not on Scale, or the key's role cannot do this.
  • 404Nothing with that id in this Distinctful.
  • 409A scheduled post still uses it, or an image is still uploading.
  • 429Over a limit. Wait Retry-After seconds.
  • 503Plan status or storage could not be reached; nothing ran. Wait Retry-After seconds.
curl -X DELETE https://app.distinctful.com/api/v1/drafts/$DRAFT_ID/media/$MEDIA_ID \
  -H "Authorization: Bearer $DISTINCTFUL_API_KEY"
Response200
{
  "data": {
    "id": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
    "deleted": true
  }
}

Reviews

Ask for review, decide a round, and share drafts with a client on a link.

The draft’s review: latest round, history, and client link

GET/drafts/{id}/review

Path parameters

  • iduuidrequired

Responses

  • 200The review.
    ›Response fields
    • dataDraftReviewrequired
      ›4 fields
      • requireClientApprovalbooleanrequired

        Every post in this workspace needs the client’s approval.

      • currentReviewRound | nullrequired

        The latest round; null before any review.

        ›10 fields
        • iduuidrequired
        • statusstringrequired
          • PENDING
          • APPROVED
          • CHANGES_REQUESTED
          • SUPERSEDED
        • needsClientbooleanrequired
        • teamApprovedbooleanrequired
        • clientApprovedbooleanrequired
        • changedSinceReviewbooleanrequired

          True once the draft no longer matches what was reviewed.

        • createdAtdate-timerequired
        • snapshotmap | nullrequired

          The draft as it was frozen for review.

        • destinationsobject[]required

          The accounts the approval covers, each with its Facebook link. An Editor schedules only to these.

          ›4 fields
          • accountIduuidrequired
          • platformstringrequired
          • accountstring | nullrequired
          • linkstring | nullrequired
        • eventsobject[]required
          ›5 fields
          • kindstringrequired
            • REQUESTED
            • APPROVED
            • CHANGES_REQUESTED
            • COMMENTED
            • SHARED
            • OVERRIDDEN
            • SCHEDULED
            • REPLIED
            • WITHDRAWN
          • bystring | nullrequired

            The teammate, or the name the client typed on the review link.

          • fromClientbooleanrequired
          • bodystring | nullrequired
          • atdate-timerequired
      • clientLinkobject | nullrequired
        ›5 fields
        • iduuid | nullrequired

          Revoke with /review-links/{id}. Null for Editors.

        • urlstring | nullrequired

          The client’s review page. It never expires; anyone holding it can review until it is revoked. Null for Editors.

        • labelstring | nullrequired
        • sharedAtdate-timerequired
        • showsCurrentbooleanrequired

          False once a later round or an edit leaves the link behind.

      • historyobject[]required

        Recent rounds’ steps, oldest first.

        ›5 fields
        • kindstringrequired
          • REQUESTED
          • APPROVED
          • CHANGES_REQUESTED
          • COMMENTED
          • SHARED
          • OVERRIDDEN
          • SCHEDULED
          • REPLIED
          • WITHDRAWN
        • bystring | nullrequired

          The teammate, or the name the client typed on the review link.

        • fromClientbooleanrequired
        • bodystring | nullrequired
        • atdate-timerequired
  • 400The body, query, or path did not validate.
  • 401Missing, mistyped, or revoked key.
  • 403Not on Scale, or the key's role cannot do this.
  • 404Nothing with that id in this Distinctful.
  • 429Over a limit. Wait Retry-After seconds.
  • 503Plan status or storage could not be reached; nothing ran. Wait Retry-After seconds.
curl https://app.distinctful.com/api/v1/drafts/$DRAFT_ID/review \
  -H "Authorization: Bearer $DISTINCTFUL_API_KEY"
Response200
{
  "data": {
    "requireClientApproval": true,
    "current": {
      "id": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
      "status": "PENDING",
      "needsClient": true,
      "teamApproved": true,
      "clientApproved": true,
      "changedSinceReview": true,
      "createdAt": "2026-11-16T15:00:00.000Z",
      "snapshot": {},
      "destinations": [
        {
          "accountId": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
          "platform": "LINKEDIN",
          "account": "string",
          "link": "string"
        }
      ],
      "events": [
        {
          "kind": "REQUESTED",
          "by": "string",
          "fromClient": true,
          "body": "We just shipped client approvals that never need an account.",
          "at": "2026-11-16T15:00:00.000Z"
        }
      ]
    },
    "clientLink": {
      "id": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
      "url": "https://example.com",
      "label": "Week 46 review",
      "sharedAt": "2026-11-16T15:00:00.000Z",
      "showsCurrent": true
    },
    "history": [
      {
        "kind": "REQUESTED",
        "by": "string",
        "fromClient": true,
        "body": "We just shipped client approvals that never need an account.",
        "at": "2026-11-16T15:00:00.000Z"
      }
    ]
  }
}

Request review: freeze the draft into a new round

POST/drafts/{id}/review

Path parameters

  • iduuidrequired

Responses

  • 201The new review round.
    ›Response fields
    • dataReviewRoundrequired
      ›10 fields
      • iduuidrequired
      • statusstringrequired
        • PENDING
        • APPROVED
        • CHANGES_REQUESTED
        • SUPERSEDED
      • needsClientbooleanrequired
      • teamApprovedbooleanrequired
      • clientApprovedbooleanrequired
      • changedSinceReviewbooleanrequired

        True once the draft no longer matches what was reviewed.

      • createdAtdate-timerequired
      • snapshotmap | nullrequired

        The draft as it was frozen for review.

      • destinationsobject[]required

        The accounts the approval covers, each with its Facebook link. An Editor schedules only to these.

        ›4 fields
        • accountIduuidrequired
        • platformstringrequired
        • accountstring | nullrequired
        • linkstring | nullrequired
      • eventsobject[]required
        ›5 fields
        • kindstringrequired
          • REQUESTED
          • APPROVED
          • CHANGES_REQUESTED
          • COMMENTED
          • SHARED
          • OVERRIDDEN
          • SCHEDULED
          • REPLIED
          • WITHDRAWN
        • bystring | nullrequired

          The teammate, or the name the client typed on the review link.

        • fromClientbooleanrequired
        • bodystring | nullrequired
        • atdate-timerequired
  • 400The body, query, or path did not validate.
  • 401Missing, mistyped, or revoked key.
  • 403Not on Scale, or the key's role cannot do this.
  • 404Nothing with that id in this Distinctful.
  • 409The client is reviewing this version, or an Editor asked before the draft had a platform with one account to post to.
  • 429Over a limit. Wait Retry-After seconds.
  • 503Plan status or storage could not be reached; nothing ran. Wait Retry-After seconds.
curl -X POST https://app.distinctful.com/api/v1/drafts/$DRAFT_ID/review \
  -H "Authorization: Bearer $DISTINCTFUL_API_KEY"
Response201
{
  "data": {
    "id": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
    "status": "PENDING",
    "needsClient": true,
    "teamApproved": true,
    "clientApproved": true,
    "changedSinceReview": true,
    "createdAt": "2026-11-16T15:00:00.000Z",
    "snapshot": {},
    "destinations": [
      {
        "accountId": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
        "platform": "LINKEDIN",
        "account": "string",
        "link": "string"
      }
    ],
    "events": [
      {
        "kind": "REQUESTED",
        "by": "string",
        "fromClient": true,
        "body": "We just shipped client approvals that never need an account.",
        "at": "2026-11-16T15:00:00.000Z"
      }
    ]
  }
}

Approve the open round for the team, or ask for changes (owner or Lead)

POST/drafts/{id}/review/decision

A note is required when asking for changes. Pass reviewId to be sure you decide the round you read.

Path parameters

  • iduuidrequired

Body

  • decisionstringrequired
    • APPROVED
    • CHANGES_REQUESTED
  • notestring
  • reviewIduuid

    The round you are deciding; refused when a newer round has opened.

Responses

  • 200The round’s new status.
    ›Response fields
    • dataReviewDecisionrequired
      ›2 fields
      • reviewIduuidrequired
      • statusstringrequired
        • PENDING
        • APPROVED
        • CHANGES_REQUESTED
        • SUPERSEDED
  • 400The body, query, or path did not validate.
  • 401Missing, mistyped, or revoked key.
  • 403Not on Scale, or the key's role cannot do this.
  • 404Nothing with that id in this Distinctful.
  • 409No round is open, a newer one opened (details.code not_open), or the client is reviewing.
  • 413The body is larger than 1 MB.
  • 429Over a limit. Wait Retry-After seconds.
  • 503Plan status or storage could not be reached; nothing ran. Wait Retry-After seconds.
curl -X POST https://app.distinctful.com/api/v1/drafts/$DRAFT_ID/review/decision \
  -H "Authorization: Bearer $DISTINCTFUL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "CHANGES_REQUESTED",
    "note": "Lead with the client quote.",
    "reviewId": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10"
  }'
Response200
{
  "data": {
    "reviewId": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
    "status": "PENDING"
  }
}

Publishing

Schedule or publish a saved draft, and cancel a scheduled post.

Schedule the saved draft

POST/drafts/{id}/schedule

Path parameters

  • iduuidrequired

Headers

  • Idempotency-Keystringrequired

    A new key for each new post; the same key on a retry returns the first result instead of posting twice.

Body

  • accountIdsuuid[]required
  • scheduledFordate-timerequired

Responses

  • 201One result per account.
    ›Response fields
    • dataScheduleResult[]required
      ›7 fields
      • integrationIduuidrequired
      • publishRecordIduuid
      • statusstringrequired
        • scheduled
        • failed
      • scheduledFordate-time
      • errorstring
      • failureCodestring
      • platformstring

        The platform, such as LINKEDIN.

  • 400The body, query, or path did not validate.
  • 401Missing, mistyped, or revoked key.
  • 403Not on Scale, or the key's role cannot do this.
  • 404Nothing with that id in this Distinctful.
  • 409Approval required (see details.code), or Idempotency-Key conflict.
  • 413The body is larger than 1 MB.
  • 429Over a limit. Wait Retry-After seconds.
  • 503Plan status or storage could not be reached; nothing ran. Wait Retry-After seconds.
curl -X POST https://app.distinctful.com/api/v1/drafts/$DRAFT_ID/schedule \
  -H "Authorization: Bearer $DISTINCTFUL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "accountIds": [
      "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10"
    ],
    "scheduledFor": "2026-11-23T14:00:00.000Z"
  }'
Response201
{
  "data": [
    {
      "integrationId": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
      "publishRecordId": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
      "status": "scheduled",
      "scheduledFor": "2026-11-16T15:00:00.000Z"
    }
  ]
}

Publish the saved draft now

POST/drafts/{id}/publish

Path parameters

  • iduuidrequired

Headers

  • Idempotency-Keystringrequired

    A new key for each new post; the same key on a retry returns the first result instead of posting twice.

Body

  • accountIdsuuid[]required

Responses

  • 201The outcome and one result per account.
    ›Response fields
    • dataPublishResultrequired
      ›2 fields
      • outcomestringrequired
        • published
        • partially_published
        • queued
        • all_failed
      • resultsobject[]required
        ›3 fields
        • integrationIduuidrequired
        • publishRecordIduuidrequired
        • statusstringrequired
          • published
          • queued
          • failed
  • 400The body, query, or path did not validate.
  • 401Missing, mistyped, or revoked key.
  • 403Not on Scale, or the key's role cannot do this.
  • 404Nothing with that id in this Distinctful.
  • 409Approval required (see details.code), or Idempotency-Key conflict.
  • 413The body is larger than 1 MB.
  • 429Over a limit. Wait Retry-After seconds.
  • 503Plan status or storage could not be reached; nothing ran. Wait Retry-After seconds.
curl -X POST https://app.distinctful.com/api/v1/drafts/$DRAFT_ID/publish \
  -H "Authorization: Bearer $DISTINCTFUL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "accountIds": [
      "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10"
    ]
  }'
Response201
{
  "data": {
    "outcome": "published",
    "results": [
      {
        "integrationId": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
        "publishRecordId": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
        "status": "published"
      }
    ]
  }
}

Cancel a scheduled post (owner or Lead)

POST/posts/{id}/cancel

Cancelling again answers the same, so a retry is safe. A video mid-upload answers 202 and stops shortly.

Path parameters

  • iduuidrequired

Responses

  • 200Cancelled.
    ›Response fields
    • dataobjectrequired
      ›2 fields
      • iduuidrequired
      • statusstringrequired
        • cancelled
  • 202Asked to stop.
    ›Response fields
    • dataobjectrequired
      ›2 fields
      • iduuidrequired
      • statusstringrequired
        • cancellation_requested
  • 400The body, query, or path did not validate.
  • 401Missing, mistyped, or revoked key.
  • 403Not on Scale, or the key's role cannot do this.
  • 404Nothing with that id in this Distinctful.
  • 409The post already went to its platform (details.code already_publishing).
  • 429Over a limit. Wait Retry-After seconds.
  • 503Plan status or storage could not be reached; nothing ran. Wait Retry-After seconds.
curl -X POST https://app.distinctful.com/api/v1/posts/$POST_ID/cancel \
  -H "Authorization: Bearer $DISTINCTFUL_API_KEY"
Response200
{
  "data": {
    "id": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
    "status": "cancelled"
  }
}

Ideas

Pages in Ideas, written and read as Markdown, and the folders they are filed in.

Pages in Ideas, most recently changed first

GET/ideas

Pages the workspace wrote. Posts saved from Discover or the extension are not listed.

Query parameters

  • cursorstring
  • folderstring

    Only pages filed in the folder with this exact name.

Responses

  • 200A page of 50 ideas.
    ›Response fields
    • dataobjectrequired
      ›2 fields
      • dataIdea[]required
        ›11 fields
        • iduuidrequired
        • titlestringrequired
        • folderstring | nullrequired

          The name of the folder the page is filed in.

        • pinnedbooleanrequired
        • createdAtdate-timerequired
        • updatedAtdate-timerequired
        • versioninteger

          Counts saves of the page. Send it back as expectedVersion so your edit never replaces a newer one. Returned by single-page reads.

        • tagsstring[]

          Returned by single-page reads.

        • contentstring

          The page as Markdown, in the form PATCH accepts. Returned by single-page reads.

        • contentCompleteboolean

          False when the page holds things Markdown cannot carry, such as images, embeds, tables, or task due dates. Sending content back would remove them, so change only the title, folder, or tags of such a page. Returned by single-page reads.

        • urlstring

          The page in Distinctful. Returned by single-page reads.

      • nextCursorstring | nullrequired

        Pass as cursor for the next page; null on the last page.

  • 400The body, query, or path did not validate.
  • 401Missing, mistyped, or revoked key.
  • 403Not on Scale, or the key's role cannot do this.
  • 429Over a limit. Wait Retry-After seconds.
  • 503Plan status or storage could not be reached; nothing ran. Wait Retry-After seconds.
curl https://app.distinctful.com/api/v1/ideas \
  -H "Authorization: Bearer $DISTINCTFUL_API_KEY"
Response200
{
  "data": {
    "data": [
      {
        "id": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
        "title": "Launch post",
        "folder": "string",
        "pinned": true,
        "createdAt": "2026-11-16T15:00:00.000Z",
        "updatedAt": "2026-11-16T15:00:00.000Z",
        "version": 3,
        "tags": [
          "string"
        ],
        "content": "We just shipped client approvals that never need an account.",
        "contentComplete": true,
        "url": "https://example.com"
      }
    ],
    "nextCursor": "string"
  }
}

Create a page in Ideas from Markdown

POST/ideas

Headers

  • Idempotency-Keystring

    A retry with the same key returns the first result instead of creating a second one.

Body

  • titlestring
  • contentstringrequired

    Markdown. Headings, lists, checkboxes, quotes, and code become blocks, and line breaks stay where you put them.

  • folderstring

    The exact name of an existing folder; see GET /ideas/folders.

  • tagsstring[]

    Tag names. A name that does not exist yet is created.

Responses

  • 201The new page.
    ›Response fields
    • dataIdearequired
      ›11 fields
      • iduuidrequired
      • titlestringrequired
      • folderstring | nullrequired

        The name of the folder the page is filed in.

      • pinnedbooleanrequired
      • createdAtdate-timerequired
      • updatedAtdate-timerequired
      • versioninteger

        Counts saves of the page. Send it back as expectedVersion so your edit never replaces a newer one. Returned by single-page reads.

      • tagsstring[]

        Returned by single-page reads.

      • contentstring

        The page as Markdown, in the form PATCH accepts. Returned by single-page reads.

      • contentCompleteboolean

        False when the page holds things Markdown cannot carry, such as images, embeds, tables, or task due dates. Sending content back would remove them, so change only the title, folder, or tags of such a page. Returned by single-page reads.

      • urlstring

        The page in Distinctful. Returned by single-page reads.

  • 400The body, query, or path did not validate.
  • 401Missing, mistyped, or revoked key.
  • 403Not on Scale, or the key's role cannot do this.
  • 409Idempotency-Key reused for a different request or still running, or new tags would pass the 500-tag limit (details.code tag_limit).
  • 413The body is larger than 1 MB.
  • 429Over a limit. Wait Retry-After seconds.
  • 503Plan status or storage could not be reached; nothing ran. Wait Retry-After seconds.
curl -X POST https://app.distinctful.com/api/v1/ideas \
  -H "Authorization: Bearer $DISTINCTFUL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Launch week hooks",
    "content": "# Launch week hooks\n\n- Most people quit posting right before it starts to work.",
    "tags": [
      "hooks"
    ]
  }'
Response201
{
  "data": {
    "id": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
    "title": "Launch post",
    "folder": "string",
    "pinned": true,
    "createdAt": "2026-11-16T15:00:00.000Z",
    "updatedAt": "2026-11-16T15:00:00.000Z",
    "version": 3,
    "tags": [
      "string"
    ],
    "content": "We just shipped client approvals that never need an account.",
    "contentComplete": true,
    "url": "https://example.com"
  }
}

Ideas folders by name

GET/ideas/folders

Query parameters

  • cursorstring

Responses

  • 200A page of 50 folders.
    ›Response fields
    • dataobjectrequired
      ›2 fields
      • dataIdeaFolder[]required
        ›3 fields
        • iduuidrequired
        • namestringrequired

          Pass as folder to file a page here.

        • parentstring | nullrequired

          The name of the folder this one sits inside.

      • nextCursorstring | nullrequired

        Pass as cursor for the next page; null on the last page.

  • 400The body, query, or path did not validate.
  • 401Missing, mistyped, or revoked key.
  • 403Not on Scale, or the key's role cannot do this.
  • 429Over a limit. Wait Retry-After seconds.
  • 503Plan status or storage could not be reached; nothing ran. Wait Retry-After seconds.
curl https://app.distinctful.com/api/v1/ideas/folders \
  -H "Authorization: Bearer $DISTINCTFUL_API_KEY"
Response200
{
  "data": {
    "data": [
      {
        "id": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
        "name": "string",
        "parent": "string"
      }
    ],
    "nextCursor": "string"
  }
}

A page with its text, folder, and tags

GET/ideas/{id}

Path parameters

  • iduuidrequired

Responses

  • 200The page.
    ›Response fields
    • dataIdearequired
      ›11 fields
      • iduuidrequired
      • titlestringrequired
      • folderstring | nullrequired

        The name of the folder the page is filed in.

      • pinnedbooleanrequired
      • createdAtdate-timerequired
      • updatedAtdate-timerequired
      • versioninteger

        Counts saves of the page. Send it back as expectedVersion so your edit never replaces a newer one. Returned by single-page reads.

      • tagsstring[]

        Returned by single-page reads.

      • contentstring

        The page as Markdown, in the form PATCH accepts. Returned by single-page reads.

      • contentCompleteboolean

        False when the page holds things Markdown cannot carry, such as images, embeds, tables, or task due dates. Sending content back would remove them, so change only the title, folder, or tags of such a page. Returned by single-page reads.

      • urlstring

        The page in Distinctful. Returned by single-page reads.

  • 400The body, query, or path did not validate.
  • 401Missing, mistyped, or revoked key.
  • 403Not on Scale, or the key's role cannot do this.
  • 404Nothing with that id in this Distinctful.
  • 429Over a limit. Wait Retry-After seconds.
  • 503Plan status or storage could not be reached; nothing ran. Wait Retry-After seconds.
curl https://app.distinctful.com/api/v1/ideas/$IDEA_ID \
  -H "Authorization: Bearer $DISTINCTFUL_API_KEY"
Response200
{
  "data": {
    "id": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
    "title": "Launch post",
    "folder": "string",
    "pinned": true,
    "createdAt": "2026-11-16T15:00:00.000Z",
    "updatedAt": "2026-11-16T15:00:00.000Z",
    "version": 3,
    "tags": [
      "string"
    ],
    "content": "We just shipped client approvals that never need an account.",
    "contentComplete": true,
    "url": "https://example.com"
  }
}

Change a page’s title, text, folder, or tags

PATCH/ideas/{id}

Send only the fields to change. content replaces the whole page, and the text it replaces stays in the page’s version history. Read the page first and check contentComplete before replacing its content. An edit never replaces a save it has not seen: send expectedVersion, the version you read, or the edit is checked against the page as it stands when the request arrives. Either way a page that changed in between answers 409 (details.code stale_version).

Path parameters

  • iduuidrequired

Body

  • titlestring
  • contentstring

    Markdown that replaces the whole page. The text it replaces stays in the page’s version history.

  • folderstring | null

    The exact name of an existing folder, or null to take the page out of its folder.

  • tagsstring[]

    Tag names that replace the page’s tags. A name that does not exist yet is created.

  • expectedVersioninteger

    The version you read. The edit is refused with 409 when the page has changed since, so a newer edit is never replaced.

Responses

  • 200The page as saved.
    ›Response fields
    • dataIdearequired
      ›11 fields
      • iduuidrequired
      • titlestringrequired
      • folderstring | nullrequired

        The name of the folder the page is filed in.

      • pinnedbooleanrequired
      • createdAtdate-timerequired
      • updatedAtdate-timerequired
      • versioninteger

        Counts saves of the page. Send it back as expectedVersion so your edit never replaces a newer one. Returned by single-page reads.

      • tagsstring[]

        Returned by single-page reads.

      • contentstring

        The page as Markdown, in the form PATCH accepts. Returned by single-page reads.

      • contentCompleteboolean

        False when the page holds things Markdown cannot carry, such as images, embeds, tables, or task due dates. Sending content back would remove them, so change only the title, folder, or tags of such a page. Returned by single-page reads.

      • urlstring

        The page in Distinctful. Returned by single-page reads.

  • 400The body, query, or path did not validate.
  • 401Missing, mistyped, or revoked key.
  • 403Not on Scale, or the key's role cannot do this.
  • 404Nothing with that id in this Distinctful.
  • 409The page changed since the version this edit was based on (details.code stale_version), or new tags would pass the 500-tag limit (details.code tag_limit).
  • 413The body is larger than 1 MB.
  • 429Over a limit. Wait Retry-After seconds.
  • 503Plan status or storage could not be reached; nothing ran. Wait Retry-After seconds.
curl -X PATCH https://app.distinctful.com/api/v1/ideas/$IDEA_ID \
  -H "Authorization: Bearer $DISTINCTFUL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Launch week hooks, final",
    "expectedVersion": 4
  }'
Response200
{
  "data": {
    "id": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
    "title": "Launch post",
    "folder": "string",
    "pinned": true,
    "createdAt": "2026-11-16T15:00:00.000Z",
    "updatedAt": "2026-11-16T15:00:00.000Z",
    "version": 3,
    "tags": [
      "string"
    ],
    "content": "We just shipped client approvals that never need an account.",
    "contentComplete": true,
    "url": "https://example.com"
  }
}

Move a page to Recently Deleted

DELETE/ideas/{id}

The page can be restored from Recently Deleted in Distinctful. Deleting again succeeds, so a retry is safe.

Path parameters

  • iduuidrequired

Responses

  • 200Deleted.
    ›Response fields
    • dataobjectrequired
      ›2 fields
      • iduuidrequired
      • deletedbooleanrequired
        • true
  • 400The body, query, or path did not validate.
  • 401Missing, mistyped, or revoked key.
  • 403Not on Scale, or the key's role cannot do this.
  • 404Nothing with that id in this Distinctful.
  • 429Over a limit. Wait Retry-After seconds.
  • 503Plan status or storage could not be reached; nothing ran. Wait Retry-After seconds.
curl -X DELETE https://app.distinctful.com/api/v1/ideas/$IDEA_ID \
  -H "Authorization: Bearer $DISTINCTFUL_API_KEY"
Response200
{
  "data": {
    "id": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
    "deleted": true
  }
}

Results

Published posts and the numbers each platform reports.

Published posts with platform-reported metrics

GET/posts

Query parameters

  • cursorstring

Responses

  • 200A page of 50 posts, newest first.
    ›Response fields
    • dataobjectrequired
      ›2 fields
      • dataPost[]required
        ›14 fields
        • publishRecordIduuidrequired
        • contentCardIduuidrequired

          The draft it was published from.

        • platformstringrequired
          • BEEHIIV
          • TIKTOK
          • INSTAGRAM
          • THREADS
          • YOUTUBE
          • TWITTER
          • LINKEDIN
          • BLUESKY
          • FACEBOOK
          • MASTODON
        • publishedAtdate-timerequired
        • titlestringrequired
        • platformUrlstring | nullrequired
        • viewsinteger | nullrequired
        • impressionsinteger | nullrequired
        • interactionsinteger | nullrequired
        • engagementRatenumber | nullrequired
        • likesinteger | nullrequired
        • commentsinteger | nullrequired
        • sharesinteger | nullrequired
        • lastSourceSyncedAtdate-time | nullrequired

          When the platform last reported these numbers.

      • nextCursorstring | nullrequired

        Pass as cursor for the next page; null on the last page.

  • 400The body, query, or path did not validate.
  • 401Missing, mistyped, or revoked key.
  • 403Not on Scale, or the key's role cannot do this.
  • 429Over a limit. Wait Retry-After seconds.
  • 503Plan status or storage could not be reached; nothing ran. Wait Retry-After seconds.
curl https://app.distinctful.com/api/v1/posts \
  -H "Authorization: Bearer $DISTINCTFUL_API_KEY"
Response200
{
  "data": {
    "data": [
      {
        "publishRecordId": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
        "contentCardId": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
        "platform": "LINKEDIN",
        "publishedAt": "2026-11-16T15:00:00.000Z",
        "title": "Launch post",
        "platformUrl": "https://example.com",
        "views": 0,
        "impressions": 0,
        "interactions": 0,
        "engagementRate": 0,
        "likes": 0,
        "comments": 0,
        "shares": 0,
        "lastSourceSyncedAt": "2026-11-16T15:00:00.000Z"
      }
    ],
    "nextCursor": "string"
  }
}

Social summary for 30 or 90 days

GET/analytics/summary

Query parameters

  • periodany
    • 30d
    • 90d

Responses

  • 200The summary Analytics shows.
    ›Response fields
    • dataAnalyticsSummaryrequired
      ›8 fields
      • periodstringrequired
        • 30d
        • 90d
      • reachinteger | nullrequired
      • trendnumber | nullrequired
      • interactionsinteger | nullrequired
      • postsShippedinteger | nullrequired
      • engagementRatenumber | nullrequired
      • platformsobject[]required
        ›6 fields
        • platformstringrequired
        • reachinteger | nullrequired
        • trendnumber | nullrequired
        • postsShippedinteger | nullrequired
        • engagementRatenumber | nullrequired
        • followersinteger | nullrequired
      • dailyobject[]required
        ›4 fields
        • datestringrequired
        • reachintegerrequired
        • postsintegerrequired
        • reachByPlatformmaprequired
  • 400The body, query, or path did not validate.
  • 401Missing, mistyped, or revoked key.
  • 403Not on Scale, or the key's role cannot do this.
  • 429Over a limit. Wait Retry-After seconds.
  • 503Plan status or storage could not be reached; nothing ran. Wait Retry-After seconds.
curl https://app.distinctful.com/api/v1/analytics/summary \
  -H "Authorization: Bearer $DISTINCTFUL_API_KEY"
Response200
{
  "data": {
    "period": "30d",
    "reach": 0,
    "trend": 0,
    "interactions": 0,
    "postsShipped": 0,
    "engagementRate": 0,
    "platforms": [
      {
        "platform": "LINKEDIN",
        "reach": 0,
        "trend": 0,
        "postsShipped": 0,
        "engagementRate": 0,
        "followers": 0
      }
    ],
    "daily": [
      {
        "date": "string",
        "reach": 0,
        "posts": 0,
        "reachByPlatform": {}
      }
    ]
  }
}

Events

Review steps and publish outcomes, in the order they were recorded.

Review steps and publish outcomes, in the order they were recorded

GET/events

Pass after (an ISO time) on the first call, then the data.nextCursor each response returns. The last 10 seconds are held back so late writes are not skipped. Delivery is at least once: dedupe by event id. data.hasMore means the next page is ready now.

Query parameters

  • afterdate-time
  • cursorstring

Responses

  • 200Up to 50 events.
    ›Response fields
    • dataobjectrequired
      ›3 fields
      • dataEvent[]required
        ›8 fields
        • idstringrequired

          Dedupe on this: delivery is at least once.

        • typestringrequired
          • review.requested
          • review.approved
          • review.changes_requested
          • review.commented
          • review.shared
          • review.overridden
          • review.scheduled
          • post.published
          • post.failed
        • atdate-timerequired
        • draftIduuid | nullrequired
        • reviewerNamestring
        • postIduuid
        • platformstring

          The platform, such as LINKEDIN.

        • urlstring

          The live post, on post.published.

      • nextCursorstringrequired
      • hasMorebooleanrequired
  • 400The body, query, or path did not validate.
  • 401Missing, mistyped, or revoked key.
  • 403Not on Scale, or the key's role cannot do this.
  • 429Over a limit. Wait Retry-After seconds.
  • 503Plan status or storage could not be reached; nothing ran. Wait Retry-After seconds.
curl https://app.distinctful.com/api/v1/events \
  -H "Authorization: Bearer $DISTINCTFUL_API_KEY"
Response200
{
  "data": {
    "data": [
      {
        "id": "string",
        "type": "review.requested",
        "at": "2026-11-16T15:00:00.000Z",
        "draftId": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
        "reviewerName": "string",
        "postId": "6f1c2a8e-4b0d-4c55-9a43-2f1e7c9b5d10",
        "platform": "LINKEDIN",
        "url": "https://example.com"
      }
    ],
    "nextCursor": "string",
    "hasMore": true
  }
}