Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Multi Upload Tool Analytics API
version: 1.0.0
summary: Publish and schedule video and photo posts to TikTok, YouTube, Instagram, Facebook, LinkedIn, Pinterest, Bluesky and Threads from one API.
description: 'REST API for the Multi Upload Tool platform.
Upload a video or photo once and publish it to one or many connected social accounts, immediately or on a schedule. The API also covers connected-account management, upload history, per-account daily limits, webhooks, teams, white-label connection links, short links and custom domains.
## Authentication
Every endpoint requires an API token sent in the `x-api-key` header. Tokens are created from the dashboard and look like `kmb_`.
```
x-api-key: kmb_0123456789abcdef...
```
## Permission model
A token carries **scopes**, chosen when it is created in the dashboard. `*` grants everything: it is what every token created before scopes existed holds, and what a token created without a list gets. Otherwise the token holds `resource:action` scopes — `posts:read`, `posts:write`, `posts:publish`, `accounts:read`, `accounts:write`, `analytics:read`, `pools:read`, `pools:write`, `webhooks:read`, `webhooks:write`, `team:read`, `team:write`, `links:read`, `links:write`. `write` includes `read`, and `posts:publish` includes `posts:write`. A token with `posts:write` but not `posts:publish` can create posts, but they are always held for approval. Each operation states what it needs in `x-required-scope`; a call without it returns `403` with `code: INSUFFICIENT_SCOPE` and `requiredScope`.
On top of scopes, **team scoping** applies.
- A token created against a team is permanently pinned to that team. It can only read and write that team''s resources, and it is revoked automatically if the user leaves the team.
- An unscoped token may target a team per-request with the `X-Team-ID` header. Membership is verified on every call.
- Inside a team, the member''s role (`OWNER`, `ADMIN`, `MEMBER`) gates privileged operations. Members cannot create webhooks; only owners and admins can invite or remove members; only an owner can remove an admin.
Treat an API token as a credential and store it accordingly; give each integration only the scopes it needs.
## Large media
A file part sent to `POST /upload` must stay under 100 MB, an edge limit on the request body rather than a platform one. For anything larger, call `POST /upload/presign` to get URLs that put the bytes straight into storage, then publish by passing the returned `bucketUrl` (preferred for large video) or `accessUrl` in the `video`, `photo` or `file` field.
## Rate limits
Limits are applied per IP and per endpoint group; exceeding one returns `429`. The tightest limits are on writes: 50 requests / 15 min for `POST /upload`, 20 requests / 15 min for `POST /upload/bulk` and for destructive operations. Reads are typically 100 requests / 5-15 min. A single IP may also present at most 10 distinct API tokens per hour.
## Errors
Errors return a JSON body of the form `{ "success": false, "error": "..." }`. Validation failures on `POST /upload` additionally return a per-field `errors` array.'
termsOfService: https://multi-upload-tool.com/terms
contact:
name: Multi Upload Tool support
url: https://multi-upload-tool.com/about
email: support@multi-upload-tool.com
servers:
- url: https://api.multi-upload-tool.com/api/v1
description: Production
security:
- apiKey: []
tags:
- name: Analytics
description: Views, likes, comments and shares collected nightly for every connected account.
paths:
/analytics/overview:
get:
tags:
- Analytics
summary: Global analytics across every connected account
description: 'Aggregates the collected metrics of all your active accounts.
The numbers come from Multi Upload Tool''s own store, filled by a nightly collector — they are not read from the platforms at request time. Check `lastRefreshedAt` before presenting them as live: a number without its reading time looks real time, and the first time it disagrees with the platform''s own app it reads as a bug rather than a collection that has not run yet.
A metric a platform does not report is counted as `0`, not omitted: YouTube exposes no shares, Bluesky no views, Pinterest no likes.'
operationId: getAnalyticsOverview
x-required-scope: analytics:read
parameters:
- name: tags
in: query
required: false
description: Comma-separated account tags. Only accounts carrying one of them are aggregated.
example: client-a,client-b
schema:
type: string
- name: source
in: query
required: false
description: Narrow `videos` (the post ranking) to `mut` (published through Multi Upload Tool) or `external` (posted directly on the platform). `all` or absent keeps every post. Totals and `summary` always cover every post.
schema:
type: string
enum:
- all
- mut
- external
- name: timezone
in: query
required: false
description: IANA zone the `postingInsights` weekday and hour buckets are read in, e.g. `Europe/Paris`. Defaults to `UTC`. An hour-of-day ranking read in the wrong zone is silently off by the whole offset, so send the user's own.
example: Europe/Paris
schema:
type: string
- $ref: '#/components/parameters/TeamId'
responses:
'200':
description: Aggregated analytics for the matching accounts.
content:
application/json:
schema:
type: object
properties:
success:
const: true
data:
$ref: '#/components/schemas/Analytics'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/analytics/{connectedAccountId}:
get:
tags:
- Analytics
summary: Analytics for one connected account
description: The same shape as the overview, restricted to a single account, plus that account's tags.
operationId: getAccountAnalytics
x-required-scope: analytics:read
parameters:
- name: connectedAccountId
in: path
required: true
description: Id of the connected account, as returned by `GET /accounts`.
schema:
type: string
- name: source
in: query
required: false
description: Narrow `videos` (the post ranking) to `mut` (published through Multi Upload Tool) or `external` (posted directly on the platform). `all` or absent keeps every post. Totals and `summary` always cover every post.
schema:
type: string
enum:
- all
- mut
- external
- name: timezone
in: query
required: false
description: IANA zone the `postingInsights` weekday and hour buckets are read in, e.g. `Europe/Paris`. Defaults to `UTC`. An hour-of-day ranking read in the wrong zone is silently off by the whole offset, so send the user's own.
example: Europe/Paris
schema:
type: string
- $ref: '#/components/parameters/TeamId'
responses:
'200':
description: Analytics for the account.
content:
application/json:
schema:
type: object
properties:
success:
const: true
data:
$ref: '#/components/schemas/Analytics'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
/analytics/{connectedAccountId}/sync:
post:
tags:
- Analytics
summary: Refresh one account now instead of waiting for the nightly pass
description: 'Reads the platform inside the request, writes the snapshots, then returns the refreshed analytics. Covers up to the 1000 most recent posts.
This is a write: it rotates OAuth tokens, stores snapshots and consumes the platform''s rate limit, so it needs manage access to the account, not read access. Use it when someone has just published from the platform''s own app — the collector otherwise runs once a night.'
operationId: syncAccountAnalytics
x-required-scope: analytics:read
parameters:
- name: connectedAccountId
in: path
required: true
description: Id of the connected account, as returned by `GET /accounts`.
schema:
type: string
- name: timezone
in: query
required: false
description: IANA zone the `postingInsights` weekday and hour buckets are read in, e.g. `Europe/Paris`. Defaults to `UTC`. An hour-of-day ranking read in the wrong zone is silently off by the whole offset, so send the user's own.
example: Europe/Paris
schema:
type: string
- $ref: '#/components/parameters/TeamId'
responses:
'200':
description: Analytics as of the sync that just ran.
content:
application/json:
schema:
type: object
properties:
success:
const: true
data:
$ref: '#/components/schemas/Analytics'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
/analytics/{connectedAccountId}/linkedin/comments:
get:
tags:
- Analytics
summary: List the commenters on a LinkedIn post
description: 'LinkedIn only — any other platform returns `400`. Read-only: there is no endpoint to reply to a comment.'
operationId: getLinkedInPostComments
x-required-scope: analytics:read
parameters:
- name: connectedAccountId
in: path
required: true
description: Id of the connected account, as returned by `GET /accounts`.
schema:
type: string
- name: postId
in: query
required: true
description: The LinkedIn post URN, as returned in the upload result.
example: urn:li:share:7212345678901234567
schema:
type: string
- $ref: '#/components/parameters/TeamId'
responses:
'200':
description: The comments on the post.
content:
application/json:
schema:
type: object
properties:
success:
const: true
data:
type: object
properties:
comments:
type: array
items:
type: object
additionalProperties: true
'400':
$ref: '#/components/responses/ValidationError'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
components:
responses:
NotFound:
description: No such resource, or it does not belong to the caller.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
ValidationError:
description: The request body or parameters were rejected.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/FieldValidationError'
Unauthorized:
description: The API key is missing, invalid, revoked or expired.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Forbidden:
description: The token is valid but not permitted to act on this resource, usually because of team scoping or the caller's team role.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
PostingBucket:
type: object
description: One weekday or one hour of day, averaged over the posts that landed in it.
properties:
weekday:
type: integer
minimum: 0
maximum: 6
description: 0 = Sunday, following Postgres' `dow`. Present on `byWeekday` and `bestDay`.
hour:
type: integer
minimum: 0
maximum: 23
description: Hour of day in the requested timezone. Present on `byHour` and `bestHours`.
posts:
type: integer
avgViews:
type: integer
ranked:
type: boolean
description: 'False when `posts` is under `minSamples`. The bucket keeps its average — it is worth showing — but it is never eligible to win. One lucky post is a coincidence, not a slot, and it is the loudest one: a single viral video gives its bucket an average no honest bucket can beat.'
Analytics:
type: object
description: What the collector holds for the accounts in scope. Every metric is a running total read from the platform, not a per-day figure.
properties:
overview:
type: object
properties:
totalViews:
type: integer
totalLikes:
type: integer
totalComments:
type: integer
totalShares:
type: integer
videoCount:
type: integer
accountCount:
type: integer
bestAccount:
type:
- object
- 'null'
properties:
name:
type: string
platform:
$ref: '#/components/schemas/Platform'
views:
type: integer
videos:
type: array
description: 'One row per tracked post, with its metrics, an `isTrending` flag and `source`: `mut` if it was published through Multi Upload Tool, `external` if it was posted directly on the platform.'
items:
type: object
additionalProperties: true
bestPerforming:
type:
- object
- 'null'
properties:
mostViewed:
type: object
additionalProperties: true
mostEngaging:
type: object
additionalProperties: true
topHashtags:
type: array
items:
type: object
additionalProperties: true
postingInsights:
$ref: '#/components/schemas/PostingInsights'
dailyHistory:
type: array
items:
type: object
additionalProperties: true
platformHistory:
type: array
items:
type: object
additionalProperties: true
summary:
type: object
description: The last 30 days against the 30 before. `null` means not measured, never zero.
properties:
windowDays:
type: integer
const: 30
views:
type: object
description: Views gained in each period, summed from the daily series (gaps spread evenly, as on the chart). `measuredDays` says how many days of each period had data.
properties:
current:
type:
- integer
- 'null'
previous:
type:
- integer
- 'null'
change:
type:
- integer
- 'null'
changePct:
type:
- number
- 'null'
measuredDays:
type: object
properties:
current:
type: integer
previous:
type: integer
followers:
type: object
description: '`total` = latest follower count summed over accounts. `change` only counts accounts that were also measured 30 days ago, so it stays `null` for the first 30 days of history.'
properties:
total:
type:
- integer
- 'null'
previous:
type:
- integer
- 'null'
change:
type:
- integer
- 'null'
changePct:
type:
- number
- 'null'
postsPublished:
type: object
properties:
current:
type: integer
previous:
type: integer
change:
type: integer
followerHistory:
type: array
description: 'One point per day over the window: the sum of each account''s last known follower count. Days before the first reading are omitted.'
items:
type: object
properties:
date:
type: string
format: date
followers:
type: integer
accountTags:
type: array
description: Only on the single-account route.
items:
type: string
lastRefreshedAt:
type:
- string
- 'null'
format: date-time
description: When the collector last read the platform. Show it next to the numbers.
neverSynced:
type: boolean
description: '`true` means nothing has ever been collected, as opposed to collected and empty. The two deserve different messages: "connect and wait for tonight" is not "you have no posts yet".'
syncErrors:
type: array
description: Accounts whose last collection failed. A failing account never stops the others.
items:
type: object
properties:
accountName:
type: string
platform:
$ref: '#/components/schemas/Platform'
error:
type: string
FieldValidationError:
type: object
required:
- success
- message
- errors
properties:
success:
const: false
message:
const: Validation Error
errors:
type: array
items:
type: object
properties:
path:
type: string
message:
type: string
summary:
type: string
PostingInsights:
type: object
description: When this account has published, and what those slots averaged. Derived from the posts already collected, so it says nothing until there are enough of them.
properties:
timezone:
type: string
description: The zone the buckets were read in — whatever you asked for, or `UTC`.
minSamples:
type: integer
description: Posts a bucket needs before it can be ranked.
byWeekday:
type: array
description: Always 7 entries, Sunday first, including the days with nothing in them.
items:
$ref: '#/components/schemas/PostingBucket'
byHour:
type: array
description: Always 24 entries, 00:00 first.
items:
$ref: '#/components/schemas/PostingBucket'
bestDay:
oneOf:
- $ref: '#/components/schemas/PostingBucket'
- type: 'null'
bestHours:
type: array
description: Up to 5 hours, best first. Ranked buckets only.
items:
$ref: '#/components/schemas/PostingBucket'
sampleSize:
type: integer
description: Posts carrying a publication date, i.e. what the buckets were built from.
Platform:
type: string
description: A supported social platform.
enum:
- tiktok
- youtube
- instagram
- facebook
- linkedin
- pinterest
- bluesky
- threads
- x
Error:
type: object
required:
- success
- error
properties:
success:
const: false
error:
type: string
description: Human-readable failure reason.
statusCode:
type: integer
parameters:
TeamId:
name: X-Team-ID
in: header
required: false
description: Act inside this team. Ignored when the token is already pinned to a team; membership is verified on every request.
schema:
type: integer
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: 'API token created from the dashboard, in the form `kmb_<64 hex characters>`.
A token carries a list of scopes, chosen when it is created: `*` (everything — every token created before scopes existed, and any token created without a list) or `resource:action` scopes such as `posts:read` or `analytics:read`. Each operation states the scope it needs in `x-required-scope`; a token without it gets `403` with `code: INSUFFICIENT_SCOPE`. A token with `posts:write` but not `posts:publish` can create posts, which are always held for approval. On top of scopes, team scoping applies: baked into the token at creation time or requested per-call with `X-Team-ID`. Store it as you would a password.'
externalDocs:
description: Full API documentation
url: https://docs.multi-upload-tool.com/api-reference