Post sets

A post set is one slot on your schedule: a date, a status, and one post per social network it targets. Scheduling the same content to Instagram and X is one post set with two posts, each carrying its own caption, media, and network-specific fields.

A post set moves through four statuses:

Creating or updating a set as DRAFT needs the post-sets:write scope. Anything that leaves a set SCHEDULED additionally needs post-sets:publish, see authentication.

List post sets

GET /v1/post-sets

curl "https://app.pallyy.com/api/v1/post-sets?socialSetId=SET_ID&filters[status][]=SCHEDULED&sort[scheduledAt]=ASC" \
  -H "Authorization: Bearer pallyy_your_api_key"

Get a post set

GET /v1/post-sets/{id}

Returns the full post set, or a 404 if it does not exist or is outside the key's access.

Any post set can also be opened in Pallyy's calendar with a link carrying its social set in the set query parameter and its id in post, handy for linking from your own tools back to the app:

https://app.pallyy.com/dashboard/scheduling/calendar/month?set=<socialSetId>&post=<postSetId>

Create a post set

POST /v1/post-sets

Requires post-sets:write, plus post-sets:publish when status is SCHEDULED. Returns the created set with a 201.

Approvals

approval places the set in Pallyy's approval workflow, the same one your team uses in the app:

The approval state is independent of status: it tracks review, while status decides whether the set publishes. Any value other than NONE requires approvals on your plan; otherwise the request fails with a 403.

Repeats

The repeat option turns one request into a repeating series. The first occurrence publishes at scheduledAt, and each following occurrence is spaced one interval apart (DAY, WEEK, MONTH, or YEAR), for a total of occurrences post sets, between 2 and 50. The series is materialized immediately: one post set per occurrence, all sharing the same seriesId, and every occurrence counts against your plan's monthly post limit.

Once a set belongs to a series, its repeat rule can no longer be changed via the API, matching the in-app editor: updating it returns a 400 with post-set:repeat_not_updatable. You can still edit each occurrence individually, since each one is a regular post set. Repeats are only available on plans that include them, otherwise the request fails with post-set:repeats_not_available.

Post objects

Every post shares these fields:

Media items reference your media library by id, with optional per-item metadata:

{
  "mediaLibraryId": "665f1c2ab7e2a4d1f0a1b2c5",
  "altText": "A latte on a wooden table"
}

Besides altText, items accept title, description, link, and tags (see below) where the network supports them. The referenced media must belong to the same social set as the post set. To get media into the library via the API, see media uploads.

Media tags

tags places account tags on an image, the way Instagram lets you tag people in a photo. Each tag carries the handle to tag and where on the image it sits:

{
  "mediaLibraryId": "665f1c2ab7e2a4d1f0a1b2c5",
  "tags": [
    { "x": 0.25, "y": 0.4, "text": "pallyy" }
  ]
}

Positions are fractions of the image size, so the same tag lands on the same spot regardless of the image's dimensions.

Network-specific fields

richCaption on Facebook and LinkedIn is the caption as an array of text segments. Pass the caption as a single-item array: ["Your caption"].

Example

curl https://app.pallyy.com/api/v1/post-sets \
  -X POST \
  -H "Authorization: Bearer pallyy_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "socialSetId": "665f1c2ab7e2a4d1f0a1b2c3",
    "scheduledAt": "2026-09-01T09:30:00.000Z",
    "status": "SCHEDULED",
    "posts": [
      {
        "accountType": "INSTAGRAM",
        "type": "IMAGE",
        "caption": "Fresh from the roastery.",
        "collaborators": [],
        "media": [{ "mediaLibraryId": "665f1c2ab7e2a4d1f0a1b2c5", "altText": "A latte on a wooden table" }]
      },
      {
        "accountType": "TWITTER",
        "caption": "Fresh from the roastery.",
        "media": [{ "mediaLibraryId": "665f1c2ab7e2a4d1f0a1b2c5" }]
      }
    ]
  }'

Validation and plan limits

Drafts are validated loosely, so you can park incomplete content. Scheduling validates every post against its network's rules, and failures return post-set:invalid_posts with one entry per problem, see errors.

Your plan is enforced on every write: the monthly post limit (post-set:monthly_posts_exceeded), carousels (post-set:carousels_not_available), videos (post-set:videos_not_available), repeats (post-set:repeats_not_available), and approvals all return a 403 when unavailable.

Update a post set

PATCH /v1/post-sets/{id}

Requires post-sets:write, plus post-sets:publish when the set ends up SCHEDULED, whether because you set the status or because it already was. The update is partial: omitted fields keep their saved values.

When posts is provided, it describes the complete new list:

• A post with an id keeps that existing post's identity. Its accountType cannot change.
• A post without an id is created new.
• Existing posts that are not referenced are removed.
• Each post's media works the same way: { "id": "..." } keeps an existing media item of the set (it may move between posts), { "mediaLibraryId": "..." } adds a new one from the library, and unreferenced media are removed.
• Each post or media id may be referenced at most once, otherwise the request fails with post-set:duplicate_references.

Sets that are PUBLISHING or PUBLISHED are read-only and return a 412 with post-set:read_only.

The post set object

Once a set has published, each post carries a result:

{
  "result": {
    "status": "POSTED",
    "providerId": "18123456789",
    "permalink": "https://www.instagram.com/p/..."
  }
}

Failed posts have "status": "FAILED" with an optional message and one of these reason codes: