{ "openapi": "3.1.0", "info": { "version": "1.0.0", "title": "Shortimize API", "description": "Shortimize API provides endpoints for managing and tracking social media accounts and videos.\n\n## Rate Limits\n\nAll API endpoints are rate limited per user. Rate limits vary by plan and endpoint:\n\n| Plan | Standard endpoints | Tracking & History endpoints |\n|------|-------------------|-----------------------------|\n| **Limited (trial)** | 5 requests per minute | 5 requests per minute |\n| **Basic** | 15 requests per minute | 15 requests per minute |\n| **Premium** | 30 requests per minute | 120 requests per minute |\n\nWhen rate limited, you'll receive a `429 Too Many Requests` response. Check the `RateLimit-*` headers for limit status.\n\nWhen you exceed a limit you get `429` with a **`Retry-After`** header giving the whole number of seconds to wait. That is the time left in the current window rather than a fixed minute, so a request rejected near the end of a window gets a short wait. The same number is in `RateLimit-Reset`, and `RateLimit-Limit` / `RateLimit-Remaining` show your allowance and what is left of it. Limits are per organisation, so all API keys in one organisation share them.\n" }, "servers": [ { "url": "https://api.shortimize.com", "description": "Production" } ], "paths": { "/accounts": { "get": { "tags": [ "Account Management" ], "operationId": "get_all_accounts", "summary": "Get All Accounts", "description": "**All tiers** — Limited/Basic: 1 result with masked metrics. Premium: full access.\n\nRetrieves all accounts linked to your organisation in Shortimize. This endpoint provides a comprehensive list of all tracked social media accounts, including key metrics and performance indicators.\n\nUse this to get an overview of all accounts under your organization's management.\n\n**Rate Limit:** 5 (limited) / 15 (basic) / 30 (premium) requests per minute", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "Bearer token for authentication", "schema": { "type": "string" }, "example": "Bearer YOUR_KEY_HERE" }, { "name": "collections", "in": "query", "description": "Optional comma-separated list of collections to filter accounts (e.g. collection1,collection2,collection3)\n\nMake sure to URL encode them before sending.", "required": false, "schema": { "type": "string" }, "example": "competitor-x,water%20app" }, { "in": "query", "name": "paginated", "schema": { "type": "boolean", "default": false }, "description": "Set to true to receive paginated response with {data, pagination} format instead of raw array" }, { "in": "query", "name": "page", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "Page number for pagination (requires paginated=true)" }, { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 5000, "minimum": 1, "maximum": 5000 }, "description": "Number of items to return per page" }, { "in": "query", "name": "order_by", "schema": { "type": "string", "default": "checked_at" }, "description": "Field to order results by" }, { "in": "query", "name": "order_direction", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] }, "description": "Direction of ordering (ascending or descending)" } ], "responses": { "200": { "description": "Successful response with a list of accounts and their detailed information", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "organisation_id": { "type": "string", "format": "uuid", "description": "Unique identifier for your organization" }, "account_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the account" }, "account_link": { "type": "string", "format": "uri", "description": "URL of the social media account" }, "username": { "type": "string", "description": "Username of the account. May carry a '~' disambiguation suffix ('handle~') for Facebook accounts: Facebook permits two genuinely different profiles to share one display handle, and the suffix keeps their stats separate. Treat the full string as canonical in API calls; strip everything from '~' onward for display." }, "platform": { "type": "string", "enum": [ "instagram", "tiktok", "youtube" ], "description": "Social media platform of the account" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the account was added to Shortimize" }, "checked_at": { "type": "string", "format": "date-time", "description": "Timestamp of the last data update" }, "removed": { "type": "boolean", "description": "Indicates if the account has been removed from tracking" }, "private": { "type": "boolean", "description": "Indicates if the account is private" }, "empty": { "type": "boolean", "description": "Indicates if the account has no content" }, "bio": { "type": "string", "description": "The bio of the account from the respective platform" }, "link": { "type": "string", "description": "The primary link of the account from the respective platform" }, "latest_followers_count": { "type": [ "integer", "null" ], "description": "Most recent follower count, null if not available" }, "latest_following_count": { "type": [ "integer", "null" ], "description": "Most recent following count, null if not available" }, "tracking_type": { "type": "string", "description": "Type of tracking applied to this account" }, "mean_views": { "type": "number", "description": "Average number of views across tracked videos" }, "most_viewed": { "type": "integer", "description": "Highest number of views for a single video" }, "median_views": { "type": "number", "description": "Median number of views across tracked videos" }, "median_views_non_zero": { "type": "number", "description": "Median number of views across tracked videos (videos with greater than 0 views)" }, "median_likes": { "type": "number", "description": "Median number of likes across tracked videos" }, "percent_outperform_10x": { "type": "number", "description": "Percentage of videos outperforming by 10x" }, "percent_outperform_25x": { "type": "number", "description": "Percentage of videos outperforming by 25x" }, "last_uploaded_at": { "type": "string", "format": "date", "description": "Date of the last uploaded video" }, "total_videos_tracked": { "type": "integer", "description": "Total number of videos being tracked" }, "total_views": { "type": "integer", "description": "Total views across all tracked videos" }, "total_likes": { "type": "integer", "description": "Total likes across all tracked videos" }, "total_comments": { "type": "integer", "description": "Total comments across all tracked videos" }, "total_bookmarks": { "type": "integer", "description": "Total bookmarks across all tracked videos" }, "total_shares": { "type": "integer", "description": "Total shares across all tracked videos" }, "total_engagement": { "type": "integer", "description": "Total engagement across all tracked videos (likes + comments + shares + bookmarks)" }, "label_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Array of collection/label IDs associated with the account" }, "label_names": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Array of collection/label names associated with the account" }, "history_array": { "type": "array", "items": { "type": "object", "properties": { "likes": { "type": "integer", "description": "Total likes for the day" }, "views": { "type": "integer", "description": "Total views for the day" }, "shares": { "type": "integer", "description": "Total shares for the day" }, "comments": { "type": "integer", "description": "Total comments for the day" }, "bookmarks": { "type": "integer", "description": "Total bookmarks for the day" }, "engagement": { "type": "integer", "description": "Total engagement for the day (likes + comments + shares + bookmarks)" }, "created_at": { "type": "string", "format": "date", "description": "Date of the data point" } } }, "description": "Historical data array, typically containing the last 30 days of data - will be deprecated soon into it's own endpoint." } } } } } } }, "401": { "description": "Unauthorized - Invalid API key" }, "429": { "description": "Rate limit exceeded. Wait the number of seconds given in the Retry-After header, then retry.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Whole seconds to wait before retrying. This is the time left in the current window, not a fixed minute, so a request rejected near the end of a window gets a short wait. Always at least 1." }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed per minute for this API key." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets. Same value as Retry-After." } } } } }, "post": { "tags": [ "Account Management" ], "summary": "Track Account", "description": "Track an account and link it to your organisation in Shortimize.\n\nA direct URL to the account on Shortimize will be returned.\n\n**Rate Limit:** 5 (limited) / 15 (basic) / 120 (premium) requests per minute", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "Bearer token for authentication", "schema": { "type": "string" }, "example": "Bearer YOUR_KEY_HERE" }, { "name": "content-type", "in": "header", "required": true, "description": "should be set to `application/json`", "schema": { "type": "string", "enum": [ "application/json" ] } } ], "operationId": "track_account", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "link" ], "properties": { "link": { "type": "string", "format": "uri", "description": "The URL of the account to start tracked" }, "collection_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Optional list of collection UUIDs to associate with the account" }, "collection_names": { "type": "array", "items": { "type": "string" }, "description": "Optional list of collection names to create and associate with the account" }, "tracking_type": { "type": "string", "description": "Optional tracking type to use (e.g., 'latest_30', 'latest_200'). If left empty, will use the organisation default." } } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "properties": { "error": { "type": "string", "description": "Only present when the account is already being tracked.", "example": "This account already tracked in the organisation." }, "directUrl": { "type": "string", "format": "uri", "description": "Shortened URL to the account on the dashboard", "example": "https://app.shortimize.com/accounts//" }, "accountId": { "type": "string", "description": "A UUID for the account in our system", "example": "xxxxxx-xxxxxx-xxxxxx-xxxxxx-xxxxxx" } } } } } } }, "400": { "description": "Bad request - missing or invalid link", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Detailed error message explaining the validation failure", "example": "Invalid account link. Please enter a valid full TikTok, Instagram, or YouTube account URL." } } } } } }, "500": { "description": "Internal server error" } } }, "delete": { "tags": [ "Account Management" ], "summary": "Stop Tracking Account", "description": "Stop tracking an account linked to your organisation. \n\nUse this to pause tracking when you want to stop monitoring an account's performance or remove it from your active tracking portfolio. This is useful for accounts that are no longer relevant to your campaign or when you need to manage your tracking quota.\n\n**Rate Limit:** 5 (limited) / 15 (basic) / 120 (premium) requests per minute", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "Bearer token for authentication", "schema": { "type": "string" }, "example": "Bearer YOUR_KEY_HERE" } ], "operationId": "stop_tracking_account", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "The ID (UUID) or URL of the account to stop tracking" } } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message confirming the operation", "example": "Successfully stopped tracking account." } } } } } }, "400": { "description": "Bad request - missing or invalid account ID" }, "500": { "description": "Internal server error" } } } }, "/accounts/bulk": { "post": { "tags": [ "Account Management" ], "summary": "Bulk Track Accounts", "description": "Start tracking up to 500 accounts in one request.\n\nSend a list of links in `links`. Each one is handled on its own, so a bad link does not stop the rest - you get one entry per link back in `results`, saying whether it was newly tracked, already tracked, or failed.\n\n**Reading the response**\n- `summary` gives you the counts at a glance.\n- Each entry in `results` has a `status`: `tracked`, `already_tracked`, or `failed`.\n- A failed entry also has a plain-language `error`, a stable `code`, and `retryable`. If `retryable` is true, sending that link again will usually work - resend just those links, not the whole batch.\n- `warnings` holds anything worth knowing that did not fail the request.\n\n**When the data starts arriving**\nRequests of 50 links or fewer start fetching data straight away. Larger requests are still saved and tracked, but the data is collected by the scheduled update rather than immediately - this stops one big import from holding up everyone else. `trackingEnqueued` tells you which happened. Send 50 links or fewer per request if you need the data to start arriving right away.\n\n**Status codes**\n`200` every link was saved. `207` some were saved and some failed. `422` none could be saved. For `207` and `422`, read `results` to see why.\n\n**Rate Limit:** 5 (limited) / 15 (basic) / 120 (premium) requests per minute", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "Bearer token for authentication", "schema": { "type": "string" }, "example": "Bearer YOUR_KEY_HERE" }, { "name": "content-type", "in": "header", "required": true, "description": "should be set to `application/json`", "schema": { "type": "string", "enum": [ "application/json" ] } } ], "operationId": "bulk_track_accounts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "links" ], "properties": { "links": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "string", "format": "uri", "description": "A link to the account you want to track." }, "description": "The accounts to start tracking, as a list of links. Between 1 and 500 of them.", "example": [ "https://www.tiktok.com/@nike" ] }, "label_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Optional label IDs to apply to all tracked accounts" }, "tracking_type": { "type": "string", "enum": [ "latest_10", "latest_30", "latest_60", "latest_100", "latest_200", "latest_500", "all_videos" ], "description": "Optional tracking type. Defaults to organisation setting." } } } } } }, "responses": { "200": { "description": "Every link was saved. Some may have been tracked already - check each entry's status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when every link succeeded. Check the results array when this is false.", "example": true }, "summary": { "type": "object", "properties": { "total": { "type": "integer", "description": "How many links were processed." }, "succeeded": { "type": "integer", "description": "Newly tracked plus already tracked." }, "failed": { "type": "integer", "description": "How many links could not be saved." }, "alreadyExists": { "type": "integer", "description": "How many you were already tracking." }, "retryable": { "type": "integer", "description": "How many of the failures are worth sending again." } } }, "results": { "type": "array", "description": "One entry per link. If you send the same link more than once it appears here once, so this array can be shorter than the list you sent.", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "account", "video" ], "description": "Whether this line was an account or a video." }, "url": { "type": "string", "description": "The link exactly as you sent it, so you can match it up." }, "status": { "type": "string", "enum": [ "tracked", "already_tracked", "failed" ], "description": "What happened to this link. \"tracked\" means it is new and now being tracked. \"already_tracked\" means you were already tracking it, so nothing changed. \"failed\" means it was not saved - see error and code. Prefer this over the older success field." }, "success": { "type": "boolean", "description": "True for both \"tracked\" and \"already_tracked\". Kept for older integrations." }, "error": { "type": "string", "description": "Plain-language explanation of what went wrong. Only present when status is \"failed\".", "example": "This shortened link could not be expanded in time. Please retry this link." }, "code": { "type": "string", "enum": [ "invalid_url", "wrong_link_type", "link_expand_timeout", "validation_failed", "retry_limit_reached", "internal_error" ], "description": "Stable reason code, so you do not have to match on the message text. \"invalid_url\": we could not read it as a supported link. \"wrong_link_type\": a video link was sent as an account (or the reverse). \"link_expand_timeout\": a shortened link we ran out of time to expand. \"validation_failed\": a temporary problem checking the link. \"retry_limit_reached\": we tried several times and gave up. \"internal_error\": something went wrong on our side. Only present when status is \"failed\"." }, "retryable": { "type": "boolean", "description": "True when sending this same link again is likely to work. Only present when status is \"failed\"." }, "accountId": { "type": "string", "format": "uuid", "description": "The id of the account, present when it was tracked or already tracked." }, "wasExisting": { "type": "boolean", "description": "True when you were already tracking this before the request." } } } }, "trackingEnqueued": { "type": "boolean", "description": "Whether we started fetching data for every item in this request. False when the request was over the immediate-fetch threshold, or when a free-plan organisation sent more than the preview allowance (in which case some items may still have been fetched). Items are saved and tracked either way. Paid plans have the rest collected by the scheduled update; free plans do not, and the warnings will say so." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Things worth knowing that did not fail the request, written in plain language. Empty when there is nothing to report.", "example": [ "This request had 120 links, which is more than 50, so we did not start fetching their data right away. Everything was saved and is being tracked - the scheduled update will collect the data shortly." ] }, "pendingTmvQueue": { "type": "object", "description": "Only present for an organisation with no active subscription, listing the items that were saved but whose data will not be fetched. On the free plan only the first few items of a batch are collected.", "properties": { "accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" } } } }, "videos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" } } } } } } } } } } }, "207": { "description": "Some links were saved and some failed. Read the results array: each failed entry has an error, a code, and a retryable flag.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when every link succeeded. Check the results array when this is false.", "example": false }, "summary": { "type": "object", "properties": { "total": { "type": "integer", "description": "How many links were processed." }, "succeeded": { "type": "integer", "description": "Newly tracked plus already tracked." }, "failed": { "type": "integer", "description": "How many links could not be saved." }, "alreadyExists": { "type": "integer", "description": "How many you were already tracking." }, "retryable": { "type": "integer", "description": "How many of the failures are worth sending again." } } }, "results": { "type": "array", "description": "One entry per link. If you send the same link more than once it appears here once, so this array can be shorter than the list you sent.", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "account", "video" ], "description": "Whether this line was an account or a video." }, "url": { "type": "string", "description": "The link exactly as you sent it, so you can match it up." }, "status": { "type": "string", "enum": [ "tracked", "already_tracked", "failed" ], "description": "What happened to this link. \"tracked\" means it is new and now being tracked. \"already_tracked\" means you were already tracking it, so nothing changed. \"failed\" means it was not saved - see error and code. Prefer this over the older success field." }, "success": { "type": "boolean", "description": "True for both \"tracked\" and \"already_tracked\". Kept for older integrations." }, "error": { "type": "string", "description": "Plain-language explanation of what went wrong. Only present when status is \"failed\".", "example": "This shortened link could not be expanded in time. Please retry this link." }, "code": { "type": "string", "enum": [ "invalid_url", "wrong_link_type", "link_expand_timeout", "validation_failed", "retry_limit_reached", "internal_error" ], "description": "Stable reason code, so you do not have to match on the message text. \"invalid_url\": we could not read it as a supported link. \"wrong_link_type\": a video link was sent as an account (or the reverse). \"link_expand_timeout\": a shortened link we ran out of time to expand. \"validation_failed\": a temporary problem checking the link. \"retry_limit_reached\": we tried several times and gave up. \"internal_error\": something went wrong on our side. Only present when status is \"failed\"." }, "retryable": { "type": "boolean", "description": "True when sending this same link again is likely to work. Only present when status is \"failed\"." }, "accountId": { "type": "string", "format": "uuid", "description": "The id of the account, present when it was tracked or already tracked." }, "wasExisting": { "type": "boolean", "description": "True when you were already tracking this before the request." } } } }, "trackingEnqueued": { "type": "boolean", "description": "Whether we started fetching data for every item in this request. False when the request was over the immediate-fetch threshold, or when a free-plan organisation sent more than the preview allowance (in which case some items may still have been fetched). Items are saved and tracked either way. Paid plans have the rest collected by the scheduled update; free plans do not, and the warnings will say so." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Things worth knowing that did not fail the request, written in plain language. Empty when there is nothing to report.", "example": [ "This request had 120 links, which is more than 50, so we did not start fetching their data right away. Everything was saved and is being tracked - the scheduled update will collect the data shortly." ] }, "pendingTmvQueue": { "type": "object", "description": "Only present for an organisation with no active subscription, listing the items that were saved but whose data will not be fetched. On the free plan only the first few items of a batch are collected.", "properties": { "accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" } } } }, "videos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" } } } } } } } } } } }, "400": { "description": "Bad request - validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Validation error message" } } } } } }, "422": { "description": "No link could be saved. Read the results array for the reason on each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when every link succeeded. Check the results array when this is false.", "example": false }, "summary": { "type": "object", "properties": { "total": { "type": "integer", "description": "How many links were processed." }, "succeeded": { "type": "integer", "description": "Newly tracked plus already tracked." }, "failed": { "type": "integer", "description": "How many links could not be saved." }, "alreadyExists": { "type": "integer", "description": "How many you were already tracking." }, "retryable": { "type": "integer", "description": "How many of the failures are worth sending again." } } }, "results": { "type": "array", "description": "One entry per link. If you send the same link more than once it appears here once, so this array can be shorter than the list you sent.", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "account", "video" ], "description": "Whether this line was an account or a video." }, "url": { "type": "string", "description": "The link exactly as you sent it, so you can match it up." }, "status": { "type": "string", "enum": [ "tracked", "already_tracked", "failed" ], "description": "What happened to this link. \"tracked\" means it is new and now being tracked. \"already_tracked\" means you were already tracking it, so nothing changed. \"failed\" means it was not saved - see error and code. Prefer this over the older success field." }, "success": { "type": "boolean", "description": "True for both \"tracked\" and \"already_tracked\". Kept for older integrations." }, "error": { "type": "string", "description": "Plain-language explanation of what went wrong. Only present when status is \"failed\".", "example": "This shortened link could not be expanded in time. Please retry this link." }, "code": { "type": "string", "enum": [ "invalid_url", "wrong_link_type", "link_expand_timeout", "validation_failed", "retry_limit_reached", "internal_error" ], "description": "Stable reason code, so you do not have to match on the message text. \"invalid_url\": we could not read it as a supported link. \"wrong_link_type\": a video link was sent as an account (or the reverse). \"link_expand_timeout\": a shortened link we ran out of time to expand. \"validation_failed\": a temporary problem checking the link. \"retry_limit_reached\": we tried several times and gave up. \"internal_error\": something went wrong on our side. Only present when status is \"failed\"." }, "retryable": { "type": "boolean", "description": "True when sending this same link again is likely to work. Only present when status is \"failed\"." }, "accountId": { "type": "string", "format": "uuid", "description": "The id of the account, present when it was tracked or already tracked." }, "wasExisting": { "type": "boolean", "description": "True when you were already tracking this before the request." } } } }, "trackingEnqueued": { "type": "boolean", "description": "Whether we started fetching data for every item in this request. False when the request was over the immediate-fetch threshold, or when a free-plan organisation sent more than the preview allowance (in which case some items may still have been fetched). Items are saved and tracked either way. Paid plans have the rest collected by the scheduled update; free plans do not, and the warnings will say so." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Things worth knowing that did not fail the request, written in plain language. Empty when there is nothing to report.", "example": [ "This request had 120 links, which is more than 50, so we did not start fetching their data right away. Everything was saved and is being tracked - the scheduled update will collect the data shortly." ] }, "pendingTmvQueue": { "type": "object", "description": "Only present for an organisation with no active subscription, listing the items that were saved but whose data will not be fetched. On the free plan only the first few items of a batch are collected.", "properties": { "accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" } } } }, "videos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" } } } } } } } } } } }, "500": { "description": "Internal server error" } } }, "delete": { "tags": [ "Account Management" ], "summary": "Bulk Stop Tracking Accounts", "description": "Stop tracking up to 500 accounts in one request.\n\nSend a list in `ids`. Each entry can be the account's id or the link you originally tracked - we look up links for you. Historical data stays available; this only stops new data being collected.\n\nIf a **link** cannot be matched to something you track, the whole request fails with `404` naming the links that did not match, before anything is removed. Entries given as **ids** are not checked up front, so a request of ids can partly succeed and return `207` - read the response to see which ones did.\n\n**Rate Limit:** 5 (limited) / 15 (basic) / 120 (premium) requests per minute", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "Bearer token for authentication", "schema": { "type": "string" }, "example": "Bearer YOUR_KEY_HERE" } ], "operationId": "bulk_stop_tracking_accounts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "string" }, "description": "The accounts to stop tracking. Each entry is either an id or the link you tracked. Between 1 and 500 of them." }, "leave_videos": { "type": "boolean", "default": false, "description": "If true, videos linked to these accounts will not be removed" } } } } } }, "responses": { "200": { "description": "All accounts successfully stopped tracking", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "summary": { "type": "object", "properties": { "total": { "type": "integer" }, "succeeded": { "type": "integer" }, "failed": { "type": "integer" } } }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "success": { "type": "boolean" }, "error": { "type": "string" } } } } } } } } }, "207": { "description": "Partial success - some accounts untracked, some failed" }, "400": { "description": "Bad request - validation error" }, "404": { "description": "None of the provided account IDs were found" }, "500": { "description": "Internal server error" } } } }, "/videos": { "get": { "tags": [ "Video Management" ], "summary": "Get All Videos", "description": "**All tiers** — Limited/Basic: 1 result with masked metrics. Premium: full access.\n\nRetrieves a list of all videos tracked by your organization in Shortimize. This endpoint provides detailed information about each video, including engagement metrics, content details, and historical performance data.\n\nUse this to get a comprehensive view of your video advertisement portfolio and their performance across different platforms.\n\n**Rate Limit:** 5 (limited) / 15 (basic) / 30 (premium) requests per minute", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "Bearer token for authentication", "schema": { "type": "string" }, "example": "Bearer YOUR_KEY_HERE" }, { "in": "query", "name": "page", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "Page number for pagination" }, { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 5000, "minimum": 1, "maximum": 5000 }, "description": "Number of items to return per page" }, { "in": "query", "name": "order_by", "schema": { "type": "string", "default": "latest_updated_at", "enum": [ "created_at", "uploaded_at", "latest_views", "latest_likes", "latest_comments", "latest_bookmarks", "latest_shares", "latest_engagement", "latest_updated_at" ] }, "description": "Field to order results by" }, { "in": "query", "name": "order_direction", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] }, "description": "Direction of ordering (ascending or descending)" }, { "in": "query", "name": "username", "schema": { "type": "string" }, "description": "Filter videos by specific username" }, { "in": "query", "name": "linked_account_id", "schema": { "type": "string", "format": "uuid" }, "description": "Filter videos by specific linked account ID" }, { "in": "query", "name": "uploaded_at_start", "schema": { "type": "string", "format": "date" }, "description": "Filter videos uploaded on or after this date (inclusive)", "example": "2024-12-01 (YYYY-MM-DD)" }, { "in": "query", "name": "uploaded_at_end", "schema": { "type": "string", "format": "date" }, "description": "Filter videos uploaded on or before this date (inclusive)", "example": "2024-12-01 (YYYY-MM-DD)" }, { "in": "query", "name": "latest_updated_at_start", "schema": { "type": "string", "format": "date-time" }, "description": "Filter videos which have been last updated on or after this date and time (inclusive)", "example": "2024-12-01T00:00:00Z" }, { "in": "query", "name": "latest_updated_at_end", "schema": { "type": "string", "format": "date-time" }, "description": "Filter videos which have been last updated on or before this date and time (inclusive)", "example": "2024-12-01T23:59:59Z" }, { "in": "query", "name": "ad_info_shop", "schema": { "type": "boolean" }, "description": "Filter TikTok shop ads (true/false)" }, { "in": "query", "name": "ad_product_id_shop", "schema": { "type": "boolean" }, "description": "Filter TikTok shop ads that have a product id. (true)" }, { "in": "query", "name": "has_metrics", "schema": { "type": "boolean" }, "description": "Only get videos which have been retrieved atleast once (metrics are not null)." }, { "name": "collections", "in": "query", "description": "Optional comma-separated list of collections to filter accounts (e.g. collection1,collection2,collection3)\n\nMake sure to URL encode them before sending.", "required": false, "schema": { "type": "string" }, "example": "competitor-x,water%20app" } ], "operationId": "get_all_videos", "responses": { "200": { "description": "Successful response with a list of videos and their detailed information", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "organisation_id": { "type": "string", "format": "uuid", "description": "Unique identifier for your organization" }, "ad_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the video" }, "username": { "type": "string", "description": "Username of the account that posted the video. May carry a '~' disambiguation suffix ('handle~') for Facebook accounts: Facebook permits two genuinely different profiles to share one display handle, and the suffix keeps their stats separate. Treat the full string as canonical in API calls; strip everything from '~' onward for display." }, "platform": { "type": "string", "enum": [ "tiktok", "instagram", "youtube" ], "description": "Social media platform where the video is posted" }, "ad_link": { "type": "string", "format": "uri", "description": "URL of the video" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the video was added to Shortimize" }, "removed": { "type": "boolean", "description": "Indicates if the video has been removed from tracking" }, "linked_account_id": { "type": "string", "format": "uuid", "description": "Unique identifier of the linked account" }, "uploaded_at": { "type": [ "string", "null" ], "format": "date", "description": "Date when the video was uploaded to the platform" }, "song_name": { "type": [ "string", "null" ], "description": "Name of the song used in the video" }, "song_link": { "type": [ "string", "null" ], "description": "Link to the song used in the video" }, "video_length": { "type": [ "string", "null" ], "description": "Length of the video in seconds" }, "title": { "type": "string", "description": "Title or caption of the video" }, "not_safe": { "type": "boolean", "description": "Indicates if the video is flagged as not safe for work" }, "private": { "type": "boolean", "description": "Indicates if the video is set to private" }, "hidden_stats": { "type": "boolean", "description": "Indicates if the video's statistics are hidden" }, "latest_views": { "type": "integer", "description": "Most recent count of views" }, "latest_likes": { "type": "integer", "description": "Most recent count of likes" }, "latest_comments": { "type": "integer", "description": "Most recent count of comments" }, "latest_bookmarks": { "type": "integer", "description": "Most recent count of bookmarks" }, "latest_shares": { "type": "integer", "description": "Most recent count of shares" }, "latest_engagement": { "type": [ "integer", "null" ], "description": "Most recent count of total engagement" }, "latest_updated_at": { "type": "string", "format": "date-time", "description": "Timestamp of the most recent update to the video's statistics" }, "outlier_multiplier": { "type": "number", "description": "Multiplier indicating how much this video outperforms the account's median" }, "increase_1d": { "type": "number", "description": "Percentage increase in views over the last day" }, "increase_7d": { "type": "number", "description": "Percentage increase in views over the last 7 days" }, "increase_14d": { "type": "number", "description": "Percentage increase in views over the last 14 days" }, "increase_30d": { "type": "number", "description": "Percentage increase in views over the last 30 days" }, "ad_info_shop": { "type": "boolean", "description": "Whether the ad is a tiktok shop ad or not. Only valid for Tiktok videos." }, "ad_is_ad": { "type": "boolean", "description": "Whether the ad is an actual ad. Only valid for Tiktok videos." }, "ad_product_id_shop": { "type": "string", "description": "The product shop id. Only valid for Tiktok videos." }, "label_ids": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" }, "description": "Array of collection/label IDs associated with the video" }, "label_names": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Array of collection/label names associated with the video" } } } }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of records" }, "page": { "type": "integer", "description": "Current page number" }, "limit": { "type": "integer", "description": "Number of items per page" }, "total_pages": { "type": "integer", "description": "Total number of pages" }, "has_more": { "type": "boolean", "description": "Whether there are more results beyond the current page" }, "order_by": { "type": "string", "description": "Field used for ordering" }, "order_direction": { "type": "string", "description": "Direction of ordering" } } }, "filters": { "type": "object", "properties": { "username": { "type": "string", "description": "May carry a '~' disambiguation suffix ('handle~') for Facebook accounts: Facebook permits two genuinely different profiles to share one display handle, and the suffix keeps their stats separate. Treat the full string as canonical in API calls; strip everything from '~' onward for display." }, "linked_account_id": { "type": "string" }, "uploaded_at_range": { "type": "object", "properties": { "start": { "type": "string", "format": "date" }, "end": { "type": "string", "format": "date" } } }, "ad_info_shop": { "type": "boolean" }, "has_metrics": { "type": "boolean" }, "collections": { "type": "array", "items": { "type": "string" } } } } } } } } }, "401": { "description": "Unauthorized - Invalid API key" }, "429": { "description": "Rate limit exceeded. Wait the number of seconds given in the Retry-After header, then retry.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Whole seconds to wait before retrying. This is the time left in the current window, not a fixed minute, so a request rejected near the end of a window gets a short wait. Always at least 1." }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed per minute for this API key." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets. Same value as Retry-After." } } } } }, "post": { "tags": [ "Video Management" ], "summary": "Track Video", "description": "Track a video and link it to your organisation in Shortimize. A direct URL to the video analysis on Shortimize will be returned.\n\n**Rate Limit:** 5 (limited) / 15 (basic) / 120 (premium) requests per minute", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "Bearer token for authentication", "schema": { "type": "string" }, "example": "Bearer YOUR_KEY_HERE" }, { "name": "content-type", "in": "header", "required": true, "description": "Must be set to `application/json`", "schema": { "type": "string", "enum": [ "application/json" ] } } ], "operationId": "track_video", "x-internal": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "link" ], "properties": { "link": { "type": "string", "format": "uri", "description": "The URL of the video to be tracked" }, "collection_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Optional list of collection UUIDs to associate with the video" }, "collection_names": { "type": "array", "items": { "type": "string" }, "description": "Optional list of collection names to create and associate with the video" } } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Only present if the video is already being tracked.", "example": "This video is already being tracked in the organisation." }, "directUrl": { "type": "string", "format": "uri", "description": "Shortened URL to the video analysis on the dashboard", "example": "https://app.shortimize.com/video//" }, "videoId": { "type": "string", "description": "A UUID representing the video in our system", "example": "xxxxxx-xxxxxx-xxxxxx-xxxxxx-xxxxxx" } } } } } }, "400": { "description": "Bad request - missing or invalid link", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Detailed error message explaining the validation failure", "example": "Invalid video link. Please enter a valid full TikTok, Instagram, or YouTube video URL." } } } } } }, "500": { "description": "Internal server error" } } }, "delete": { "tags": [ "Video Management" ], "summary": "Stop Tracking Video", "description": "Stops tracking specific videos in Shortimize. This operation allows you to selectively pause data collection for individual videos while maintaining their historical performance data and metrics. \nUse this when you need to stop monitoring particular videos that are no longer relevant to your campaign or to optimize your tracking quota. The videos' past performance data remains accessible for analysis and reporting purposes.\n\n**Rate Limit:** 5 (limited) / 15 (basic) / 120 (premium) requests per minute", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "Bearer token for authentication", "schema": { "type": "string" }, "example": "Bearer YOUR_KEY_HERE" } ], "operationId": "stop_tracking_video", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "The ID (UUID) or URL of the video to stop tracking" } } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message confirming the operation", "example": "Successfully stopped tracking the video." } } } } } }, "500": { "description": "Internal server error" } } } }, "/videos/bulk": { "post": { "tags": [ "Video Management" ], "summary": "Bulk Track Videos", "description": "Start tracking up to 500 videos in one request.\n\nSend a list of links in `links`. Each one is handled on its own, so a bad link does not stop the rest - you get one entry per link back in `results`, saying whether it was newly tracked, already tracked, or failed.\n\n**Reading the response**\n- `summary` gives you the counts at a glance.\n- Each entry in `results` has a `status`: `tracked`, `already_tracked`, or `failed`.\n- A failed entry also has a plain-language `error`, a stable `code`, and `retryable`. If `retryable` is true, sending that link again will usually work - resend just those links, not the whole batch.\n- `warnings` holds anything worth knowing that did not fail the request.\n\n**When the data starts arriving**\nRequests of 50 links or fewer start fetching data straight away. Larger requests are still saved and tracked, but the data is collected by the scheduled update rather than immediately - this stops one big import from holding up everyone else. `trackingEnqueued` tells you which happened. Send 50 links or fewer per request if you need the data to start arriving right away.\n\n**Status codes**\n`200` every link was saved. `207` some were saved and some failed. `422` none could be saved. For `207` and `422`, read `results` to see why.\n\n**Rate Limit:** 5 (limited) / 15 (basic) / 120 (premium) requests per minute", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "Bearer token for authentication", "schema": { "type": "string" }, "example": "Bearer YOUR_KEY_HERE" }, { "name": "content-type", "in": "header", "required": true, "description": "Must be set to `application/json`", "schema": { "type": "string", "enum": [ "application/json" ] } } ], "operationId": "bulk_track_videos", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "links" ], "properties": { "links": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "string", "format": "uri", "description": "A link to the video you want to track." }, "description": "The videos to start tracking, as a list of links. Between 1 and 500 of them.", "example": [ "https://www.tiktok.com/@nike/video/7301234567890123456" ] }, "label_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Optional label IDs to apply to all tracked videos" } } } } } }, "responses": { "200": { "description": "Every link was saved. Some may have been tracked already - check each entry's status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when every link succeeded. Check the results array when this is false.", "example": true }, "summary": { "type": "object", "properties": { "total": { "type": "integer", "description": "How many links were processed." }, "succeeded": { "type": "integer", "description": "Newly tracked plus already tracked." }, "failed": { "type": "integer", "description": "How many links could not be saved." }, "alreadyExists": { "type": "integer", "description": "How many you were already tracking." }, "retryable": { "type": "integer", "description": "How many of the failures are worth sending again." } } }, "results": { "type": "array", "description": "One entry per link. If you send the same link more than once it appears here once, so this array can be shorter than the list you sent.", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "account", "video" ], "description": "Whether this line was an account or a video." }, "url": { "type": "string", "description": "The link exactly as you sent it, so you can match it up." }, "status": { "type": "string", "enum": [ "tracked", "already_tracked", "failed" ], "description": "What happened to this link. \"tracked\" means it is new and now being tracked. \"already_tracked\" means you were already tracking it, so nothing changed. \"failed\" means it was not saved - see error and code. Prefer this over the older success field." }, "success": { "type": "boolean", "description": "True for both \"tracked\" and \"already_tracked\". Kept for older integrations." }, "error": { "type": "string", "description": "Plain-language explanation of what went wrong. Only present when status is \"failed\".", "example": "This shortened link could not be expanded in time. Please retry this link." }, "code": { "type": "string", "enum": [ "invalid_url", "wrong_link_type", "link_expand_timeout", "validation_failed", "retry_limit_reached", "internal_error" ], "description": "Stable reason code, so you do not have to match on the message text. \"invalid_url\": we could not read it as a supported link. \"wrong_link_type\": a video link was sent as an account (or the reverse). \"link_expand_timeout\": a shortened link we ran out of time to expand. \"validation_failed\": a temporary problem checking the link. \"retry_limit_reached\": we tried several times and gave up. \"internal_error\": something went wrong on our side. Only present when status is \"failed\"." }, "retryable": { "type": "boolean", "description": "True when sending this same link again is likely to work. Only present when status is \"failed\"." }, "videoId": { "type": "string", "format": "uuid", "description": "The id of the video, present when it was tracked or already tracked." }, "wasExisting": { "type": "boolean", "description": "True when you were already tracking this before the request." } } } }, "trackingEnqueued": { "type": "boolean", "description": "Whether we started fetching data for every item in this request. False when the request was over the immediate-fetch threshold, or when a free-plan organisation sent more than the preview allowance (in which case some items may still have been fetched). Items are saved and tracked either way. Paid plans have the rest collected by the scheduled update; free plans do not, and the warnings will say so." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Things worth knowing that did not fail the request, written in plain language. Empty when there is nothing to report.", "example": [ "This request had 120 links, which is more than 50, so we did not start fetching their data right away. Everything was saved and is being tracked - the scheduled update will collect the data shortly." ] }, "pendingTmvQueue": { "type": "object", "description": "Only present for an organisation with no active subscription, listing the items that were saved but whose data will not be fetched. On the free plan only the first few items of a batch are collected.", "properties": { "accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" } } } }, "videos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" } } } } } } } } } } }, "207": { "description": "Some links were saved and some failed. Read the results array: each failed entry has an error, a code, and a retryable flag.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when every link succeeded. Check the results array when this is false.", "example": false }, "summary": { "type": "object", "properties": { "total": { "type": "integer", "description": "How many links were processed." }, "succeeded": { "type": "integer", "description": "Newly tracked plus already tracked." }, "failed": { "type": "integer", "description": "How many links could not be saved." }, "alreadyExists": { "type": "integer", "description": "How many you were already tracking." }, "retryable": { "type": "integer", "description": "How many of the failures are worth sending again." } } }, "results": { "type": "array", "description": "One entry per link. If you send the same link more than once it appears here once, so this array can be shorter than the list you sent.", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "account", "video" ], "description": "Whether this line was an account or a video." }, "url": { "type": "string", "description": "The link exactly as you sent it, so you can match it up." }, "status": { "type": "string", "enum": [ "tracked", "already_tracked", "failed" ], "description": "What happened to this link. \"tracked\" means it is new and now being tracked. \"already_tracked\" means you were already tracking it, so nothing changed. \"failed\" means it was not saved - see error and code. Prefer this over the older success field." }, "success": { "type": "boolean", "description": "True for both \"tracked\" and \"already_tracked\". Kept for older integrations." }, "error": { "type": "string", "description": "Plain-language explanation of what went wrong. Only present when status is \"failed\".", "example": "This shortened link could not be expanded in time. Please retry this link." }, "code": { "type": "string", "enum": [ "invalid_url", "wrong_link_type", "link_expand_timeout", "validation_failed", "retry_limit_reached", "internal_error" ], "description": "Stable reason code, so you do not have to match on the message text. \"invalid_url\": we could not read it as a supported link. \"wrong_link_type\": a video link was sent as an account (or the reverse). \"link_expand_timeout\": a shortened link we ran out of time to expand. \"validation_failed\": a temporary problem checking the link. \"retry_limit_reached\": we tried several times and gave up. \"internal_error\": something went wrong on our side. Only present when status is \"failed\"." }, "retryable": { "type": "boolean", "description": "True when sending this same link again is likely to work. Only present when status is \"failed\"." }, "videoId": { "type": "string", "format": "uuid", "description": "The id of the video, present when it was tracked or already tracked." }, "wasExisting": { "type": "boolean", "description": "True when you were already tracking this before the request." } } } }, "trackingEnqueued": { "type": "boolean", "description": "Whether we started fetching data for every item in this request. False when the request was over the immediate-fetch threshold, or when a free-plan organisation sent more than the preview allowance (in which case some items may still have been fetched). Items are saved and tracked either way. Paid plans have the rest collected by the scheduled update; free plans do not, and the warnings will say so." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Things worth knowing that did not fail the request, written in plain language. Empty when there is nothing to report.", "example": [ "This request had 120 links, which is more than 50, so we did not start fetching their data right away. Everything was saved and is being tracked - the scheduled update will collect the data shortly." ] }, "pendingTmvQueue": { "type": "object", "description": "Only present for an organisation with no active subscription, listing the items that were saved but whose data will not be fetched. On the free plan only the first few items of a batch are collected.", "properties": { "accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" } } } }, "videos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" } } } } } } } } } } }, "400": { "description": "Bad request - validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Validation error message" } } } } } }, "422": { "description": "No link could be saved. Read the results array for the reason on each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when every link succeeded. Check the results array when this is false.", "example": false }, "summary": { "type": "object", "properties": { "total": { "type": "integer", "description": "How many links were processed." }, "succeeded": { "type": "integer", "description": "Newly tracked plus already tracked." }, "failed": { "type": "integer", "description": "How many links could not be saved." }, "alreadyExists": { "type": "integer", "description": "How many you were already tracking." }, "retryable": { "type": "integer", "description": "How many of the failures are worth sending again." } } }, "results": { "type": "array", "description": "One entry per link. If you send the same link more than once it appears here once, so this array can be shorter than the list you sent.", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "account", "video" ], "description": "Whether this line was an account or a video." }, "url": { "type": "string", "description": "The link exactly as you sent it, so you can match it up." }, "status": { "type": "string", "enum": [ "tracked", "already_tracked", "failed" ], "description": "What happened to this link. \"tracked\" means it is new and now being tracked. \"already_tracked\" means you were already tracking it, so nothing changed. \"failed\" means it was not saved - see error and code. Prefer this over the older success field." }, "success": { "type": "boolean", "description": "True for both \"tracked\" and \"already_tracked\". Kept for older integrations." }, "error": { "type": "string", "description": "Plain-language explanation of what went wrong. Only present when status is \"failed\".", "example": "This shortened link could not be expanded in time. Please retry this link." }, "code": { "type": "string", "enum": [ "invalid_url", "wrong_link_type", "link_expand_timeout", "validation_failed", "retry_limit_reached", "internal_error" ], "description": "Stable reason code, so you do not have to match on the message text. \"invalid_url\": we could not read it as a supported link. \"wrong_link_type\": a video link was sent as an account (or the reverse). \"link_expand_timeout\": a shortened link we ran out of time to expand. \"validation_failed\": a temporary problem checking the link. \"retry_limit_reached\": we tried several times and gave up. \"internal_error\": something went wrong on our side. Only present when status is \"failed\"." }, "retryable": { "type": "boolean", "description": "True when sending this same link again is likely to work. Only present when status is \"failed\"." }, "videoId": { "type": "string", "format": "uuid", "description": "The id of the video, present when it was tracked or already tracked." }, "wasExisting": { "type": "boolean", "description": "True when you were already tracking this before the request." } } } }, "trackingEnqueued": { "type": "boolean", "description": "Whether we started fetching data for every item in this request. False when the request was over the immediate-fetch threshold, or when a free-plan organisation sent more than the preview allowance (in which case some items may still have been fetched). Items are saved and tracked either way. Paid plans have the rest collected by the scheduled update; free plans do not, and the warnings will say so." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Things worth knowing that did not fail the request, written in plain language. Empty when there is nothing to report.", "example": [ "This request had 120 links, which is more than 50, so we did not start fetching their data right away. Everything was saved and is being tracked - the scheduled update will collect the data shortly." ] }, "pendingTmvQueue": { "type": "object", "description": "Only present for an organisation with no active subscription, listing the items that were saved but whose data will not be fetched. On the free plan only the first few items of a batch are collected.", "properties": { "accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" } } } }, "videos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" } } } } } } } } } } }, "500": { "description": "Internal server error" } } }, "delete": { "tags": [ "Video Management" ], "summary": "Bulk Stop Tracking Videos", "description": "Stop tracking up to 500 videos in one request.\n\nSend a list in `ids`. Each entry can be the video's id or the link you originally tracked - we look up links for you. Historical data stays available; this only stops new data being collected.\n\nIf a **link** cannot be matched to something you track, the whole request fails with `404` naming the links that did not match, before anything is removed. Entries given as **ids** are not checked up front, so a request of ids can partly succeed and return `207` - read the response to see which ones did.\n\n**Rate Limit:** 5 (limited) / 15 (basic) / 120 (premium) requests per minute", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "Bearer token for authentication", "schema": { "type": "string" }, "example": "Bearer YOUR_KEY_HERE" } ], "operationId": "bulk_stop_tracking_videos", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "string" }, "description": "The videos to stop tracking. Each entry is either an id or the link you tracked. Between 1 and 500 of them." } } } } } }, "responses": { "200": { "description": "All videos successfully stopped tracking", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "summary": { "type": "object", "properties": { "total": { "type": "integer" }, "succeeded": { "type": "integer" }, "failed": { "type": "integer" } } }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "success": { "type": "boolean" }, "error": { "type": "string" } } } } } } } } }, "207": { "description": "Partial success - some videos untracked, some failed" }, "400": { "description": "Bad request - validation error" }, "404": { "description": "None of the provided video IDs were found" }, "500": { "description": "Internal server error" } } } }, "/authenticate": { "get": { "tags": [ "Authentication" ], "summary": "Authenticate", "description": "Test your AUTH key against our service, if successful your organisation name will be returned.\n\n**Rate Limit:** 5 (limited) / 15 (basic) / 30 (premium) requests per minute", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "Bearer token for authentication", "schema": { "type": "string" }, "example": "Bearer YOUR_KEY_HERE" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Bad request (e.g., query parameters or body were sent)" } }, "operationId": "authenticate", "x-internal": true } }, "/organisation/history": { "get": { "tags": [ "Organisation Management" ], "summary": "Get Organisation History", "description": "**All tiers** — Limited/Basic: 1 result with masked metrics. Premium: full access.\n\nRetrieves daily aggregated metrics for your entire organisation. By default if no dates are passed, gets the last 30 days of data. Data is available for the last 90 days (up to 2 years for premium users).\n\n**Rate Limit:** 5 (limited) / 15 (basic) / 120 (premium) requests per minute", "operationId": "get_organisation_history", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "Bearer token for authentication", "schema": { "type": "string" }, "example": "Bearer YOUR_KEY_HERE" }, { "name": "start_date", "in": "query", "required": false, "description": "Start date (inclusive) in YYYY-MM-DD format. Defaults to 30 days ago if not provided. Cannot be older than 90 days (730 days for premium users).", "schema": { "type": "string", "format": "date" }, "example": "2025-01-01" }, { "name": "end_date", "in": "query", "required": false, "description": "End date (inclusive) in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" }, "example": "2025-01-31" } ], "responses": { "200": { "description": "Successful response - array of daily metrics", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "views": { "type": "integer" }, "likes": { "type": "integer" }, "comments": { "type": "integer" }, "shares": { "type": "integer" }, "bookmarks": { "type": "integer" }, "engagements": { "type": "integer" }, "total_ads": { "type": "integer" }, "ads_upload_count": { "type": "integer" } } } } } } }, "400": { "description": "Bad request – start_date older than allowed range (90 days, or 730 days for premium)" }, "401": { "description": "Unauthorized – invalid or missing API key" } } } }, "/videos/{ad_id}": { "get": { "tags": [ "Video Management" ], "summary": "Get Specific Video", "description": "**All tiers** — Limited/Basic: 1 result with masked metrics. Premium: full access.\n\nRetrieves detailed information about a specific video advertisement linked to your organisation in Shortimize via its ad_id. This endpoint provides comprehensive data including video metrics, performance indicators, and historical data. Use this to get in-depth insights into a particular video's performance, engagement rates, and audience reception.\n\nThe data includes:\n- Video identification and platform details\n- Latest engagement metrics (views, likes, comments, shares)\n- Performance statistics (median views, outlier multiplier)\n- Historical data for multiple data points\n- Growth metrics (1-day and 7-day view increases)\n\nThis endpoint is crucial for analyzing the success of individual video advertisements and understanding their performance in the context of the account's overall metrics.\n\n**Rate Limit:** 5 (limited) / 15 (basic) / 30 (premium) requests per minute", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "Bearer token for authentication", "schema": { "type": "string" }, "example": "Bearer YOUR_KEY_HERE" }, { "name": "ad_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Video identifier - can be a UUID or video URL (URL-encoded)" } ], "operationId": "get_video", "responses": { "200": { "description": "Successful response with detailed information about the specific video", "content": { "application/json": { "schema": { "type": "object", "properties": { "organisation_id": { "type": "string", "format": "uuid", "description": "Unique identifier for your organization" }, "ad_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the video" }, "username": { "type": "string", "description": "Username of the account that posted the video. May carry a '~' disambiguation suffix ('handle~') for Facebook accounts: Facebook permits two genuinely different profiles to share one display handle, and the suffix keeps their stats separate. Treat the full string as canonical in API calls; strip everything from '~' onward for display." }, "platform": { "type": "string", "enum": [ "tiktok", "instagram", "youtube" ], "description": "Social media platform where the video is posted" }, "ad_link": { "type": "string", "format": "uri", "description": "URL of the video" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the video was added to Shortimize" }, "removed": { "type": "boolean", "description": "Indicates if the video has been removed from tracking" }, "linked_account_id": { "type": "string", "format": "uuid", "description": "Unique identifier of the linked account" }, "uploaded_at": { "type": [ "string", "null" ], "format": "date", "description": "Date when the video was uploaded to the platform" }, "song_name": { "type": [ "string", "null" ], "description": "Name of the song used in the video" }, "song_link": { "type": [ "string", "null" ], "description": "Link to the song used in the video" }, "video_length": { "type": [ "string", "null" ], "description": "Length of the video in seconds" }, "title": { "type": "string", "description": "Title or caption of the video" }, "not_safe": { "type": "boolean", "description": "Indicates if the video is flagged as not safe for work" }, "private": { "type": "boolean", "description": "Indicates if the video is set to private" }, "hidden_stats": { "type": "boolean", "description": "Indicates if the video's statistics are hidden" }, "latest_views": { "type": "integer", "description": "Most recent count of views" }, "latest_likes": { "type": "integer", "description": "Most recent count of likes" }, "latest_comments": { "type": "integer", "description": "Most recent count of comments" }, "latest_bookmarks": { "type": "integer", "description": "Most recent count of bookmarks" }, "latest_shares": { "type": "integer", "description": "Most recent count of shares" }, "latest_engagement": { "type": [ "integer", "null" ], "description": "Most recent count of total engagement" }, "latest_updated_at": { "type": "string", "format": "date-time", "description": "Timestamp of the most recent update to the video's statistics" }, "outlier_multiplier": { "type": "number", "description": "Multiplier indicating how much this video outperforms the account's median" }, "increase_1d": { "type": "number", "description": "Percentage increase in views over the last day" }, "increase_7d": { "type": "number", "description": "Percentage increase in views over the last 7 days" }, "increase_14d": { "type": "number", "description": "Percentage increase in views over the last 14 days" }, "increase_30d": { "type": "number", "description": "Percentage increase in views over the last 30 days" }, "ad_info_shop": { "type": "boolean", "description": "Whether the ad is a tiktok shop ad or not. Only valid for Tiktok videos." }, "label_ids": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" }, "description": "Array of collection/label IDs associated with the video" }, "label_names": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Array of collection/label names associated with the video" } } } } } }, "401": { "description": "Unauthorized - Invalid API key" }, "404": { "description": "Not Found - Video not found" }, "429": { "description": "Rate limit exceeded. Wait the number of seconds given in the Retry-After header, then retry.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Whole seconds to wait before retrying. This is the time left in the current window, not a fixed minute, so a request rejected near the end of a window gets a short wait. Always at least 1." }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed per minute for this API key." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets. Same value as Retry-After." } } } } }, "delete": { "tags": [ "Video Management" ], "summary": "Stop Tracking Video By ID", "description": "Stop tracking a video linked to your organisation via its ad_id.\n\nUse this to pause tracking when you want to stop monitoring a video's performance or remove it from your active tracking portfolio.\n\n**Rate Limit:** 5 (limited) / 15 (basic) / 120 (premium) requests per minute", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "Bearer token for authentication", "schema": { "type": "string" }, "example": "Bearer YOUR_KEY_HERE" }, { "name": "ad_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The UUID of the video to stop tracking" } ], "operationId": "stop_tracking_video_by_id", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message confirming the operation", "example": "Successfully stopped tracking the video." } } } } } }, "400": { "description": "Bad request - missing or invalid video ID" }, "500": { "description": "Internal server error" } } } }, "/videos/{ad_id}/history": { "get": { "tags": [ "Video Management" ], "summary": "Get Video History", "description": "**All tiers** — Limited/Basic: 1 result with masked metrics. Premium: full access.\n\nRetrieves daily aggregated metrics for a specific video (ad_id) tracked by your organization. By default if no dates are passed, gets the last 30 days of data. Maximum date range is limited to 90 days (730 days for premium users — historical data beyond 90 days is interpolated from periodic snapshots).\n\n**Rate Limit:** 5 (limited) / 15 (basic) / 120 (premium) requests per minute", "operationId": "get_video_history", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "Bearer token for authentication", "schema": { "type": "string" }, "example": "Bearer YOUR_KEY_HERE" }, { "name": "ad_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Video identifier - can be a UUID or video URL (URL-encoded)" }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Start date (inclusive) in YYYY-MM-DD format. Defaults to 30 days ago if not provided. Cannot be older than 90 days (730 days for premium users)." }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "End date (inclusive) in YYYY-MM-DD format" } ], "responses": { "200": { "description": "List of daily metrics for the specified video", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "views": { "type": "integer" }, "likes": { "type": "integer" }, "comments": { "type": "integer" }, "shares": { "type": "integer" }, "bookmarks": { "type": "integer" }, "engagements": { "type": "integer" } } } } } } }, "401": { "description": "Unauthorized – invalid or missing API key" }, "404": { "description": "Not found – ad_id not found or not in your organization" } } } }, "/accounts/{account_id}/history": { "get": { "tags": [ "Account Management" ], "summary": "Get Account History", "description": "**All tiers** — Limited/Basic: 1 result with masked metrics. Premium: full access.\n\nRetrieves daily aggregated metrics for a specific account (account_id) tracked by your organization. By default if no dates are passed, gets the last 30 days of data. Data is available for the last 90 days (up to 2 years for premium users).\n\n**Rate Limit:** 5 (limited) / 15 (basic) / 120 (premium) requests per minute", "operationId": "get_account_history", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "Bearer token for authentication", "schema": { "type": "string" }, "example": "Bearer YOUR_KEY_HERE" }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Account identifier - can be a UUID or account URL (URL-encoded)" }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Start date (inclusive) in YYYY-MM-DD format. Defaults to 30 days ago if not provided. Cannot be older than 90 days (730 days for premium users)." }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "End date (inclusive) in YYYY-MM-DD format" } ], "responses": { "200": { "description": "List of daily metrics for the specified account", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "views": { "type": "integer", "description": "Total views for the day" }, "likes": { "type": "integer", "description": "Total likes for the day" }, "comments": { "type": "integer", "description": "Total comments for the day" }, "shares": { "type": "integer", "description": "Total shares for the day" }, "bookmarks": { "type": "integer", "description": "Total bookmarks for the day" }, "engagements": { "type": "integer", "description": "Total engagements for the day (likes + comments + shares + bookmarks)" }, "ads_upload_count": { "type": "integer", "description": "Number of videos uploaded on this day" }, "total_ads": { "type": "integer", "description": "Total number of videos tracked for this account on this day" } } } } } } }, "401": { "description": "Unauthorized – invalid or missing API key" }, "404": { "description": "Not found – account_id not found or not in your organization" } } } }, "/accounts/{account_id}": { "get": { "tags": [ "Account Management" ], "summary": "Get Specific Account", "description": "**All tiers** — Limited/Basic: 1 result with masked metrics. Premium: full access.\n\nRetrieves detailed information about a specific account linked to your organisation in Shortimize via its account_id. This endpoint provides comprehensive data including account metrics, performance indicators, and historical data.\n\nUse this to get in-depth insights into a particular account's performance and engagement.\n\n**Rate Limit:** 5 (limited) / 15 (basic) / 30 (premium) requests per minute", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "Bearer token for authentication", "schema": { "type": "string" }, "example": "Bearer YOUR_KEY_HERE" }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Account identifier - can be a UUID or account URL (URL-encoded)" } ], "operationId": "get_account", "responses": { "200": { "description": "Successful response with detailed information about the specific account", "content": { "application/json": { "schema": { "type": "object", "properties": { "organisation_id": { "type": "string", "format": "uuid", "description": "Unique identifier for your organization" }, "account_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the account" }, "account_link": { "type": "string", "format": "uri", "description": "URL of the social media account" }, "username": { "type": "string", "description": "Username of the account. May carry a '~' disambiguation suffix ('handle~') for Facebook accounts: Facebook permits two genuinely different profiles to share one display handle, and the suffix keeps their stats separate. Treat the full string as canonical in API calls; strip everything from '~' onward for display." }, "platform": { "type": "string", "enum": [ "instagram", "tiktok", "youtube" ], "description": "Social media platform of the account" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the account was added to Shortimize" }, "checked_at": { "type": "string", "format": "date-time", "description": "Timestamp of the last data update" }, "removed": { "type": "boolean", "description": "Indicates if the account has been removed from tracking" }, "private": { "type": "boolean", "description": "Indicates if the account is private" }, "empty": { "type": "boolean", "description": "Indicates if the account has no content" }, "bio": { "type": "string", "description": "The bio of the account from the respective platform" }, "link": { "type": "string", "description": "The primary link of the account from the respective platform" }, "latest_followers_count": { "type": [ "integer", "null" ], "description": "Most recent follower count, null if not available" }, "latest_following_count": { "type": [ "integer", "null" ], "description": "Most recent following count, null if not available" }, "tracking_type": { "type": "string", "description": "Type of tracking applied to this account" }, "mean_views": { "type": "number", "description": "Average number of views across tracked videos" }, "most_viewed": { "type": "integer", "description": "Highest number of views for a single video" }, "median_views": { "type": "number", "description": "Median number of views across tracked videos" }, "median_views_non_zero": { "type": "number", "description": "Median number of views across tracked videos (videos with greater than 0 views)" }, "median_likes": { "type": "number", "description": "Median number of likes across tracked videos" }, "percent_outperform_10x": { "type": "number", "description": "Percentage of videos outperforming by 10x" }, "percent_outperform_25x": { "type": "number", "description": "Percentage of videos outperforming by 25x" }, "last_uploaded_at": { "type": "string", "format": "date", "description": "Date of the last uploaded video" }, "total_videos_tracked": { "type": "integer", "description": "Total number of videos being tracked" }, "total_views": { "type": "integer", "description": "Total views across all tracked videos" }, "total_likes": { "type": "integer", "description": "Total likes across all tracked videos" }, "total_comments": { "type": "integer", "description": "Total comments across all tracked videos" }, "total_bookmarks": { "type": "integer", "description": "Total bookmarks across all tracked videos" }, "total_shares": { "type": "integer", "description": "Total shares across all tracked videos" }, "total_engagement": { "type": "integer", "description": "Total engagement across all tracked videos (likes + comments + shares + bookmarks)" }, "label_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Array of collection/label IDs associated with the account" }, "label_names": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Array of collection/label names associated with the account" } } } } } }, "401": { "description": "Unauthorized - Invalid API key" }, "404": { "description": "Not Found - Account not found" }, "429": { "description": "Rate limit exceeded. Wait the number of seconds given in the Retry-After header, then retry.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Whole seconds to wait before retrying. This is the time left in the current window, not a fixed minute, so a request rejected near the end of a window gets a short wait. Always at least 1." }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed per minute for this API key." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets. Same value as Retry-After." } } } } }, "delete": { "tags": [ "Account Management" ], "summary": "Stop Tracking Account By ID", "description": "Stop tracking an account linked to your organisation via its account_id.\n\nUse this to pause tracking when you want to stop monitoring an account's performance or remove it from your active tracking portfolio.\n\n**Rate Limit:** 5 (limited) / 15 (basic) / 120 (premium) requests per minute", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "Bearer token for authentication", "schema": { "type": "string" }, "example": "Bearer YOUR_KEY_HERE" }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The UUID of the account to stop tracking" } ], "operationId": "stop_tracking_account_by_id", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message confirming the operation", "example": "Successfully stopped tracking account." } } } } } }, "400": { "description": "Bad request - missing or invalid account ID" }, "500": { "description": "Internal server error" } } } }, "/accounts/{account_id}/videos": { "get": { "tags": [ "Video Management" ], "summary": "Get All Videos Linked To Account", "description": "**All tiers** — Limited/Basic: 1 result with masked metrics. Premium: full access.\n\nRetrieves a list of all videos tracked by your organization in Shortimize linked to a specific account. This endpoint provides detailed information about each video, including engagement metrics, content details, and historical performance data.\n\nUse this to get a comprehensive view of your video advertisement portfolio and their performance across different platforms.\n\n**Rate Limit:** 5 (limited) / 15 (basic) / 30 (premium) requests per minute", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "Bearer token for authentication", "schema": { "type": "string" }, "example": "Bearer YOUR_KEY_HERE" }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Account identifier - can be a UUID or account URL (URL-encoded)" }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Filter videos uploaded on or after this date (inclusive, YYYY-MM-DD)" }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Filter videos uploaded on or before this date (inclusive, YYYY-MM-DD)" }, { "in": "query", "name": "paginated", "schema": { "type": "boolean", "default": false }, "description": "Set to true to receive paginated response with {data, pagination} format instead of raw array" }, { "in": "query", "name": "page", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "Page number for pagination (requires paginated=true)" }, { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 5000, "minimum": 1, "maximum": 5000 }, "description": "Number of items to return per page" }, { "in": "query", "name": "order_by", "schema": { "type": "string", "default": "uploaded_at" }, "description": "Field to order results by" }, { "in": "query", "name": "order_direction", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] }, "description": "Direction of ordering (ascending or descending)" } ], "operationId": "get_videos_linked_to_account", "responses": { "200": { "description": "Successful response with a list of videos and their detailed information", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "organisation_id": { "type": "string", "format": "uuid", "description": "Unique identifier for your organization" }, "ad_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the video" }, "username": { "type": "string", "description": "Username of the account that posted the video. May carry a '~' disambiguation suffix ('handle~') for Facebook accounts: Facebook permits two genuinely different profiles to share one display handle, and the suffix keeps their stats separate. Treat the full string as canonical in API calls; strip everything from '~' onward for display." }, "platform": { "type": "string", "enum": [ "tiktok", "instagram", "youtube" ], "description": "Social media platform where the video is posted" }, "ad_link": { "type": "string", "format": "uri", "description": "URL of the video" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the video was added to Shortimize" }, "removed": { "type": "boolean", "description": "Indicates if the video has been removed from tracking" }, "linked_account_id": { "type": "string", "format": "uuid", "description": "Unique identifier of the linked account" }, "uploaded_at": { "type": [ "string", "null" ], "format": "date", "description": "Date when the video was uploaded to the platform" }, "song_name": { "type": [ "string", "null" ], "description": "Name of the song used in the video" }, "song_link": { "type": [ "string", "null" ], "description": "Link to the song used in the video" }, "video_length": { "type": [ "string", "null" ], "description": "Length of the video in seconds" }, "title": { "type": "string", "description": "Title or caption of the video" }, "not_safe": { "type": "boolean", "description": "Indicates if the video is flagged as not safe for work" }, "private": { "type": "boolean", "description": "Indicates if the video is set to private" }, "hidden_stats": { "type": "boolean", "description": "Indicates if the video's statistics are hidden" }, "latest_views": { "type": "integer", "description": "Most recent count of views" }, "latest_likes": { "type": "integer", "description": "Most recent count of likes" }, "latest_comments": { "type": "integer", "description": "Most recent count of comments" }, "latest_bookmarks": { "type": "integer", "description": "Most recent count of bookmarks" }, "latest_shares": { "type": "integer", "description": "Most recent count of shares" }, "latest_engagement": { "type": [ "integer", "null" ], "description": "Most recent count of total engagement" }, "latest_updated_at": { "type": "string", "format": "date-time", "description": "Timestamp of the most recent update to the video's statistics" }, "outlier_multiplier": { "type": "number", "description": "Multiplier indicating how much this video outperforms the account's median" }, "increase_1d": { "type": "number", "description": "Percentage increase in views over the last day" }, "increase_7d": { "type": "number", "description": "Percentage increase in views over the last 7 days" }, "ad_info_shop": { "type": "boolean", "description": "Whether the ad is a tiktok shop ad or not. Only valid for Tiktok videos." }, "label_ids": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" }, "description": "Array of collection/label IDs associated with the video" }, "label_names": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Array of collection/label names associated with the video" } } } } } } }, "401": { "description": "Unauthorized - Invalid API key" }, "404": { "description": "No results found for the account ID and your current organisation" }, "429": { "description": "Rate limit exceeded. Wait the number of seconds given in the Retry-After header, then retry.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Whole seconds to wait before retrying. This is the time left in the current window, not a fixed minute, so a request rejected near the end of a window gets a short wait. Always at least 1." }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed per minute for this API key." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets. Same value as Retry-After." } } } } } }, "/total/videos": { "get": { "tags": [ "Statistics" ], "summary": "Total Videos", "description": "Retrieves the total count of videos being tracked by your organization in Shortimize.\n\nThis endpoint provides a quick snapshot of your video monitoring volume across all tracked accounts and platforms. \nUse this to monitor your video tracking usage, manage quotas, and understand the scale of your video performance tracking operations.\n\n**Rate Limit:** 5 (limited) / 15 (basic) / 30 (premium) requests per minute", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "Bearer token for authentication", "schema": { "type": "string" }, "example": "Bearer YOUR_KEY_HERE" } ], "operationId": "total_videos", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "video_count": { "type": "integer", "example": 150, "description": "Total number of videos being tracked" } }, "required": [ "video_count" ] } } } }, "500": { "description": "Internal server error" } } } }, "/total/accounts": { "get": { "tags": [ "Statistics" ], "summary": "Total Accounts", "description": "Retrieves the total number of accounts currently being tracked by your organization in Shortimize.\n\nThis provides a quick overview of your account monitoring scope and helps manage your tracking capacity. \nUse this to track your account monitoring usage, plan capacity, and make informed decisions about account tracking allocation across your campaigns.\n\n**Rate Limit:** 5 (limited) / 15 (basic) / 30 (premium) requests per minute", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "Bearer token for authentication", "schema": { "type": "string" }, "example": "Bearer YOUR_KEY_HERE" } ], "operationId": "total_accounts", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "account_count": { "type": "integer", "example": 25, "description": "Total number of accounts being tracked" } }, "required": [ "account_count" ] } } } }, "500": { "description": "Internal server error" } } } }, "/refresh/accounts/": { "post": { "tags": [ "Data Operations" ], "summary": "Refresh Account Data", "description": "Refresh an account, if it wasn't updated in the last 4 hours.\n\n**Rate Limit:** 5 (limited) / 15 (basic) / 30 (premium) requests per minute", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "Bearer token for authentication", "schema": { "type": "string" }, "example": "Bearer YOUR_KEY_HERE" }, { "name": "content-type", "in": "header", "required": true, "description": "should be set to `application/json`", "schema": { "type": "string", "enum": [ "application/json" ] } } ], "operationId": "refresh_account_data", "x-internal": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "link" ], "properties": { "link": { "type": "string", "description": "The URL or ID (UUID) of the account to refresh" } } } } } }, "responses": { "200": { "description": "Successfully scheduled account refresh", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad request - invalid account link", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message", "example": "Invalid account link. Please enter a valid full TikTok, Instagram, or YouTube account URL." } } } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds given in the Retry-After header, then retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Rate limit error message", "example": "Rate limit exceeded. Please try again later." } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Whole seconds to wait before retrying. This is the time left in the current window, not a fixed minute, so a request rejected near the end of a window gets a short wait. Always at least 1." }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed per minute for this API key." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets. Same value as Retry-After." } } } } } }, "/refresh/videos/": { "post": { "tags": [ "Data Operations" ], "summary": "Refresh Video Data", "description": "Refresh a video, if it wasn't updated in the last 4 hours.\n\n**Rate Limit:** 5 (limited) / 15 (basic) / 30 (premium) requests per minute", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "Bearer token for authentication", "schema": { "type": "string" }, "example": "Bearer YOUR_KEY_HERE" }, { "name": "content-type", "in": "header", "required": true, "description": "should be set to `application/json`", "schema": { "type": "string", "enum": [ "application/json" ] } } ], "operationId": "refresh_video_data", "x-internal": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "link" ], "properties": { "link": { "type": "string", "description": "The URL or ID (UUID) of the video to refresh" } } } } } }, "responses": { "200": { "description": "Successfully scheduled video refresh", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad request - invalid video link", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message", "example": "Invalid video link. Please enter a valid full TikTok, Instagram, or YouTube video URL." } } } } } }, "429": { "description": "Rate limit exceeded. Wait the number of seconds given in the Retry-After header, then retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Rate limit error message", "example": "Rate limit exceeded. Please try again later." } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Whole seconds to wait before retrying. This is the time left in the current window, not a fixed minute, so a request rejected near the end of a window gets a short wait. Always at least 1." }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed per minute for this API key." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets. Same value as Retry-After." } } } } } }, "/collections": { "get": { "tags": [ "Collection Management" ], "operationId": "get_all_collections", "summary": "Get All Collections", "description": "**All tiers** — Limited/Basic: 1 result with masked metrics. Premium: full access.\n\nRetrieves all collections linked to your organisation. Collections are used to organize and group accounts and videos for easier management.\n\n**Rate Limit:** 5 (limited) / 15 (basic) / 30 (premium) requests per minute", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "Bearer token for authentication", "schema": { "type": "string" }, "example": "Bearer YOUR_KEY_HERE" }, { "name": "parent_id", "in": "query", "description": "Filter collections by parent ID. Use 'null' for root-level collections only.", "required": false, "schema": { "type": "string" } }, { "name": "include_children", "in": "query", "description": "Include child collections in the response", "required": false, "schema": { "type": "boolean", "default": false } }, { "in": "query", "name": "paginated", "schema": { "type": "boolean", "default": false }, "description": "Set to true to receive paginated response with {data, pagination} format instead of {data, count}" }, { "in": "query", "name": "page", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "Page number for pagination (requires paginated=true)" }, { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 5000, "minimum": 1, "maximum": 5000 }, "description": "Number of items to return per page" }, { "in": "query", "name": "order_by", "schema": { "type": "string", "default": "created_at" }, "description": "Field to order results by" }, { "in": "query", "name": "order_direction", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] }, "description": "Direction of ordering (ascending or descending)" } ], "responses": { "200": { "description": "Successful response with a list of collections", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the collection" }, "name": { "type": "string", "description": "Collection name" }, "organisation_id": { "type": "string", "format": "uuid", "description": "Organisation that owns this collection" }, "parent_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Parent collection ID for nested collections" }, "access": { "type": "string", "enum": [ "private", "public", "protected" ], "description": "Access level for the collection" }, "hash": { "type": [ "string", "null" ], "description": "Share hash for public/protected collections" }, "display_settings": { "type": [ "object", "null" ], "description": "Display configuration for public collections" }, "created_by": { "type": "string", "format": "uuid", "description": "User who created the collection" }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "hashtags": { "type": "array", "items": { "type": "string" }, "description": "Hashtags associated with this collection" } } } }, "count": { "type": "integer", "description": "Number of collections returned" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "403": { "description": "Forbidden - Insufficient permissions" } } }, "post": { "tags": [ "Collection Management" ], "operationId": "create_collection", "summary": "Create Collection", "description": "Creates a new collection for organizing accounts and videos.\n\n**Rate Limit:** 5 (limited) / 15 (basic) / 30 (premium) requests per minute", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "Bearer token for authentication", "schema": { "type": "string" }, "example": "Bearer YOUR_KEY_HERE" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Collection name", "maxLength": 100 }, "parent_id": { "type": "string", "format": "uuid", "description": "Optional parent collection ID for nested collections" }, "access": { "type": "string", "enum": [ "private", "public", "protected" ], "default": "private", "description": "Access level for the collection" } } } } } }, "responses": { "201": { "description": "Collection created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "organisation_id": { "type": "string", "format": "uuid" }, "access": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Bad request - Invalid input" }, "409": { "description": "Conflict - Collection with this name already exists" } } } }, "/collections/{collection_id}": { "get": { "tags": [ "Collection Management" ], "operationId": "get_collection", "summary": "Get Collection", "description": "**All tiers** — Limited/Basic: 1 result with masked metrics. Premium: full access.\n\nRetrieves a specific collection by ID.\n\n**Rate Limit:** 5 (limited) / 15 (basic) / 30 (premium) requests per minute", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer YOUR_KEY_HERE" }, { "name": "collection_id", "in": "path", "required": true, "description": "The unique identifier of the collection", "schema": { "type": "string", "format": "uuid" } }, { "name": "include_counts", "in": "query", "description": "Include video and account counts", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Collection details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "organisation_id": { "type": "string", "format": "uuid" }, "parent_id": { "type": [ "string", "null" ] }, "access": { "type": "string" }, "hash": { "type": [ "string", "null" ] }, "display_settings": { "type": [ "object", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "hashtags": { "type": "array", "items": { "type": "string" } }, "video_count": { "type": "integer", "description": "Only if include_counts=true" }, "account_count": { "type": "integer", "description": "Only if include_counts=true" } } } } } }, "404": { "description": "Collection not found" } } }, "patch": { "tags": [ "Collection Management" ], "operationId": "update_collection", "summary": "Update Collection", "description": "Updates a collection's properties.\n\n**Rate Limit:** 5 (limited) / 15 (basic) / 30 (premium) requests per minute", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer YOUR_KEY_HERE" }, { "name": "collection_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "parent_id": { "type": [ "string", "null" ], "format": "uuid" }, "access": { "type": "string", "enum": [ "private", "public", "protected" ] }, "password": { "type": "string", "minLength": 8, "description": "Password for protected collections" }, "display_settings": { "type": "object", "description": "Display settings for public collections" } } } } } }, "responses": { "200": { "description": "Collection updated successfully" }, "400": { "description": "Bad request" }, "404": { "description": "Collection not found" }, "409": { "description": "Conflict - Name already exists" } } }, "delete": { "tags": [ "Collection Management" ], "operationId": "delete_collection", "summary": "Delete Collection", "description": "Deletes a collection. This will also remove all associations with accounts and videos.\n\n**Rate Limit:** 5 (limited) / 15 (basic) / 30 (premium) requests per minute", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer YOUR_KEY_HERE" }, { "name": "collection_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "Collection deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "deleted_id": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Collection not found" } } } }, "/collections/{collection_id}/videos": { "get": { "tags": [ "Collection Management" ], "operationId": "get_collection_videos", "summary": "Get Collection Videos", "description": "**All tiers** — Limited/Basic: 1 result with masked metrics. Premium: full access.\n\nRetrieves all videos in a collection with pagination.\n\n**Rate Limit:** 5 (limited) / 15 (basic) / 30 (premium) requests per minute", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer YOUR_KEY_HERE" }, { "name": "collection_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "paginated", "schema": { "type": "boolean", "default": false }, "description": "Set to true to receive paginated response with {data, pagination} format instead of raw array" }, { "name": "page", "in": "query", "description": "Page number (default: 1)", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "description": "Items per page (default: 100, max: 5000)", "schema": { "type": "integer", "default": 100, "maximum": 5000 } }, { "name": "order_by", "in": "query", "description": "Field to order by", "schema": { "type": "string", "default": "created_at" } }, { "name": "order_direction", "in": "query", "description": "Order direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } } ], "responses": { "200": { "description": "List of videos in the collection", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } }, "pagination": { "type": "object", "properties": { "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "total_pages": { "type": "integer" } } } } } } } }, "404": { "description": "Collection not found" } } }, "post": { "tags": [ "Collection Management" ], "operationId": "add_videos_to_collection", "summary": "Add Videos to Collection", "description": "Adds one or more videos to a collection.\n\n**Rate Limit:** 5 (limited) / 15 (basic) / 30 (premium) requests per minute", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer YOUR_KEY_HERE" }, { "name": "collection_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "video_ids" ], "properties": { "video_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100, "description": "Array of video IDs to add to the collection. Between 1 and 100 of them - an empty list is rejected." } } } } } }, "responses": { "200": { "description": "Videos added successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "collection_id": { "type": "string" }, "videos_added": { "type": "integer" } } } } } }, "400": { "description": "Bad request" }, "404": { "description": "Collection not found" } } }, "delete": { "tags": [ "Collection Management" ], "operationId": "remove_videos_from_collection", "summary": "Remove Videos from Collection", "description": "Removes one or more videos from a collection.\n\n**Rate Limit:** 5 (limited) / 15 (basic) / 30 (premium) requests per minute", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer YOUR_KEY_HERE" }, { "name": "collection_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "video_ids" ], "properties": { "video_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100, "description": "Array of video IDs to remove from the collection. Between 1 and 100 of them - an empty list is rejected." } } } } } }, "responses": { "200": { "description": "Videos removed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "collection_id": { "type": "string" }, "videos_removed": { "type": "integer" } } } } } }, "400": { "description": "Bad request" }, "404": { "description": "Collection not found" } } } }, "/collections/{collection_id}/accounts": { "get": { "tags": [ "Collection Management" ], "operationId": "get_collection_accounts", "summary": "Get Collection Accounts", "description": "**All tiers** — Limited/Basic: 1 result with masked metrics. Premium: full access.\n\nRetrieves all accounts in a collection with pagination.\n\n**Rate Limit:** 5 (limited) / 15 (basic) / 30 (premium) requests per minute", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer YOUR_KEY_HERE" }, { "name": "collection_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "paginated", "schema": { "type": "boolean", "default": false }, "description": "Set to true to receive paginated response with {data, pagination} format instead of raw array" }, { "name": "page", "in": "query", "description": "Page number (default: 1)", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "description": "Items per page (default: 100, max: 5000)", "schema": { "type": "integer", "default": 100, "maximum": 5000 } }, { "name": "order_by", "in": "query", "description": "Field to order by", "schema": { "type": "string", "default": "created_at" } }, { "name": "order_direction", "in": "query", "description": "Order direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } } ], "responses": { "200": { "description": "List of accounts in the collection", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } }, "pagination": { "type": "object", "properties": { "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "total_pages": { "type": "integer" } } } } } } } }, "404": { "description": "Collection not found" } } }, "post": { "tags": [ "Collection Management" ], "operationId": "add_accounts_to_collection", "summary": "Add Accounts to Collection", "description": "Adds one or more accounts to a collection.\n\n**Rate Limit:** 5 (limited) / 15 (basic) / 30 (premium) requests per minute", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer YOUR_KEY_HERE" }, { "name": "collection_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "account_ids" ], "properties": { "account_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100, "description": "Array of account IDs to add to the collection. Between 1 and 100 of them - an empty list is rejected." } } } } } }, "responses": { "200": { "description": "Accounts added successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "collection_id": { "type": "string" }, "accounts_added": { "type": "integer" } } } } } }, "400": { "description": "Bad request" }, "404": { "description": "Collection not found" } } }, "delete": { "tags": [ "Collection Management" ], "operationId": "remove_accounts_from_collection", "summary": "Remove Accounts from Collection", "description": "Removes one or more accounts from a collection.\n\n**Rate Limit:** 5 (limited) / 15 (basic) / 30 (premium) requests per minute", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer YOUR_KEY_HERE" }, { "name": "collection_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "account_ids" ], "properties": { "account_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100, "description": "Array of account IDs to remove from the collection. Between 1 and 100 of them - an empty list is rejected." } } } } } }, "responses": { "200": { "description": "Accounts removed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "collection_id": { "type": "string" }, "accounts_removed": { "type": "integer" } } } } } }, "400": { "description": "Bad request" }, "404": { "description": "Collection not found" } } } }, "/mcp": { "post": { "tags": [ "Integration" ], "operationId": "mcp", "summary": "Shortimize MCP Server", "description": "MCP Server to be used with all the routes available.\n\n**Rate Limit:** 5 (limited) / 15 (basic) / 30 (premium) requests per minute" } } }, "x-tagGroups": [ { "name": "Core Resources", "tags": [ "Account Management", "Video Management", "Collection Management", "Organisation Management" ] }, { "name": "Analytics", "tags": [ "Statistics", "Data Operations" ] }, { "name": "System", "tags": [ "Authentication", "Integration" ] } ], "tags": [ { "name": "Account Management", "description": "Manage and track social media accounts", "x-zudoku-collapsed": false }, { "name": "Video Management", "description": "Manage and track video content", "x-zudoku-collapsed": false }, { "name": "Collection Management", "description": "Organize accounts and videos into collections", "x-zudoku-collapsed": false }, { "name": "Statistics", "description": "Get aggregated statistics and counts" }, { "name": "Data Operations", "description": "Refresh and update tracked data" }, { "name": "Authentication", "description": "API authentication and validation" }, { "name": "Integration", "description": "MCP server and integration endpoints" }, { "name": "Organisation Management", "description": "Organisation-wide metrics and historical data" } ] }