Authentication

PostPulse API uses OAuth 2.0 for authentication. Sign up at PostPulse and create an OAuth application at PostPulse Developer Portal to get your API credentials instantly.

API Base URLs

Authentication: https://auth.post-pulse.com
API Endpoints:  https://api.post-pulse.com

OAuth Flow

// Step 1: Get authorization code
GET https://auth.post-pulse.com/authorize
  ?client_id=YOUR_CLIENT_ID
  &response_type=code
  &redirect_uri=YOUR_REDIRECT_URI
  &scope=offline_access postpulse-api/accounts.read postpulse-api/api postpulse-api/media.write postpulse-api/posts.read postpulse-api/posts.write postpulse-api/webhooks.write
  &state=YOUR_STATE_PARAMETER
  &audience=https://api.post-pulse.com

// Step 2: Exchange code for access token
POST https://auth.post-pulse.com/oauth/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "code": "AUTHORIZATION_CODE",
  "redirect_uri": "YOUR_REDIRECT_URI"
}

The token response contains an access token valid for 24 hours. Include offline_access in scope to also receive a refresh token, so your backend can keep working without another browser login:

{
  "access_token": "eyJhbGciOi...",
  "refresh_token": "v1.MjE3...",     // Present only when offline_access was requested
  "scope": "offline_access postpulse-api/accounts.read ...",
  "expires_in": 86400,
  "token_type": "Bearer"
}

Refreshing the Access Token

Exchange the refresh token for a new access token whenever the current one expires, or at the start of every run for scheduled jobs:

POST https://auth.post-pulse.com/oauth/token
Content-Type: application/json

{
  "grant_type": "refresh_token",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "refresh_token": "YOUR_REFRESH_TOKEN"
}

// Response: a new access_token AND a new refresh_token.
// Store the new refresh_token; the one you just sent no longer works.
  • Refresh tokens rotate. Every refresh returns a new refresh token and invalidates the one you sent. Reusing an old refresh token revokes the whole chain, and the user has to log in again. Persist the new token after every refresh.
  • Don't refresh in parallel. If two workers refresh with the same token, one of them reuses an invalidated token. Serialize refreshes (one job at a time, or a lock).
  • Lifetimes: a refresh token expires after 7 days without use and 1 year after the original login, whichever comes first. After that, repeat the authorization step.
  • An invalid_grant error means the refresh token is no longer valid. Send the user through the authorization step again.

Using Access Token

All API requests must include the Bearer token in the Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

Accounts

Retrieve connected social media accounts for the authenticated user.

Get All Accounts

GET/v1/accounts

Returns a list of all social media accounts connected by the user.

Response Example

[
  {
    "id": 123,
    "platform": "INSTAGRAM",
    "accountId": "instagram_user_id",
    "accountUsername": "myaccount",
    "accountDisplayName": "My Instagram Account",
    "accountAvatarUrl": "https://example.com/avatar.jpg",
    "createdTime": "2025-08-15T10:30:00.000000",
    "updatedTime": "2025-08-15T10:30:00.000000"
  }
]

Get Connected Chats

GET/v1/accounts/{id}/chats

Returns the destinations a post can target on accounts that publish to a specific channel, Page, board or phone number. Pass the returned id as the post's chatId. What is returned depends on the account's platform:

  • TELEGRAM — channels/chats where the bot can publish
  • FACEBOOK — Facebook Pages managed by the account
  • PINTEREST — the account's Pinterest boards (type is BOARD)
  • WHATSAPP — phone numbers of the WhatsApp Business account (type is PHONE_NUMBER, see WhatsApp Broadcasts)

Accounts of any other platform, including FACEBOOK_PAGE, have no chats: the request returns 400. Publish to such an account directly, without chatId.

Response Example — Telegram

[
  {
    "id": "-1002726180643",
    "title": "PostPulse Official",
    "type": "channel",
    "platform": "TELEGRAM"
  }
]

Response Example — Pinterest

[
  {
    "id": "1018813041503562001",
    "title": "Spring Recipes",
    "type": "BOARD",
    "platform": "PINTEREST"
  }
]

Media Upload

Most platforms require media to be hosted in PostPulse storage before scheduling. You have three ways to get media there — pick the one that fits your use case.

1

Direct Upload

POST /v1/media/upload

Send the file as binary in a single multipart/form-data request.

  • Simplest approach
  • Best for small files
  • Synchronous — returns the media key immediately
2

Pre-signed PUT URL

POST /v1/media/upload/urls

Request a pre-signed URL, then PUT the file directly to our storage.

  • Best for large files
  • Bypasses API size limits
  • Confirm step recommended after upload
3

Public URL Import

POST /v1/media/upload/import

Provide a public URL — we download the file into our storage.

  • Fully asynchronous
  • Poll for completion
  • Or pass the URL directly to attachmentPaths

Direct Upload

POST/v1/media/upload

Upload an image or video file in a single request.

Request

Content-Type: multipart/form-data

file: [binary file data]

Response Example

{
  "path": "6354d8d2-e0f1-702b-af6c-62e28e377ec7/e1992700-96f5-4f0b-bd48-45d902ffbb0c.jpeg"
}

Use the returned path as an entry in attachmentPaths when creating a post.

Pre-signed PUT URL

For large files, request a pre-signed URL and upload the binary directly to our storage. This takes three calls: request URL → PUT file → confirm upload.

Your ClientPostPulse APIObject StoragePOST /v1/media/upload/urls{ filename, contentType, sizeBytes }200 OK{ key, url, method, headers, expiresAt }PUT {url} — binary file(with headers from previous response)200 OKPOST /v1/media/upload/confirm (recommended){ key }204 No Content

1. Request the URL

POST/v1/media/upload/urls

Get a pre-signed URL configured for your file's filename, content type, and size.

Request Schema
{
  "filename": "my-video.mp4",
  "contentType": "video/mp4",
  "sizeBytes": 10485760
}
Response Schema
{
  "key": "f157080a-7c45-4b43-9d7c-d17dd83dbf92/b43ec45c-6367-4edd-868b-5f704a4ff04e.mp4",
  "method": "PUT",
  "url": "https://postpulse-prod-user-media.s3.eu-central-1.amazonaws.com/f157080a-7c45-4b43-9d7c-d17dd83dbf92/b43ec45c-6367-4edd-868b-5f704a4ff04e.mp4?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20260418T193733Z&X-Amz-SignedHeaders=content-type%3Bhost%3Bx-amz-meta-declared-size%3Bx-amz-meta-orig-filename&X-Amz-Credential=...&X-Amz-Expires=600&X-Amz-Signature=...",
  "headers": {
    "Content-Type": "video/mp4",
    "x-amz-meta-declared-size": "10485760",
    "x-amz-meta-orig-filename": "my-video.mp4"
  },
  "expiresAt": "2026-04-18T19:47:33Z"
}
Important: You must send the request to the returned url with the exact headers and HTTP method from the response — the signature is bound to them.

2. PUT the file to the returned URL

PUT https://postpulse-prod-user-media.s3.eu-central-1.amazonaws.com/...?X-Amz-Signature=...
Content-Type: video/mp4
x-amz-meta-declared-size: 10485760
x-amz-meta-orig-filename: my-video.mp4

[binary file bytes]

Storage responds with 200 OK on success. The URL expires after the window shown in expiresAt.

3. Confirm the upload (recommended)

POST/v1/media/upload/confirm

Confirms the file landed in our storage, runs a basic integrity check (for videos, this verifies the container is readable), and detects the file's real type from its bytes. Optional but recommended — catches transfer problems early and avoids surprises at post time.

Request Schema
{
  "key": "f157080a-7c45-4b43-9d7c-d17dd83dbf92/b43ec45c-6367-4edd-868b-5f704a4ff04e.mp4"
}
Response Schema
{
  "key": "b43ec45c-6367-4edd-868b-5f704a4ff04e.mp4",
  "path": "f157080a-7c45-4b43-9d7c-d17dd83dbf92/b43ec45c-6367-4edd-868b-5f704a4ff04e.mp4",
  "filename": "my-video.mp4",
  "contentType": "video/mp4",
  "sizeBytes": 10485760,
  "url": "https://..."
}

The returned path is always the key you were given in step 1 — a key never moves once it has been handed out, so it is safe to store it before confirming.

Content type beats the extension. The key's extension comes from the filename you declared before any bytes existed, so it can disagree with what you actually uploaded — a PNG sent under the name photo.jpeg keeps a .jpegkey. The returned contentType is detected from the file itself and is what we use when publishing (image conversion, platform format rules). Read the type from contentType, never from the key.

A file whose bytes are neither an image nor a video is refused: confirm answers 400 naming the type we found, the stored object is deleted, and that key can no longer be used in attachmentPaths — scheduling a post with it fails with the same reason. Upload the file again as a supported image or video. A corrupt or incomplete file is refused the same way.

Confirm also checks that the file actually reached storage. If the PUT failed or was never made, confirm waits a few seconds for it, then answers 400 with Upload not found in storage. The key stays pending: PUT the file to the same URL while it is still valid (see expiresAt) and confirm again. A key that never receives its file expires and does not appear in the media library.

Public URL Import

Already have a public URL? Hand it to us and we'll pull the file into storage for you. This is fully asynchronous — you get an import job back and poll for completion.

Your ClientPostPulse APISource URLPOST /v1/media/upload/import{ url, filenameHint }202 Accepted{ id, state: "QUEUED" }GET (background download)GET /v1/media/upload/import/{id} (poll)200 OK{ state: "READY", s3Key, ... }
Shortcut: You can also pass a public URL directly as an entry in attachmentPaths when creating a post — see the Post Scheduling section. The platform will create the import job for you and flip the post to SCHEDULED once the file is ready.

Start an import

POST/v1/media/upload/import

Kick off a background import from a public URL.

Request Schema
{
  "url": "https://example.com/image.jpg",
  "filenameHint": "image.jpg"
}
Response Schema
{
  "id": 12345,
  "state": "QUEUED"
}

Poll import status

GET/v1/media/upload/import/{id}

Get the current status of a media import job.

Response Schema
{
  "id": 12345,
  "state": "READY",            // QUEUED, DOWNLOADING, VALIDATING, UPLOADING, READY, FAILED_TEMPORARY, FAILED_PERMANENT
  "sourceUrl": "https://example.com/image.jpg",
  "bytesDownloaded": 2048576,
  "totalBytes": 2048576,
  "detectedMime": "image/jpeg",
  "s3Key": "6354d8d2-e0f1-702b-af6c-62e28e377ec7/e1992700-96f5-4f0b-bd48-45d902ffbb0c.jpeg",
  "errorCode": null,
  "errorMessage": null
}

When state is READY, use s3Key as the attachmentPaths entry. FAILED_PERMANENT means the job is dead — inspect errorCode and errorMessage. FAILED_TEMPORARY may still recover.

Tip: Instead of polling, you can use Webhooks to receive a media.import.ready event when the import is complete.

Media Library

Every uploaded, confirmed or imported file stays in the user's media library until you delete it. Deleting a post does not delete its files.

List files

GET/v1/media

Returns the library page by page, newest first. Query parameters: page (from 0, default 0) and size (default 20).

Response Schema
{
  "items": [
    {
      "key": "e1992700-96f5-4f0b-bd48-45d902ffbb0c.jpeg",
      "path": "6354d8d2-e0f1-702b-af6c-62e28e377ec7/e1992700-96f5-4f0b-bd48-45d902ffbb0c.jpeg",
      "url": "https://...",            // Temporary download URL
      "filename": "launch.jpeg",
      "contentType": "image/jpeg",
      "sizeBytes": 245133,
      "thumbnailUrl": null             // Preview image of a video, or null
    }
  ],
  "page": 0,
  "size": 20,
  "totalItems": 43,
  "totalPages": 3
}

Check what deleting a file would do

GET/v1/media/deletion-impact?key={key}

Lists the posts that use the file and what deleting it would do to each of them. Pass the file's key from the list above, not its path.

  • MEDIA_DELETED — the post only loses the file. Always the case for a post that is published or failed: it stays as the record of what was published.
  • PUBLICATION_DELETED — the post is not published yet, and on some accounts it is left without the media the platform requires (or without any content); those publications are deleted, the others stay.
  • SCHEDULE_DELETED — every publication of a post that is not published yet is deleted, so the whole post is deleted.
Response Schema
[
  {
    "id": 9821,                        // Post id
    "content": "Ready to go!",
    "platforms": ["TELEGRAM", "INSTAGRAM"],
    "scheduledTime": "2026-04-17T23:33:00Z",
    "outcome": "SCHEDULE_DELETED"      // MEDIA_DELETED | PUBLICATION_DELETED | SCHEDULE_DELETED
  }
]

Delete a file

DELETE/v1/media/{key}

Deletes the file from storage and from the library, and changes the posts that use it as described above. Returns 204 No Content. If a post that uses the file is being published (IN_PROGRESS), the request is rejected with 409 and code post_in_progress, and nothing is deleted: the platform may still be fetching the file. Retry once publishing finishes. A key that matches no file returns 404, and so does deleting the same file again.

Subscribers get media.deleted for the file, and publication.deleted / schedule.deleted for every publication or post deleted with it (see Webhooks).

Post Scheduling

Schedule posts to one or multiple social media platforms simultaneously, then track, edit or delete them.

Understanding the Data Model

PostSchedule

The root object that contains common settings for all publications:

  • scheduledTime: When to publish. Accepts ISO 8601 with or without timezone offset (see below).
  • isDraft: Whether this is a draft (recommended: false for API)
  • publications: Array of Publication objects

Publication

Represents publishing to one social media account:

  • socialMediaAccountId: Required. The numeric id of a connected account from the accounts endpoint (not the platform-side accountId).
  • platformSettings: Required. Object with at least a type matching the account platform (e.g. { "type": "TELEGRAM" }); some platforms need extra fields, see Platform Settings.
  • posts: Array of Post objects

Post

Individual post content:

  • content: Post text/description
  • attachmentPaths: Array of media references — each entry is either an s3 key returned by a media upload, or a public URL we should import.
  • chatId: Target destination on the account: the Telegram channel ID, Facebook Page ID, Pinterest board ID (required for Pinterest) or the WhatsApp phone number to send from (required for WhatsApp). Get the IDs from Get Connected Chats. Only Telegram, Facebook, Pinterest and WhatsApp use chatId; on any other platform it is ignored, not stored and left out of responses.
  • thumbnailPath: Optional cover for a video: the storage key of an image. Instagram uses it as the cover of a single-video Reel, and List Posts returns it as the post's coverImageUrl (without it, a frame of the video). Other platforms don't use it.

Scheduled Time Formats

The scheduledTime field accepts ISO 8601 with or without a timezone offset. All values are normalized to UTC on the server.

// All three formats are accepted:

"2026-04-17T23:33:00"          // No offset — interpreted as UTC
"2026-04-17T23:33:00Z"         // Explicit UTC
"2026-04-17T19:33:00-04:00"    // With offset — normalized to UTC server-side

Attachments: Key vs Public URL

Each entry in attachmentPaths can be one of two things:

Storage key (path)

Returned from any of the Media Upload endpoints. The post is created in SCHEDULED status immediately.

"attachmentPaths": [
  "6354d8d2-.../e1992700-...jpeg"
]

Public URL

We create an import job and flip the post to SCHEDULED once the file is ready. If the import fails permanently, the post moves to MEDIA_IMPORT_FAILED.

"attachmentPaths": [
  "https://example.com/my-image.jpg"
]

Post Lifecycle

The diagram below shows how a posting schedule moves through statuses. Posts with s3 keys go straight to SCHEDULED. Posts with public URLs start in AWAITING_MEDIA and transition to SCHEDULED once every referenced file has been imported — or to MEDIA_IMPORT_FAILED if any import fails permanently.

Post schedule lifecycle diagram showing transitions between DRAFT, AWAITING_MEDIA, SCHEDULED, MEDIA_IMPORT_FAILED, IN_PROGRESS, COMPLETED, PARTIALLY_COMPLETED and FAILED states

Create Post Schedule

POST/v1/posts

Schedule a post to one or multiple platforms.

Request Example — Storage Key

{
  "scheduledTime": "2026-04-17T19:33:00-04:00",
  "isDraft": false,
  "publications": [
    {
      "socialMediaAccountId": 445,
      "platformSettings": {
        "type": "TELEGRAM"
      },
      "posts": [
        {
          "content": "Ready to go!",
          "chatId": "-1001947450140",
          "attachmentPaths": [
            "6354d8d2-e0f1-702b-af6c-62e28e377ec7/e1992700-96f5-4f0b-bd48-45d902ffbb0c.jpeg"
          ]
        }
      ]
    }
  ]
}

Request Example — Public URL

{
  "scheduledTime": "2026-04-20T12:00:00Z",
  "isDraft": false,
  "publications": [
    {
      "socialMediaAccountId": 445,
      "platformSettings": { "type": "TELEGRAM" },
      "posts": [
        {
          "content": "Posting from a remote image",
          "chatId": "-1001947450140",
          "attachmentPaths": [
            "https://example.com/my-image.jpg"
          ]
        }
      ]
    }
  ]
}

Request Example — Pinterest Pin

The board goes in chatId; pin options go in platformSettings (see Platform Settings).

{
  "scheduledTime": "2026-04-20T12:00:00Z",
  "isDraft": false,
  "publications": [
    {
      "socialMediaAccountId": 512,
      "platformSettings": {
        "type": "PINTEREST",
        "title": "Easy spring salad",
        "link": "https://example.com/recipes/spring-salad"
      },
      "posts": [
        {
          "content": "A 10-minute salad with seasonal greens.",
          "chatId": "1018813041503562001",
          "attachmentPaths": [
            "6354d8d2-e0f1-702b-af6c-62e28e377ec7/b7c1f0a2-3d4e-4f5a-9b6c-7d8e9f0a1b2c.jpeg"
          ]
        }
      ]
    }
  ]
}

Response

Returns 201 Created with the newly created posting schedule. Fields without a value (for example thumbnail, or pendingImports when nothing is being imported) are omitted from the response:

{
  "id": 9821,
  "overallStatus": "SCHEDULED",       // SCHEDULED | AWAITING_MEDIA | DRAFT
  "scheduledTime": "2026-04-17T23:33:00Z",
  "publications": [
    {
      "id": 14433,
      "socialMediaAccountId": 445,
      "platformSettings": { "type": "TELEGRAM" },
      "posts": [
        {
          "id": 28801,
          "chatId": "-1001947450140",
          "content": "Ready to go!",
          "attachmentPaths": [
            "6354d8d2-e0f1-702b-af6c-62e28e377ec7/e1992700-96f5-4f0b-bd48-45d902ffbb0c.jpeg"
          ]
        }
      ]
    }
  ]
  // "pendingImports" is added when attachmentPaths contain public URLs (see below)
}

When any attachmentPaths entry is a public URL, overallStatus is AWAITING_MEDIA and pendingImports is populated with one entry per in-flight import. Track progress by polling GET /v1/media/upload/import/{importTaskId}:

"pendingImports": [
  {
    "postId": 28801,
    "attachmentIndex": 0,
    "importTaskId": 12345,
    "sourceUrl": "https://example.com/my-image.jpg",
    "state": "QUEUED"                 // Poll GET /v1/media/upload/import/{importTaskId}
  }
]

List Posts

GET/v1/posts

Returns the user's posting schedules, ordered by scheduledTime. Both query parameters are optional ISO 8601 instants and filter on scheduledTime (inclusive). Pass a window: without one, every post the user ever created is returned.

  • fromDate — earliest scheduledTime to include
  • toDate — latest scheduledTime to include

Request Example

GET /v1/posts?fromDate=2026-04-01T00:00:00Z&toDate=2026-05-01T00:00:00Z

Response Example

[
  {
    "id": 9821,
    "content": "Ready to go!",
    "overallStatus": "SCHEDULED",
    "scheduledTime": "2026-04-17T23:33:00Z",
    "platforms": ["TELEGRAM", "INSTAGRAM"],
    "coverImageUrl": "https://..."    // First attached image, or null
  }
]

Get Post Details

GET/v1/posts/{id}

Returns one posting schedule with a status per account (publications[].status) and, for each post, the platform's post id and public link (permalink), or the error message. Published posts also carry metrics. Returns 404 if the post doesn't exist or belongs to another user.

Response Example

{
  "id": 9821,
  "overallStatus": "PARTIALLY_COMPLETED",
  "scheduledTime": "2026-04-17T23:33:00Z",
  "publications": [
    {
      "id": 14433,                      // Publication id (use it to remove one account)
      "socialMediaAccountId": 445,
      "accountUsername": "my_channel",
      "platformName": "TELEGRAM",
      "status": "COMPLETED",
      "platformSettingsNew": { "type": "TELEGRAM" },
      "posts": [
        {
          "id": 28801,
          "chatId": "-1001947450140",
          "platformPostIdentifier": "412",    // The post's id on the platform
          "permalink": "https://t.me/my_channel/412",  // Public link to the post, or null
          "errorMessage": null,
          "content": "Ready to go!",
          "media": [
            {
              "key": "e1992700-96f5-4f0b-bd48-45d902ffbb0c.jpeg",
              "path": "6354d8d2-.../e1992700-96f5-4f0b-bd48-45d902ffbb0c.jpeg",
              "url": "https://...",       // Temporary download URL
              "filename": "launch.jpeg",
              "contentType": "image/jpeg",
              "sizeBytes": 245133,
              "thumbnailUrl": null
            }
          ],
          "thumbnail": null,
          "metrics": null                // See Post Metrics below; null until collected
        }
      ]
    },
    {
      "id": 14434,
      "socialMediaAccountId": 512,
      "accountUsername": "my_brand",
      "platformName": "INSTAGRAM",
      "status": "FAILED",
      "platformSettingsNew": { "type": "INSTAGRAM", "publicationType": "FEED", "aiContent": false },
      "posts": [
        {
          "id": 28802,
          "chatId": null,
          "platformPostIdentifier": null,
          "permalink": null,
          "errorMessage": "...",          // Why publishing failed
          "content": "Ready to go!",
          "media": [ ... ],
          "thumbnail": null,
          "metrics": null
        }
      ]
    }
  ]
}
Tip: Instead of polling this endpoint, subscribe to Webhooks to get schedule.*, publication.* and post.* events as statuses change.

Post Metrics

Published posts carry metrics, refreshed from the platform on each call of this endpoint (if the platform returns nothing, the last known values are returned). impressions, engagements, likes, shares, comments and profileClicks are common to all platforms; a metric the platform does not report is null.

platformAnalytics holds the platform's own analytics for the post, named as the platform names them, for example view_count on TikTok or views and quotes on Threads. The platform is the publication's platformName. Its fields depend on the platform and the post type and may change with the platform's API, so do not rely on a fixed set. It is null when the platform reports none.

"metrics": {
  "impressions": 182,
  "engagements": null,              // null when the platform does not report this metric
  "likes": 1,
  "shares": 0,
  "comments": 0,
  "profileClicks": null,
  "lastUpdatedTime": "2026-10-27T12:17:34Z",
  "platformAnalytics": {            // The platform's own fields, named as the platform names them
    "like_count": 1,
    "comment_count": 0,
    "share_count": 0,
    "view_count": 182
  }
}

Edit a Post

PATCH/v1/posts/{id}

Changes a posting schedule in place: its scheduledTime, and the text, attachments and cover of individual posts. Send only what changes: a field you leave out keeps its value, and posts you don't list stay as they are. Every id stays the same and a draft stays a draft. Platform settings, accounts and chatId can't be changed here. Returns 200 OK with the posting schedule in the same shape as Get Post Details.

A post can be edited while its overallStatus is DRAFT, SCHEDULED, AWAITING_MEDIA or MEDIA_IMPORT_FAILED. Once publishing starts, an edit gets 400.

Request Example

scheduledTime takes the same formats as on create and can't be in the past. Each entry of posts names a post by id and carries only the fields to change:

PATCH /v1/posts/9821

{
  "scheduledTime": "2026-04-18T09:00:00Z",
  "posts": [
    {
      "id": 28801,
      "content": "Ready to go, one day later!"
    },
    {
      "id": 28802,
      "attachmentPaths": [
        "6354d8d2-e0f1-702b-af6c-62e28e377ec7/e1992700-96f5-4f0b-bd48-45d902ffbb0c.jpeg",
        "https://example.com/second-image.jpg"
      ]
    }
  ]
}
Post fieldMeaning
idRequired. The post's id: posts[].id of a publication in Get Post Details.
contentThe new text.
clearContenttrue removes the text. Not together with content.
attachmentPathsThe new list of attachments, in order; it replaces the current list. Entries are storage keys or public URLs, as on create. A public URL that is still being imported is not downloaded again.
removeAttachmentstrue removes every attachment and the cover. Not together with attachmentPaths or thumbnailPath.
thumbnailPathThe cover, as a storage key (see thumbnailPath in the Post model above). New attachmentPaths without it remove the cover; send both in one request to set a new one.

Removing the Text or the Attachments

Empty values are refused, not read as "remove": an empty content, attachmentPaths or thumbnailPath gets 400. To remove the text, send clearContent: true; to remove the attachments, send removeAttachments: true. A flag set to false or null means the same as leaving it out.

{
  "posts": [
    { "id": 28801, "removeAttachments": true }
  ]
}

Statuses and Validation

The edited schedule is checked against the same platform rules as on create (text length, media types and so on), so an edit that breaks one gets 400 with the reason. A post whose text comes from the platform, such as a WhatsApp template message, can't take content or clearContent.

A new public URL in attachmentPaths moves the post to AWAITING_MEDIA until the file is imported, as on create. To get a post out of MEDIA_IMPORT_FAILED, replace the attachment that failed; sending the same URL again retries the import. When an edit changes a publication's status, subscribers get the matching publication.* event (see Webhooks).

Errors

Each of these gets 400 with a message in error, and nothing is changed:

  • nothing to change: no scheduledTime and no post field or flag;
  • an empty content or thumbnailPath, an empty attachmentPaths or an empty entry in it;
  • a field together with the flag that removes it: content with clearContent, attachmentPaths or thumbnailPath with removeAttachments;
  • scheduledTime in the past;
  • a post id that isn't in this schedule, or the same id twice;
  • an overallStatus that can't be edited;
  • a platform rule the edited post breaks;
  • content or clearContent on a post whose text comes from the platform.
HTTP/1.1 400 Bad Request

{
  "error": "Post 28801: content is empty. To keep the text, leave content out; to remove it, send clearContent: true"
}

Delete a Post

DELETE/v1/posts/{id}

Deletes the posting schedule with all its publications. Returns 204 No Content.

  • DRAFT, SCHEDULED, AWAITING_MEDIA, MEDIA_IMPORT_FAILED — the post is cancelled and never published.
  • COMPLETED, PARTIALLY_COMPLETED, FAILED — the post is deleted from PostPulse permanently, with its metrics and analytics. This cannot be undone. The posts already published stay on the platforms, unless you pass deleteFromPlatform=true.
  • IN_PROGRESS — rejected with 409 and code post_in_progress; nothing is deleted. Retry once publishing finishes.

Files the post used stay in the media library; delete them with DELETE /v1/media/{key}. Subscribers get publication.deleted for every publication and then schedule.deleted (see Webhooks).

HTTP/1.1 409 Conflict

{
  "error": "Post 9821 is IN_PROGRESS; try again when it finishes",
  "code": "post_in_progress"
}

Remove One Account from a Post

DELETE/v1/posts/{id}/accounts/{publicationId}

Removes a single publication from the posting schedule and keeps the others. Use publications[].id from Get Post Details (not the socialMediaAccountId). Removing the last publication deletes the whole schedule. Returns 204 No Content.

The statuses work as for deleting the whole post, and a published or failed publication is deleted permanently as well. A published post then takes its overallStatus from the publications left: PARTIALLY_COMPLETED without its failed publication becomes COMPLETED. While overallStatus is IN_PROGRESS (even if this publication has already finished) or AWAITING_MEDIA, the request is rejected with 409 and code post_in_progress; retry once the post leaves that status. Subscribers get publication.deleted, and schedule.deleted when the last publication goes.

Delete on the Platforms

Both DELETE endpoints accept the optional query parameter deleteFromPlatform (default false). With true, the published posts are deleted on the platforms first, then the post is deleted in PostPulse, and the response is 204 No Content. It applies to COMPLETED, PARTIALLY_COMPLETED and FAILED posts; whatever failed to publish is skipped, since it never reached the platform. For any other status the parameter changes nothing.

DELETE /v1/posts/9821?deleteFromPlatform=true

It is all or nothing:

  • 400 with code platform_deletion_not_supported — a published post can't be deleted on its platform (see Supported Platforms below); platforms names those platforms. The request is refused before any platform call, and nothing is deleted. To remove the post from PostPulse only, repeat the request without deleteFromPlatform.
  • 502 with code platform_deletion_failed — a platform failed to delete a post; platform and publicationId name the publication. Nothing is deleted in PostPulse. Posts deleted on the platforms before the failure stay deleted. Retrying the same request is safe: a post already gone from the platform counts as deleted.
HTTP/1.1 400 Bad Request

{
  "error": "Can't delete the published post on TikTok; delete it without deleteFromPlatform to remove it from PostPulse only",
  "code": "platform_deletion_not_supported",
  "platforms": ["TIKTOK"]
}
HTTP/1.1 502 Bad Gateway

{
  "error": "Failed to delete the post on X, nothing was deleted in PostPulse and retrying is safe: X Error: Service Unavailable",
  "code": "platform_deletion_failed",
  "platform": "X_TWITTER",
  "publicationId": 10342
}

Each publication.deleted event carries deletedFromPlatform: true when the publication's published posts were deleted on the platform (see Webhooks).

Supported Platforms

Posts are deleted on the platforms below. On any other platform a published post gets 400.

PlatformNotes
X (X_TWITTER)Every post of a thread is deleted. X allows 50 deletions per account in 15 minutes; above that the request gets 502, retry later.
Pinterest (PINTEREST)The pin is deleted.
YouTube (YOUTUBE)The video is deleted. YouTube deletions count against a daily API quota shared across PostPulse; when it runs out the request gets 502, retry later.
Bluesky (BLUE_SKY)The post is deleted.
Telegram (TELEGRAM)Every message of the post is deleted, including each message of an album. Telegram allows this only within 48 hours of publishing; for an older post the whole request gets 400.
Facebook (FACEBOOK)Feed posts (text, photos, carousels and videos) and Reels are deleted along with their media. A Story can't be deleted: the whole request gets 400, and the Story disappears by itself 24 hours after publishing. For some seconds after publishing, Facebook refuses to delete a video or Reel, answering as if it were already gone. So while a post is under 5 minutes old, that answer gets 502: retry shortly. After that, a post Facebook reports as gone counts as deleted.
Facebook Page (FACEBOOK_PAGE)Feed posts (text, photos, carousels and videos) and Reels are deleted along with their media. A Story can't be deleted: the whole request gets 400, and the Story disappears by itself 24 hours after publishing. For some seconds after publishing, Facebook refuses to delete a video or Reel, answering as if it were already gone. So while a post is under 5 minutes old, that answer gets 502: retry shortly. After that, a post Facebook reports as gone counts as deleted.
LinkedIn (LINKEDIN)The post is deleted. Right after publishing, LinkedIn may fail the deletion; the request gets 502, retry shortly.

Platform Settings

Each platform requires specific settings in the platformSettings JSON object. The type field is mandatory for all platforms and must match the platform name.

Important: Even if a platform doesn't have specific settings yet (like X/Twitter), you must still include the platformSettings field with the type value in your request.

Instagram

{
  "type": "INSTAGRAM",
  "publicationType": "FEED" | "REELS" | "STORY",
  "aiContent": false
}

aiContent (optional, default false) labels the post as AI-generated content on Instagram.

LinkedIn

{
  "type": "LINKEDIN",
  "visibility": "PUBLIC" | "CONNECTIONS" | "GROUP"
}

Threads

{
  "type": "THREADS",
  "topicTag": "optional topic tag"
}

TikTok

{
  "type": "TIK_TOK",
  "title": "Video title",
  "privacyLevel": "PUBLIC_TO_EVERYONE" | "FOLLOWER_OF_CREATOR" | "MUTUAL_FOLLOW_FRIENDS" | "SELF_ONLY",
  "disableDuet": false,
  "disableComments": false,
  "disableStitch": false,
  "brandContent": false,
  "brandOrganic": false,
  "aiContent": false,
  "autoAddMusic": false,
  "hasUsageConfirmation": true
}

type also accepts TIKTOK. aiContent (optional, default false) discloses AI-generated content and applies to video posts. autoAddMusic (optional, default false) lets TikTok add background music and applies to photo posts. TikTok decides per creator which privacyLevel values are available and whether duet/stitch/comments can be enabled; a value the creator can't use is rejected when the post is published.

YouTube

{
  "type": "YOUTUBE",
  "title": "Video title",
  "privacyStatus": "PUBLIC" | "UNLISTED" | "PRIVATE",
  "category": "FILM_ANIMATION" | "AUTOS_VEHICLES" | "MUSIC" | "PETS_ANIMALS" | "SPORTS" | "TRAVEL_EVENTS" | "GAMING" | "PEOPLE_BLOGS" | "COMEDY" | "ENTERTAINMENT" | "NEWS_POLITICS" | "HOWTO_STYLE" | "EDUCATION" | "SCIENCE_TECHNOLOGY"
}

Telegram

{
  "type": "TELEGRAM"
}

X (Twitter)

{
  "type": "TWITTER"
}

type also accepts X_TWITTER.

Bluesky

{
  "type": "BLUE_SKY"
}

type also accepts BLUESKY.

Facebook

{
  "type": "FACEBOOK",
  "publicationType": "FEED" | "REELS" | "STORY"
}

Pinterest

{
  "type": "PINTEREST",
  "title": "Pin title",
  "link": "https://example.com/landing-page",
  "altText": "Description of the image for screen readers",
  "boardSectionId": "5234567890123456789"
}

Only type is required; title (up to 100 characters), link (destination URL opened when the pin is clicked), altText and boardSectionId (pin into a section of the board) are optional. The board itself is set per post via chatId — get board IDs from Get Connected Chats with platform=PINTEREST.

WhatsApp

{
  "type": "WHATSAPP",
  "contactListId": 42,
  "templateName": "autumn_sale",
  "templateLanguage": "en",
  "headerParameter": "Autumn sale",
  "bodyParameters": { "1": "20%", "2": "Sunday" },
  "buttonParameters": { "0": "autumn-2026" }
}

contactListId, templateName and templateLanguage are required; the variables depend on the template. androidVideoCompat (REPACK or SEND_AS_IS) is needed for a header video whose index is at the end of the file. The sending number is set per post via chatId. See WhatsApp Broadcasts.

WhatsApp Broadcasts

A WhatsApp account in PostPulse is a WhatsApp Business Account (WABA). A post sends one of the account's approved message templates to a contact list, from one of the account's phone numbers. In GET /v1/accounts each connected WABA is a separate account with platform WHATSAPP: accountDisplayName is the WABA name.

Connecting: WhatsApp is connected on the PostPulse website (Accounts → WhatsApp) or with a link from the MCP server. The white-label Connect flow doesn't support it yet.

To send a broadcast:

  1. Pick the sending number with Get Connected Chats.
  2. Pick an approved template.
  3. Pick or create a contact list.
  4. Schedule the post, then follow its delivery.

Phone Numbers

GET /v1/accounts/{id}/chats returns the account's phone numbers. Pass the id of the number to send from as the post's chatId.

[
  {
    "id": "106540352242922",
    "title": "Acme Store +44 7700 900123",
    "type": "PHONE_NUMBER",
    "platform": "WHATSAPP"
  }
]

Templates

GET/v1/accounts/{id}/whatsapp/templates

Returns the account's approved message templates. Templates are created and approved in WhatsApp Manager, not in PostPulse; a new or changed template shows up here within 10 minutes.

  • parameterFormat — POSITIONAL (variables {{1}}, {{2}}, …) or NAMED (variables by name).
  • headerFormat — TEXT, IMAGE, VIDEO, or null without a header. headerParameterKey is the variable of a text header, or null.
  • bodyParameterKeys — the body variables in the order they appear.
  • buttons[].dynamicUrl — the URL of the button ends with a variable.
  • supported — false for a template PostPulse can't send, with the reason in unsupportedReason: authentication templates, document or location headers, carousels and other components besides header, body, footer and buttons, and buttons other than quick reply, URL and phone number.

Response Example

[
  {
    "name": "autumn_sale",
    "language": "en",
    "category": "MARKETING",
    "parameterFormat": "POSITIONAL",
    "headerFormat": "TEXT",
    "headerText": "Our {{1}} is on!",
    "headerParameterKey": "1",
    "bodyText": "Get {{1}} off until {{2}}",
    "bodyParameterKeys": ["1", "2"],
    "footerText": "Reply STOP to opt out",
    "buttons": [
      {
        "type": "URL",
        "text": "Shop",
        "url": "https://example.com/{{1}}",
        "phoneNumber": null,
        "dynamicUrl": true
      },
      {
        "type": "PHONE_NUMBER",
        "text": "Call",
        "url": null,
        "phoneNumber": "+447700900456",
        "dynamicUrl": false
      }
    ],
    "supported": true,
    "unsupportedReason": null
  }
]

Contact Lists

Contact lists belong to the account. A list holds up to 1,000 contacts, and a broadcast goes to one list.

GET/v1/accounts/{id}/whatsapp/contact-lists

Returns the account's contact lists.

POST/v1/accounts/{id}/whatsapp/contact-lists

Creates a list. Body: { "name": "Newsletter" }, 1–100 characters, unique in the account regardless of case. Returns the list.

PATCH/v1/accounts/{id}/whatsapp/contact-lists/{listId}

Renames the list. Same body as creating it. Returns the list.

DELETE/v1/accounts/{id}/whatsapp/contact-lists/{listId}

Deletes the list with its contacts. Returns 204 No Content. A scheduled broadcast to a deleted list fails.

Contact List

{
  "id": 42,
  "name": "Newsletter",
  "contactCount": 318,
  "createdTime": "2026-11-02T09:15:00.000000"
}

Contacts

GET/v1/accounts/{id}/whatsapp/contact-lists/{listId}/contacts

Returns a page of the list's contacts in the order they were added. Query parameters: page (from 0, default 0) and size (default 50). optedOut is true when the phone is on the account's opt-out list: broadcasts skip it.

Response Example

{
  "items": [
    {
      "id": 9001,
      "phone": "447700900123",
      "name": "Alex",
      "optedOut": false,
      "createdTime": "2026-11-02T09:16:00.000000"
    }
  ],
  "page": 0,
  "size": 50,
  "totalItems": 318,
  "totalPages": 7
}
POST/v1/accounts/{id}/whatsapp/contact-lists/{listId}/contacts

Adds up to 1,000 contacts per request. optInConfirmed must be true: it confirms that every contact agreed to receive WhatsApp messages from your business. name is optional, up to 255 characters.

Phones are in international format with the country code. Spaces, dashes, parentheses and a leading + or 00 are removed; what is left must be 7–15 digits. Phones are stored as digits without +. Invalid phones are returned in invalid, phones already in the list are counted in duplicates, and optedOut counts the added phones that are on the opt-out list. An upload that would take the list over 1,000 contacts adds nothing and returns 400.

Request Example

{
  "optInConfirmed": true,
  "contacts": [
    { "phone": "+44 7700 900123", "name": "Alex" },
    { "phone": "0044 7700 900124" },
    { "phone": "12345" }
  ]
}

Response Example

{
  "added": 2,
  "duplicates": 0,
  "optedOut": 0,
  "invalid": ["12345"]
}
DELETE/v1/accounts/{id}/whatsapp/contact-lists/{listId}/contacts/{contactId}

Removes the contact from the list. Returns 204 No Content. The phone stays on the opt-out list if it is there.

Schedule a Broadcast

Use POST /v1/posts (see Post Scheduling) with WhatsApp platformSettings:

{
  "scheduledTime": "2026-11-20T10:00:00Z",
  "isDraft": false,
  "publications": [
    {
      "socialMediaAccountId": 731,
      "platformSettings": {
        "type": "WHATSAPP",
        "contactListId": 42,
        "templateName": "autumn_sale",
        "templateLanguage": "en",
        "headerParameter": "Autumn sale",
        "bodyParameters": { "1": "20%", "2": "Sunday" },
        "buttonParameters": { "0": "autumn-2026" }
      },
      "posts": [
        { "chatId": "106540352242922" }
      ]
    }
  ]
}
  • A publication sends from one number to one list: it has exactly one post, whose chatId is the number. To send from two numbers or to two lists, add two publications.
  • content is not needed: PostPulse saves the template text (the text header and the body, with the variables filled in) as the post's content and replaces any content you send.
  • bodyParameters has a value for every key in the template's bodyParameterKeys. headerParameter is set only when the template has a headerParameterKey, up to 60 characters. buttonParameters maps the index of each button with dynamicUrl in buttons to the end of its URL. Values can't be empty or contain new lines, tabs or more than four spaces in a row.
  • A template with an IMAGE header needs exactly one image attachment (JPEG or PNG, up to 5 MB) in attachmentPaths; a VIDEO header needs one video (MP4 or 3GPP, up to 16 MB). Other templates take no attachments.
  • WhatsApp on Android can't play a header video whose index (the MP4 moov box) comes after its data. For such a video set androidVideoCompat: REPACK lets PostPulse move the index to the front without re-encoding before sending, SEND_AS_IS sends the file unchanged. Without it the request returns 400, and a video attached by URL ends the post in MEDIA_IMPORT_FAILED once it is imported. The field is returned with the post.
  • The list must have at least one contact that hasn't opted out.

If a rule is broken, or the template is no longer approved, the request returns 400 with the reason in error.

Sending and Result

At the scheduled time the post moves to IN_PROGRESS and the messages go out in batches of 200, about every two minutes: 1,000 contacts take about 15–25 minutes. Contacts on the opt-out list are skipped and don't count as failures. Once the messages are out and WhatsApp has reported their statuses, the post settles:

  • COMPLETED — WhatsApp accepted every message.
  • PARTIALLY_COMPLETED — WhatsApp accepted some of the messages. errorMessage says how many failed and why, for example 12 of 320 messages failed: Message undeliverable (131026), or why the broadcast stopped, and errorKind is the kind of that error.
  • FAILED — WhatsApp accepted no message.

The broadcast stops on an error that affects every message: the template was paused or deleted, the account's access was revoked, the phone number's display name is not approved, or the WhatsApp Business Account has a payment problem. The messages not sent yet are dropped, and the post is PARTIALLY_COMPLETED if some messages had gone out, FAILED otherwise.

WhatsApp charges message fees to the payment method of the WhatsApp Business Account in WhatsApp Manager. Replies of recipients don't appear in PostPulse. A recipient who replies STOP or UNSUBSCRIBE, or stops marketing messages in WhatsApp, is put on the account's opt-out list automatically.

Delivery Summary

GET/v1/accounts/{id}/whatsapp/posts/{postId}/delivery

Returns how the broadcast went: the number of messages in each status and the most frequent errors. postId is publications[].posts[].id from Get Post Details, not the posting schedule id. The counts keep changing while WhatsApp reports statuses, also after the post has settled.

  • pending, sending — not sent yet; accepted — accepted by WhatsApp, no status yet.
  • sent, delivered, read, failed — the last status WhatsApp reported.
  • optedOut — skipped, the phone is on the opt-out list; cancelled — not sent because the broadcast stopped.
  • topErrors — up to five WhatsApp errors of the failed messages, the most frequent first.

Response Example

{
  "total": 320,
  "pending": 0,
  "sending": 0,
  "accepted": 4,
  "sent": 21,
  "delivered": 180,
  "read": 96,
  "failed": 17,
  "optedOut": 2,
  "cancelled": 0,
  "topErrors": [
    { "code": 131026, "title": "Message undeliverable", "count": 12 },
    {
      "code": 131049,
      "title": "This message was not delivered to maintain healthy ecosystem engagement.",
      "count": 5
    }
  ]
}

Opt-outs

The opt-out list belongs to the account: an opted-out phone gets no broadcast of the account, from any of its numbers and to any of its lists. Mark a recipient who asked to stop in another way, for example in a chat or by email.

POST/v1/accounts/{id}/whatsapp/opt-outs

Body: { "phone": "+44 7700 900123" }, written as for contacts. Returns 204 No Content, also when the phone is already on the list.

DELETE/v1/accounts/{id}/whatsapp/opt-outs/{phone}

Takes the phone off the opt-out list, whoever put it there. Pass the phone as digits, for example 447700900123. Returns 204 No Content, also when the phone is not on the list.

Disconnecting the account deletes its contact lists and its opt-out list.

Data Models

Account Model

{
  "id": "number",
  "platform": "X_TWITTER" | "YOUTUBE" | "THREADS" | "TIKTOK" | "INSTAGRAM" | "LINKEDIN" | "BLUE_SKY" | "TELEGRAM" | "FACEBOOK" | "PINTEREST" | "WHATSAPP",
  "accountId": "string",
  "accountUsername": "string",
  "accountDisplayName": "string",
  "accountAvatarUrl": "string",
  "createdTime": "ISO 8601 datetime",
  "updatedTime": "ISO 8601 datetime"
}

Chat Model

{
  "id": "string",
  "title": "string",
  "type": "string",
  "platform": "string"
}

Media Upload Response

{
  "path": "string"
}

Publication Model

{
  "socialMediaAccountId": "number",
  "platformSettings": {
    "type": "platform_enum"
  },
  "posts": [
    {
      "content": "string",
      "chatId": "string (Telegram channel, Facebook Page, Pinterest board or WhatsApp phone number)",
      "attachmentPaths": ["string — storage key (from media upload) OR public URL"]
    }
  ]
}

Posting Schedule Created Response

Returned from POST /v1/posts.

{
  "id": "number",
  "overallStatus": "SCHEDULED | AWAITING_MEDIA | DRAFT",
  "scheduledTime": "ISO 8601 datetime (UTC)",
  "publications": [
    {
      "id": "number",
      "socialMediaAccountId": "number",
      "platformSettings": { "type": "platform_enum" },
      "posts": [
        {
          "id": "number",
          "chatId": "string (omitted when not set)",
          "content": "string",
          "attachmentPaths": ["string"],
          "thumbnail": "string — the post's thumbnailPath (omitted when not set)"
        }
      ]
    }
  ],
  "pendingImports": [                // Omitted when no public URLs are being imported
    {
      "postId": "number",
      "attachmentIndex": "number",
      "importTaskId": "number",
      "sourceUrl": "string",
      "state": "QUEUED | DOWNLOADING | VALIDATING | UPLOADING | READY | FAILED_TEMPORARY | FAILED_PERMANENT"
    }
  ]
}

Error Handling

PostPulse API uses standard HTTP status codes. Every error response from the API is a JSON object with an error string. A few errors also carry a machine-readable code, for example post_in_progress (409), oauth_state_expired (410), or platform_deletion_not_supported (400) and platform_deletion_failed (502) when deleting posts on the platforms. Branch on code when it is present and on the HTTP status otherwise, and show error to the user or log it.

Error Response Format

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "Social media account ID cannot be null; Platform settings cannot be null"
}

When several fields fail validation at once, their messages are joined with ; in a single error string, as in the example above.

Common Status Codes

HTTP StatusWhenExample error message
400Request validation failed, malformed JSON, or an invalid valuePlatform settings cannot be null
401Missing, expired or invalid access tokenUnauthorized
402Connecting a social media account that was already used by another PostPulse userSocial media account has already been used previously
403Token lacks the required scope, or the account is suspendedAccess denied
404Unknown route or resourcePosting schedule not found: 9821
409A conflicting operation is running: the post is being published or awaits its media import (code post_in_progress), or the user is being deletedPost 9821 is IN_PROGRESS; try again when it finishes
410OAuth state of a connect flow expired — start the flow againInvalid or expired OAuth state
413Uploaded file exceeds the size limitUploaded file is too large. Max size is 100MB.
500Unexpected server errorAn unexpected error occurred
502A platform failed to delete a post requested with deleteFromPlatform=true (code platform_deletion_failed); nothing was deleted in PostPulseFailed to delete the post on X, nothing was deleted in PostPulse and retrying is safe: X Error: Service Unavailable

Gateway Errors

Rate limiting (429) and a few infrastructure errors are returned by the API gateway in front of the service rather than by the API itself. Those responses use a message field instead of error:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
  "message": "Too Many Requests"
}

Retry 429 and 5xx responses with exponential backoff. Do not retry 4xx responses other than 429 without changing the request, except 409 with code post_in_progress: the same request succeeds once the post leaves that status.