---
title: "Group uploads into a carousel"
method: POST
path: "/uploads/carousel-group"
tags: ["Uploads"]
---

# Group uploads into a carousel

`POST /uploads/carousel-group`

## Request

- Base URL: `https://api.shortsync.app/v1`
- URL: `https://api.shortsync.app/v1/uploads/carousel-group`
- Auth: `bearerAuth` (a scheme the document does not define)

Groups an ordered list of already-uploaded items into a single carousel
post. Each item must have been uploaded via `POST /uploads` and finalized
(bytes landed in S3) before calling this endpoint.

Creates a carousel parent with `content_type: "carousel"` and returns a
new `upload_id` that you pass to `POST /posts` to publish.

The global item limit is 50. Per-platform limits are enforced at publish
time: Instagram (10), TikTok (35, images only), Facebook (30, images
only), LinkedIn (20, images only), Threads (10), X (4, images only),
Bluesky (4, images only), Pinterest (5, images only), Telegram (10),
Mastodon (4, images only), Discord (10, images and video, 10 MB
total per post), Tumblr (10, images and one video max), Pixelfed (20, images
and video; the connected server's album cap applies, default 4).
Google Business Profile doesn't support carousels (one photo per post).

## Request body

- object
  - `child_upload_ids` string[], required: Ordered list of `upload_id` values (from `POST /uploads`) to group. Position 0 is the cover by default.
  - `cover_index` integer: 0-based index within `child_upload_ids` to use as the carousel cover image. Defaults to 0 (first item).

## Response `201`

Carousel created.

- object
  - `upload_id` string: The carousel's `upload_id`. Pass this to `POST /posts` as the `upload_id` to publish the carousel.
  - `child_count` integer
  - `content_type` 'carousel'
  - `cover_index` integer
  - `has_video` boolean
  - `has_image` boolean

## Other responses

- `400`: Request body or parameters failed validation.
- `401`: Missing, malformed, or revoked token.
- `403`: Token is valid but cannot access this resource. Common cases: - `INSUFFICIENT_SCOPE` - token lacks the required scope. - `WORKSPACE_NOT_ALLOWED` - account token is allowlisted to other workspaces.
- `404`: One or more upload IDs not found or not finalized.
- `429`: Per-key sliding-window rate limit (60 req/min), per-org monthly request quota, or per-user upload cap was hit. `RATE_LIMIT_EXCEEDED` carries the window headers; `QUOTA_EXCEEDED` carries `details.quota` (which counter), `used`, `limit`, `resets_at`, and `upgrade_url`. `UPLOAD_QUOTA_EXCEEDED` (Free tier on `POST /posts` only) carries the same shape plus `details.remaining`.

---

[API](https://skmtc.dev/shortsync/apis/shortsync-api.md) · [All operations](https://skmtc.dev/shortsync/apis/shortsync-api/llms.txt) · [OpenAPI document](https://skmtc.dev/shortsync/apis/shortsync-api/revisions/71fdaef1e400?raw)