Skip to Content
API ReferenceUpload Pools

Upload Pools API

Upload Pools let you define recurring time slots and queue videos that are dispatched automatically. This page documents all public API endpoints for managing pools and their queues.

Base URL

https://api.multi-upload-tool.com/api/v1

Authentication

All requests require an API token:

x-api-key: YOUR_API_TOKEN

List Pools

Retrieve all pools belonging to your account (or team).

Endpoint

GET /pools

Example Request

curl https://api.multi-upload-tool.com/api/v1/pools \
  -H "x-api-key: YOUR_API_TOKEN"

Example Response

{
  "success": true,
  "pools": [
    {
      "id": 1,
      "name": "Daily TikTok",
      "timezone": "Europe/Paris",
      "isActive": true,
      "slots": [
        {
          "id": 10,
          "time": "08:00",
          "days": [1, 2, 3, 4, 5],
          "accountIds": ["42"]
        },
        {
          "id": 11,
          "time": "18:00",
          "days": [1, 2, 3, 4, 5],
          "accountIds": ["42"]
        }
      ],
      "_count": { "items": 14 }
    }
  ]
}

Get Pool

Retrieve a single pool by ID.

Endpoint

GET /pools/:id

Path Parameters

ParameterTypeDescription
idstringPool ID

Example Request

curl https://api.multi-upload-tool.com/api/v1/pools/abc123 \
  -H "x-api-key: YOUR_API_TOKEN"

Check Capacity

Preview how many days your current queue will last and whether adding more videos would exceed plan limits.

Endpoint

GET /pools/:id/capacity?count=N

Query Parameters

ParameterTypeRequiredDescription
countnumberNoNumber of videos you’re about to add. Default 1.

Example Request

curl "https://api.multi-upload-tool.com/api/v1/pools/1/capacity?count=20" \
  -H "x-api-key: YOUR_API_TOKEN"

Example Response

{
  "success": true,
  "queued": 5,
  "slotsPerDay": 2,
  "daysOfContent": 2,
  "afterAdd": {
    "queued": 25,
    "daysOfContent": 12
  },
  "warning": null
}

If adding the requested videos would exceed your plan quota, a warning string is returned. You should display this to the user before confirming the upload.

Add a video or photo carousel to a pool’s queue. Items are dispatched in the order they were added (FIFO).

Endpoint

POST /pools/:id/videos

Content-Type

multipart/form-data

The API works the same way as POST /upload: you send the file(s) directly and the API uploads them to storage internally. Only the resulting storage URLs are kept.

Body Parameters

ParameterTypeRequiredDescription
videoFileOne ofA single video file (mp4, webm, mov…).
photoFile | File[]One ofOne or more images for a photo carousel. Repeat the field for multiple images.
titlestringYesPost title / caption.
descriptionstringNoAdditional description.
metadatastringNoJSON-encoded platform-specific options (see below).

Provide either video or photo — not both. For carousels, all images are uploaded and the extra URLs are automatically stored as childrenKeys for dispatch.

The metadata field

Pass a JSON string with platform-specific options applied at dispatch time:

{
  "privacy_level": "PUBLIC_TO_EVERYONE",
  "disable_comment": false,
  "is_aigc": false
}

Refer to each platform’s upload documentation for available options.

Example — single video

curl -X POST https://api.multi-upload-tool.com/api/v1/pools/1/videos \
  -H "x-api-key: YOUR_API_TOKEN" \
  -F "video=@/path/to/video.mp4" \
  -F "title=My awesome video #fyp" \
  -F "description=Check this out" \
  -F 'metadata={"privacy_level":"PUBLIC_TO_EVERYONE","disable_comment":false}'

Example — photo carousel (3 images)

curl -X POST https://api.multi-upload-tool.com/api/v1/pools/1/videos \
  -H "x-api-key: YOUR_API_TOKEN" \
  -F "photo=@/path/to/image1.jpg" \
  -F "photo=@/path/to/image2.jpg" \
  -F "photo=@/path/to/image3.jpg" \
  -F "title=My carousel post" \
  -F "description=Swipe through!"

Example Response

{
  "success": true,
  "added": 1,
  "items": [
    { "id": 101, "position": 6, "status": "queued", "title": "My carousel post" }
  ]
}

List Queue Items

Retrieve the list of videos in a pool’s queue.

Endpoint

GET /pools/:id/videos

Query Parameters

ParameterTypeRequiredDescription
statusstringNoFilter by status: queued, dispatched, skipped.

Example Request

curl "https://api.multi-upload-tool.com/api/v1/pools/1/videos?status=queued" \
  -H "x-api-key: YOUR_API_TOKEN"

Example Response

{
  "success": true,
  "items": [
    {
      "id": 101,
      "position": 1,
      "status": "queued",
      "title": "Video 1",
      "description": "Check this out",
      "createdAt": "2026-03-15T10:00:00Z"
    }
  ]
}

Remove Queue Item

Remove a video from the queue. Only queued items can be removed — dispatched items cannot be undone.

Endpoint

DELETE /pools/:id/videos/:itemId

Path Parameters

ParameterTypeDescription
idstringPool ID
itemIdnumberQueue item ID

Example Request

curl -X DELETE https://api.multi-upload-tool.com/api/v1/pools/1/videos/101 \
  -H "x-api-key: YOUR_API_TOKEN"

Example Response

{ "success": true }

Clear Queue

Remove all queued items from a pool’s queue. Dispatched and skipped items are not affected.

Endpoint

DELETE /pools/:id/videos

Path Parameters

ParameterTypeDescription
idstringPool ID

Example Request

curl -X DELETE https://api.multi-upload-tool.com/api/v1/pools/abc123/videos \
  -H "x-api-key: YOUR_API_TOKEN"

Example Response

{
  "success": true,
  "removed": 5
}

Bulk Add Videos (JSON)

Add multiple videos to a pool’s queue using URLs (no file upload). Useful for adding pre-uploaded or external videos.

Endpoint

POST /pools/:id/videos/bulk

Content-Type

application/json

Body Parameters

ParameterTypeRequiredDescription
itemsarrayYesArray of video objects (min 1, max 50).
items[].titlestringYesPost title / caption.
items[].videoUrlstringYesURL of the video file.
items[].descriptionstringNoAdditional description.
items[].metadatastringNoJSON-encoded platform-specific options.

Example Request

curl -X POST https://api.multi-upload-tool.com/api/v1/pools/abc123/videos/bulk \
  -H "x-api-key: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "title": "Video 1",
        "videoUrl": "https://storage.example.com/video1.mp4",
        "metadata": "{\"privacy_level\":\"PUBLIC_TO_EVERYONE\"}"
      },
      {
        "title": "Video 2",
        "videoUrl": "https://storage.example.com/video2.mp4"
      }
    ]
  }'

Example Response

{
  "success": true,
  "added": 2,
  "items": [
    { "id": 102, "position": 7, "status": "queued", "title": "Video 1" },
    { "id": 103, "position": 8, "status": "queued", "title": "Video 2" }
  ]
}

Item status reference

StatusDescription
queuedWaiting for the next available slot.
dispatchedSuccessfully posted to the social platform.
skippedSlot fired but item was not posted (quota, platform error, etc.).

Error reference

HTTPCodeDescription
401UNAUTHORIZEDMissing or invalid API token.
403FORBIDDENPool belongs to a different user/team.
404NOT_FOUNDPool or item not found.
429RATE_LIMITToo many requests.
400VALIDATIONInvalid body parameters — details in errors[].
BlueskyShort Links