{ "openapi": "3.1.0", "info": { "title": "CreatorAudit API v2", "summary": "Public REST API for tracking creators, accounts, videos, and analytics.", "description": "The **CreatorAudit v2 API** tracks Instagram and TikTok creators, accounts, and\ntheir content, and serves the engagement analytics computed from them.\n\n### Authentication & scopes\n\nSend your organization API key as a bearer token on every request:\n\n```\nAuthorization: Bearer \n```\n\nKeys are scoped to a single organization; every response is limited to the data\nthat organization owns. Missing or invalid credentials return `401`; an inactive\nkey or subscription returns `403`.\n\nEach key carries a set of **scopes** — `read`, `write`, and `admin` — and keys\nare issued with all three by default. Read endpoints (`GET`) require no special\nscope; mutating endpoints (`POST`/`PATCH`/`PUT`/`DELETE`) require the `write`\nscope (`admin` implies `write` implies `read`). A key lacking the required scope\ngets `403` with `code: INSUFFICIENT_SCOPE`.\n\n### Response envelope\n\nSuccessful responses are wrapped in a consistent envelope:\n\n- **Single resource** — `{ \"data\": { ... } }`\n- **Collection** — `{ \"data\": [ ... ], \"pagination\": { ... }, \"filters\": { ... } }`\n- **Collection with metadata** — `{ \"data\": ..., \"meta\": { ... } }`\n\n`pagination` carries `next_cursor`, `has_next`, `limit`, and (when requested)\n`total_count`. `filters` echoes the filter/sort that produced the page.\n\n### Pagination\n\nList endpoints use opaque **cursor** pagination. Pass `limit` (1–200) and the\n`pagination.next_cursor` from the previous page as `cursor` to fetch the next\npage. `pagination.has_next` is `false` on the final page. A cursor is bound to\nthe exact filter and sort combination it was issued for — reusing it under a\ndifferent filter/sort returns `422`. Pass `include_total=true` to also receive\n`pagination.total_count` (adds one COUNT query). List responses also carry an\nRFC 8288 `Link` header with `rel=\"first\"` and (when more pages exist)\n`rel=\"next\"`.\n\n### Caching\n\n`GET` responses carry a strong `ETag` and `Cache-Control: private, no-cache`.\nSend the value back as `If-None-Match` on a follow-up request; if the\nrepresentation is unchanged the API replies `304 Not Modified` with an empty\nbody, saving the re-download.\n\n### Rate limits\n\nRequests are rate limited per API key. Every **authenticated** response includes\n`X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` (a Unix\ntimestamp); the unauthenticated `GET /health` and `GET /meta` are not limited\nand omit them. Exceeding the limit returns `429` with `code: RATE_LIMITED` and a\n`Retry-After` header (seconds to wait).\n\n### Account quota\n\nAn organization may set an optional cap on the number of accounts it tracks. By\ndefault there is **no cap** (unlimited). When a cap is set and reached,\n`POST /accounts` returns `403` with `code: QUOTA_EXCEEDED`.\n\n### Content negotiation\n\nThe API only produces JSON. A request whose `Accept` header cannot be satisfied\nwith JSON returns `406` (`code: NOT_ACCEPTABLE`). A write request whose body is\nnot `application/json` returns `415` (`code: UNSUPPORTED_MEDIA_TYPE`).\n\n### Errors\n\nErrors follow **RFC 9457 Problem Details** (`application/problem+json`):\n\n```json\n{\n \"type\": \"urn:creatoraudit:error:not-found\",\n \"title\": \"Not Found\",\n \"status\": 404,\n \"detail\": \"Account not found.\",\n \"code\": \"NOT_FOUND\",\n \"instance\": \"/v2/accounts/{id}\",\n \"request_id\": \"8f1c…\"\n}\n```\n\nThe `code` is the stable machine identifier; `type` is an RFC 9457 URN.\nValidation failures (`422`) additionally carry an `errors` array of\n`{ field, message }` entries. The full set of machine `code`s:\n\n| HTTP | `code` | Meaning |\n| ---- | ------ | ------- |\n| 400 | `BAD_REQUEST` | Malformed request. |\n| 401 | `UNAUTHORIZED` | Missing or invalid API key. |\n| 403 | `FORBIDDEN` | Inactive key/subscription. |\n| 403 | `INSUFFICIENT_SCOPE` | Key lacks the required scope. |\n| 403 | `QUOTA_EXCEEDED` | Account quota reached. |\n| 404 | `NOT_FOUND` | Resource not found in your org. |\n| 406 | `NOT_ACCEPTABLE` | `Accept` not satisfiable as JSON. |\n| 409 | `CONFLICT` | State conflict (e.g. duplicate). |\n| 415 | `UNSUPPORTED_MEDIA_TYPE` | Write body is not JSON. |\n| 422 | `VALIDATION_ERROR` | Request failed validation. |\n| 429 | `RATE_LIMITED` | Rate limit exceeded. |\n| 500 | `INTERNAL_ERROR` | Unexpected server error. |\n| 502 | `UPSTREAM_ERROR` | Upstream provider error. |\n| 503 | `SERVICE_UNAVAILABLE` | Temporarily unavailable; retry. |\n\n### Idempotency\n\n`POST` create endpoints accept an optional `Idempotency-Key` header so a retried\nrequest returns the original result instead of creating a duplicate. On success\na `201` carries a `Location` header pointing at the new resource.\n\n### Response headers\n\nEvery response echoes `X-Request-ID` (also surfaced as `request_id` in error\nbodies) so a call can be correlated with its server-side event. Collections add\n`Link`; `GET`s add `ETag`/`Cache-Control`; authenticated responses add\n`X-RateLimit-*`; `429`/`503` add `Retry-After`; `201` creates add `Location`.\n", "contact": { "name": "CreatorAudit Support", "url": "https://creatoraudit.com/", "email": "support@creatoraudit.com" }, "license": { "name": "Proprietary — © CreatorAudit" }, "version": "2.0.0", "x-api-stability": "current" }, "servers": [ { "url": "https://api.creatoraudit.com/v2", "description": "Production" } ], "paths": { "/meta": { "get": { "tags": [ "System" ], "summary": "API surface metadata", "description": "Unauthenticated discovery document for the v2 surface — its version,\nlifecycle status, and docs/OpenAPI links. Side-effect-free.", "operationId": "v2_meta", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Single_V2Meta_" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag).", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } } } } }, "/whoami": { "get": { "tags": [ "System" ], "summary": "Identify the calling API key", "description": "Echo the authenticated caller's organization and API-key name — useful\nfor debugging which credential a tool is using. No extra query: reads the\n`key_data` the auth dependency already resolved.", "operationId": "whoami", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Single_WhoAmI_" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag).", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/health": { "get": { "tags": [ "System" ], "summary": "Liveness check", "description": "Unauthenticated liveness probe.\n\nReturns `{\"status\": \"ok\"}` whenever the API process is serving\nrequests. Requires no API key, performs no database access, and has\nno side effects, so load balancers, uptime monitors, and container\nliveness/readiness probes can call it freely.", "operationId": "health_check", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Single_HealthPayload_" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag).", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } } } } }, "/accounts/metrics": { "post": { "tags": [ "Analytics" ], "summary": "Batch windowed account metrics", "description": "Windowed engagement totals for a batch of entities.\n\nFor each requested id, returns the SUM of `views`, `plays`, `likes`,\n`comments`, `shares`, and the derived `engagement` (likes+comments+shares)\nover the resolved `[start_date, end_date]` window. Read-only. Ids your\norganization does not track are omitted from `data` and listed under\n`meta.not_found`. Response shape:\n\n```\n{ \"data\": { \"\": { \"views\": 1234, \"plays\": 1200, \"likes\": 56,\n \"comments\": 7, \"shares\": 8, \"engagement\": 71 } },\n \"meta\": { \"period\": \"30d\", \"start_date\": \"...\", \"end_date\": \"...\",\n \"days\": 30, \"not_found\": [\"\"] } }\n```\n\nNote: TikTok has no separate plays count, so a TikTok entity's `plays`\nequals its `views`. There is no `impressions` metric — the platform tracks\nviews and plays only.", "operationId": "account_metrics", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountMetricsRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": { "type": "object", "properties": { "views": { "type": "integer" }, "plays": { "type": "integer" }, "likes": { "type": "integer" }, "comments": { "type": "integer" }, "shares": { "type": "integer" }, "engagement": { "type": "integer" } } } }, "meta": { "type": "object" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/videos/metrics": { "post": { "tags": [ "Analytics" ], "summary": "Batch windowed video metrics", "description": "Windowed engagement totals for a batch of entities.\n\nFor each requested id, returns the SUM of `views`, `plays`, `likes`,\n`comments`, `shares`, and the derived `engagement` (likes+comments+shares)\nover the resolved `[start_date, end_date]` window. Read-only. Ids your\norganization does not track are omitted from `data` and listed under\n`meta.not_found`. Response shape:\n\n```\n{ \"data\": { \"\": { \"views\": 1234, \"plays\": 1200, \"likes\": 56,\n \"comments\": 7, \"shares\": 8, \"engagement\": 71 } },\n \"meta\": { \"period\": \"30d\", \"start_date\": \"...\", \"end_date\": \"...\",\n \"days\": 30, \"not_found\": [\"\"] } }\n```\n\nNote: TikTok has no separate plays count, so a TikTok entity's `plays`\nequals its `views`. There is no `impressions` metric — the platform tracks\nviews and plays only.", "operationId": "video_metrics", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoMetricsRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": { "type": "object", "properties": { "views": { "type": "integer" }, "plays": { "type": "integer" }, "likes": { "type": "integer" }, "comments": { "type": "integer" }, "shares": { "type": "integer" }, "engagement": { "type": "integer" } } } }, "meta": { "type": "object" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/account-videos/metrics": { "post": { "tags": [ "Analytics" ], "summary": "Batch windowed account-video metrics", "description": "Windowed engagement totals for a batch of entities.\n\nFor each requested id, returns the SUM of `views`, `plays`, `likes`,\n`comments`, `shares`, and the derived `engagement` (likes+comments+shares)\nover the resolved `[start_date, end_date]` window. Read-only. Ids your\norganization does not track are omitted from `data` and listed under\n`meta.not_found`. Response shape:\n\n```\n{ \"data\": { \"\": { \"views\": 1234, \"plays\": 1200, \"likes\": 56,\n \"comments\": 7, \"shares\": 8, \"engagement\": 71 } },\n \"meta\": { \"period\": \"30d\", \"start_date\": \"...\", \"end_date\": \"...\",\n \"days\": 30, \"not_found\": [\"\"] } }\n```\n\nNote: TikTok has no separate plays count, so a TikTok entity's `plays`\nequals its `views`. There is no `impressions` metric — the platform tracks\nviews and plays only.\n\nFor account-discovered posts, keyed by internal post/video id.", "operationId": "account_video_metrics", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountVideoMetricsRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": { "type": "object", "properties": { "views": { "type": "integer" }, "plays": { "type": "integer" }, "likes": { "type": "integer" }, "comments": { "type": "integer" }, "shares": { "type": "integer" }, "engagement": { "type": "integer" } } } }, "meta": { "type": "object" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/accounts": { "get": { "tags": [ "Accounts" ], "summary": "List tracked accounts", "description": "List the organization's tracked accounts, newest first by default.\n\nCursor-paginated. Each row carries the account's profile fields and\nits latest engagement metrics, plus the per-account tracking-limit\noverrides (`max_recent_posts_per_account`, `post_lookback_days`) and\ntheir computed `effective_*` values (`null` override = inheriting the\norganization default).", "operationId": "list_accounts", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "description": "Page size (1–200).", "default": 50, "title": "Limit" }, "description": "Page size (1–200)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque `pagination.next_cursor` from the previous page.", "title": "Cursor" }, "description": "Opaque `pagination.next_cursor` from the previous page." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "description": "Legacy signed sort string (e.g. `-added_at`). Prefer `order_by` + `order_direction`, which are validated as enums. Allowed keys: `added_at`, `username`, `last_scrape_time`, `follower_count`, `view_count`, `like_count`, `play_count`.", "default": "-added_at", "title": "Sort" }, "description": "Legacy signed sort string (e.g. `-added_at`). Prefer `order_by` + `order_direction`, which are validated as enums. Allowed keys: `added_at`, `username`, `last_scrape_time`, `follower_count`, `view_count`, `like_count`, `play_count`." }, { "name": "order_by", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "added_at", "username", "last_scrape_time", "follower_count", "view_count", "like_count", "play_count" ], "type": "string" }, { "type": "null" } ], "description": "Field to sort by. Overrides `sort`.", "title": "Order By" }, "description": "Field to sort by. Overrides `sort`." }, { "name": "order_direction", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "asc", "desc" ], "type": "string" }, { "type": "null" } ], "description": "Sort direction (default `desc`). Used with `order_by`.", "title": "Order Direction" }, "description": "Sort direction (default `desc`). Used with `order_by`." }, { "name": "platform", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "instagram", "tiktok" ], "type": "string" }, { "type": "null" } ], "description": "Filter by platform: `instagram` or `tiktok`.", "title": "Platform" }, "description": "Filter by platform: `instagram` or `tiktok`." }, { "name": "is_active", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Filter by tracking state (active vs paused).", "title": "Is Active" }, "description": "Filter by tracking state (active vs paused)." }, { "name": "creator_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Only accounts linked to this creator.", "title": "Creator Id" }, "description": "Only accounts linked to this creator." }, { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by the account's category label.", "title": "Category" }, "description": "Filter by the account's category label." }, { "name": "q", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Case-insensitive substring match against the account's username or display name.", "title": "Q" }, "description": "Case-insensitive substring match against the account's username or display name." }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When true, the response includes `pagination.total_count`. Adds one extra COUNT(*) query — leave off for cheap paging.", "default": false, "title": "Include Total" }, "description": "When true, the response includes `pagination.total_count`. Adds one extra COUNT(*) query — leave off for cheap paging." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AccountResponse" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "filters": { "type": [ "object", "null" ] } }, "required": [ "data", "pagination" ] } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." }, "Link": { "schema": { "type": "string" }, "description": "RFC 8288 pagination links (rel=\"first\"/\"next\")." } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag).", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } } } }, "post": { "tags": [ "Accounts" ], "summary": "Track an account", "description": "Add an Instagram or TikTok account for automated tracking.\n\nCreates a tracking record scoped to your organization and begins\nrefreshing all of the account's posts/videos on the configured\ninterval (default: every 24 hours). The account's profile and most\nrecent posts/videos are fetched in the background as soon as it's\nadded, so followers, totals, and recent content begin populating\nwithin seconds instead of waiting for the first scheduled refresh.\nThe returned ``id`` references this account in all other endpoints.", "operationId": "create_account", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional client-supplied unique key for retry-safe POSTs. Best-effort in-process dedup over a 10-minute window. Multi-replica deployments will need a shared store before this is load-bearing across all writes.", "title": "Idempotency-Key" }, "description": "Optional client-supplied unique key for retry-safe POSTs. Best-effort in-process dedup over a 10-minute window. Multi-replica deployments will need a shared store before this is load-bearing across all writes." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccountRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AccountResponse" } }, "required": [ "data" ] } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Location": { "schema": { "type": "string" }, "description": "URI of the created resource." } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } } } } }, "/accounts/stats": { "get": { "tags": [ "Accounts" ], "summary": "Per-account video stats", "description": "Per-account aggregate stats for every tracked account in the org.\n\nReturns a list of `{account_id, account_videos_count,\nposts_per_day_7d}` rows — one per tracked account in\n`organization_{instagram,tiktok}_accounts`. The web app's Accounts\nlist grid uses this to render the \"Videos Tracked\" column with a\nreal count of org-discovered account videos (instead of the\nplatform-reported lifetime post count, which is frequently 0) and\nthe \"Posting Activity (7d)\" sparkline (replacing the old\nindividual-videos-only count, which excluded account-ingest-\ndiscovered videos).\n\n`posts_per_day_7d` is a 7-element array, oldest day first, with the\nlast element being today's posts. Computed in UTC to match the rest\nof the analytics surface.", "operationId": "list_account_stats", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag).", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/accounts/{account_id}": { "get": { "tags": [ "Accounts" ], "summary": "Get an account", "description": "Retrieve a single tracked account.\n\n`account_id` may be the account UUID or an `@username` (V2R-13). Returns the same fully-enriched shape as the list endpoint\n(profile, latest metrics, and per-account tracking-limit fields). Returns\n`404` if the account does not exist or is not tracked by your organization.", "operationId": "get_account", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Account UUID or @username (V2R-13).", "title": "Account Id" }, "description": "Account UUID or @username (V2R-13)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AccountResponse" } }, "required": [ "data" ] } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag).", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } } } }, "patch": { "tags": [ "Accounts" ], "summary": "Update an account", "description": "Update a tracked account's settings.\n\n`account_id` may be the account UUID or an `@username` (V2R-13). Only the fields you include are changed (partial update). Supports\npausing/resuming tracking (`is_active`), re-categorizing, editing\n`metadata`, changing the `scrape_interval_hours`, linking or unlinking\na `creator_id`, and setting per-account tracking-limit overrides.\nReturns the updated account; `404` if it is not tracked by your\norganization.", "operationId": "update_account", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Account UUID or @username (V2R-13).", "title": "Account Id" }, "description": "Account UUID or @username (V2R-13)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAccountRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AccountResponse" } }, "required": [ "data" ] } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } } } }, "delete": { "tags": [ "Accounts" ], "summary": "Stop tracking an account", "description": "Remove an account from your organization's tracking.\n\n`account_id` may be the account UUID or an `@username` (V2R-13). Soft-deletes the tracking record and stops future refreshes;\npreviously collected analytics are retained. **Idempotent** (RFC 9110\n§9.2.2): returns `204 No Content` whether or not the account was currently\ntracked, so a retried or duplicated delete is not a spurious `404`.", "operationId": "delete_account", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Account UUID or @username (V2R-13).", "title": "Account Id" }, "description": "Account UUID or @username (V2R-13)." } ], "responses": { "204": { "description": "Successful Response", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } } } } }, "/creators/top": { "get": { "tags": [ "Creators" ], "summary": "Top creators leaderboard", "description": "Leaderboard of the top creators by total views over the period.\n\nReturns a collection: `data` is the ranked list of creators (each with\n`id`, `type`, `name`, and aggregate `views`/`engagement`, most-viewed\nfirst) and `meta.period` echoes the window. (V2R-40a: a collection is\nserved under the collection envelope, not the single-resource one.)", "operationId": "top_creators", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "period", "in": "query", "required": false, "schema": { "enum": [ "7d", "30d", "90d" ], "type": "string", "description": "Ranking window.", "default": "7d", "title": "Period" }, "description": "Ranking window." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 25, "minimum": 1, "description": "How many creators.", "default": 10, "title": "Limit" }, "description": "How many creators." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag).", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } } } } }, "/creators": { "get": { "tags": [ "Creators" ], "summary": "List creators", "description": "List the organization's creators, sorted by name.\n\nCursor-paginated. Each row includes a lightweight `accounts_summary`\nroll-up (account count, per-platform breakdown, total followers) so the\nlisting avoids an N-accounts fan-out; hydrate the full account list via\n`/accounts?creator_id=...`.", "operationId": "list_creators", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "description": "Page size (1–200).", "default": 50, "title": "Limit" }, "description": "Page size (1–200)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque `pagination.next_cursor` from the previous page.", "title": "Cursor" }, "description": "Opaque `pagination.next_cursor` from the previous page." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "description": "Legacy signed sort string (e.g. `name` or `-name`). Prefer `order_by` + `order_direction`. Only `name` is supported.", "default": "name", "title": "Sort" }, "description": "Legacy signed sort string (e.g. `name` or `-name`). Prefer `order_by` + `order_direction`. Only `name` is supported." }, { "name": "order_by", "in": "query", "required": false, "schema": { "anyOf": [ { "const": "name", "type": "string" }, { "type": "null" } ], "description": "Field to sort by. Overrides `sort`.", "title": "Order By" }, "description": "Field to sort by. Overrides `sort`." }, { "name": "order_direction", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "asc", "desc" ], "type": "string" }, { "type": "null" } ], "description": "Sort direction (default `asc` for name). Used with `order_by`.", "title": "Order Direction" }, "description": "Sort direction (default `asc` for name). Used with `order_by`." }, { "name": "is_active", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Filter by active vs archived creators.", "title": "Is Active" }, "description": "Filter by active vs archived creators." }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When true, the response includes `pagination.total_count`. Adds one extra COUNT(*) query — leave off for cheap paging.", "default": false, "title": "Include Total" }, "description": "When true, the response includes `pagination.total_count`. Adds one extra COUNT(*) query — leave off for cheap paging." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection_CreatorResponse_" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." }, "Link": { "schema": { "type": "string" }, "description": "RFC 8288 pagination links (rel=\"first\"/\"next\")." } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag).", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } } } }, "post": { "tags": [ "Creators" ], "summary": "Create a creator", "description": "Create a creator to group accounts under for roll-up analytics.\n\nSupply a `name` (and optional `metadata`); link accounts afterwards via\n`PUT /creators/{creator_id}/accounts/{account_id}`. Pass an\n`Idempotency-Key` header to make a retried create return the original\ncreator instead of a duplicate.", "operationId": "create_creator", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional client-supplied unique key for retry-safe POSTs. Best-effort in-process dedup over a 10-minute window. Multi-replica deployments will need a shared store before this is load-bearing across all writes.", "title": "Idempotency-Key" }, "description": "Optional client-supplied unique key for retry-safe POSTs. Best-effort in-process dedup over a 10-minute window. Multi-replica deployments will need a shared store before this is load-bearing across all writes." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCreatorRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Single_CreatorResponse_" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Location": { "schema": { "type": "string" }, "description": "URI of the created resource." } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } } } } }, "/creators/{creator_id}": { "get": { "tags": [ "Creators" ], "summary": "Get a creator", "description": "Retrieve a single creator by its UUID.\n\nReturns the creator with its `accounts_summary` roll-up. Returns `404`\nif the creator does not exist in your organization.", "operationId": "get_creator", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "creator_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Creator UUID.", "title": "Creator Id" }, "description": "Creator UUID." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Single_CreatorResponse_" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag).", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } } } }, "patch": { "tags": [ "Creators" ], "summary": "Update a creator", "description": "Update a creator's `name`, `is_active`, or `metadata`.\n\nPartial update — only the fields you include change. Returns the\nupdated creator; `404` if it does not exist in your organization.", "operationId": "update_creator", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "creator_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Creator UUID.", "title": "Creator Id" }, "description": "Creator UUID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCreatorRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Single_CreatorResponse_" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } } } }, "delete": { "tags": [ "Creators" ], "summary": "Delete a creator", "description": "Delete a creator.\n\nRemoves the creator entity; the accounts that were linked to it remain\ntracked (they are simply no longer grouped). **Idempotent** (RFC 9110\n§9.2.2): returns `204 No Content` whether or not the creator existed,\nso a retried or duplicated delete is not a spurious `404`.", "operationId": "delete_creator", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "creator_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Creator UUID.", "title": "Creator Id" }, "description": "Creator UUID." } ], "responses": { "204": { "description": "Successful Response", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } } } } }, "/creators/{creator_id}/accounts/{account_id}": { "put": { "tags": [ "Creators" ], "summary": "Link an account to a creator", "description": "Link a tracked account to a creator.\n\nPUT-to-create with correct REST semantics (review V2R-06): the first\nlink returns `201 Created` with a `Location` header; re-linking an\naccount already linked to this creator is an idempotent `200 OK`.\nLinking an account already owned by a *different* creator returns\n`409`. Returns the link record; `404` if either the creator or the\naccount does not exist in your organization.", "operationId": "link_account", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "creator_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Creator UUID.", "title": "Creator Id" }, "description": "Creator UUID." }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Tracked account UUID.", "title": "Account Id" }, "description": "Tracked account UUID." } ], "responses": { "200": { "description": "Already linked (idempotent re-link).", "content": { "application/json": { "schema": {} } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "201": { "description": "Link created.", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Location": { "schema": { "type": "string" }, "description": "URI of the created resource." } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } } } }, "delete": { "tags": [ "Creators" ], "summary": "Unlink an account from a creator", "description": "Remove the link between an account and a creator.\n\nThe account stays tracked; it is just no longer grouped under the\ncreator. Returns `204 No Content`; `404` if no such link exists.", "operationId": "unlink_account", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "creator_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Creator UUID.", "title": "Creator Id" }, "description": "Creator UUID." }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Tracked account UUID.", "title": "Account Id" }, "description": "Tracked account UUID." } ], "responses": { "204": { "description": "Successful Response", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } } } } }, "/videos/deltas": { "get": { "tags": [ "Videos" ], "summary": "Batch video engagement deltas", "description": "View-count deltas for many videos over several look-back windows.\n\nFor each requested video, returns the view-count change over each\n`windows` entry (e.g. views gained in the last 1/7/14/30 days), keyed as\n`\"d\"`. Read-only and side-effect-free. Video ids your organization\ndoes not track are omitted from `data` and listed under\n`meta.not_found` (so a zero delta is never confused with a foreign id).\nResponse shape:\n\n```\n{ \"data\": { \"\": { \"1d\": 1234, \"7d\": 5678, \"30d\": 9012 } },\n \"meta\": { \"windows\": [1, 7, 14, 30], \"video_count\": ,\n \"not_found\": [\"\"] } }\n```", "operationId": "video_deltas_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "video_ids", "in": "query", "required": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 200, "description": "Repeated `video_ids` query param — 1–200 video UUIDs.", "title": "Video Ids" }, "description": "Repeated `video_ids` query param — 1–200 video UUIDs." }, { "name": "windows", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "integer" }, "description": "Repeated `windows` query param — days (1–365), up to 10.", "default": [ 1, 7, 14, 30 ], "title": "Windows" }, "description": "Repeated `windows` query param — days (1–365), up to 10." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag).", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } } } }, "post": { "tags": [ "Videos" ], "summary": "Batch video engagement deltas", "description": "View-count deltas for many videos over several look-back windows.\n\nFor each requested video, returns the view-count change over each\n`windows` entry (e.g. views gained in the last 1/7/14/30 days), keyed as\n`\"d\"`. Read-only and side-effect-free. Video ids your organization\ndoes not track are omitted from `data` and listed under\n`meta.not_found` (so a zero delta is never confused with a foreign id).\nResponse shape:\n\n```\n{ \"data\": { \"\": { \"1d\": 1234, \"7d\": 5678, \"30d\": 9012 } },\n \"meta\": { \"windows\": [1, 7, 14, 30], \"video_count\": ,\n \"not_found\": [\"\"] } }\n```\n\nUses `POST` so large `video_ids` batches travel in the body.", "operationId": "video_deltas", "security": [ { "HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoDeltasRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } } } } }, "/videos": { "get": { "tags": [ "Videos" ], "summary": "List tracked videos", "description": "List the organization's individually tracked posts and videos.\n\nCovers Instagram posts and TikTok videos added one-by-one via\n`POST /videos`. Cursor-paginated, newest first by default. Each row\ncarries content fields plus the latest engagement metrics and account\ncontext (`account_id` is the org-scoped author account, `null` when the\nauthor isn't tracked by your org). To list videos discovered from a\ntracked account instead, use `/account-videos`.", "operationId": "list_videos", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "description": "Page size (1–200).", "default": 50, "title": "Limit" }, "description": "Page size (1–200)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque `pagination.next_cursor` from the previous page.", "title": "Cursor" }, "description": "Opaque `pagination.next_cursor` from the previous page." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "description": "Legacy signed sort string (e.g. `-added_at`). Prefer `order_by` + `order_direction`. Allowed keys: `added_at`, `create_time`, `view_count`, `like_count`, `play_count`.", "default": "-added_at", "title": "Sort" }, "description": "Legacy signed sort string (e.g. `-added_at`). Prefer `order_by` + `order_direction`. Allowed keys: `added_at`, `create_time`, `view_count`, `like_count`, `play_count`." }, { "name": "order_by", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "added_at", "create_time", "view_count", "like_count", "play_count" ], "type": "string" }, { "type": "null" } ], "description": "Field to sort by. Overrides `sort`.", "title": "Order By" }, "description": "Field to sort by. Overrides `sort`." }, { "name": "order_direction", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "asc", "desc" ], "type": "string" }, { "type": "null" } ], "description": "Sort direction (default `desc`). Used with `order_by`.", "title": "Order Direction" }, "description": "Sort direction (default `desc`). Used with `order_by`." }, { "name": "platform", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "instagram", "tiktok" ], "type": "string" }, { "type": "null" } ], "description": "Filter by platform: `instagram` or `tiktok`.", "title": "Platform" }, "description": "Filter by platform: `instagram` or `tiktok`." }, { "name": "is_active", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Filter by tracking state (active vs paused).", "title": "Is Active" }, "description": "Filter by tracking state (active vs paused)." }, { "name": "account_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Only videos whose author is this tracked account.", "title": "Account Id" }, "description": "Only videos whose author is this tracked account." }, { "name": "q", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Case-insensitive substring match against the video description.", "title": "Q" }, "description": "Case-insensitive substring match against the video description." }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When true, the response includes `pagination.total_count`. Adds one extra COUNT(*) query — leave off for cheap paging.", "default": false, "title": "Include Total" }, "description": "When true, the response includes `pagination.total_count`. Adds one extra COUNT(*) query — leave off for cheap paging." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection_VideoResponse_" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." }, "Link": { "schema": { "type": "string" }, "description": "RFC 8288 pagination links (rel=\"first\"/\"next\")." } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag).", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } } } }, "post": { "tags": [ "Videos" ], "summary": "Track a video", "description": "Track an individual Instagram post or TikTok video.\n\nSet ``platform`` to ``\"instagram\"`` or ``\"tiktok\"``. The item is\nregistered immediately and, when added as active, its metrics are\nfetched in the background so they begin populating within seconds\ninstead of waiting for the next refresh cycle. Subsequent refreshes\nthen occur automatically at the configured interval.\n\nTo track **every** post/video from an account automatically, add the\naccount via ``POST /accounts`` instead.", "operationId": "track_video", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional client-supplied unique key for retry-safe POSTs. Best-effort in-process dedup over a 10-minute window. Multi-replica deployments will need a shared store before this is load-bearing across all writes.", "title": "Idempotency-Key" }, "description": "Optional client-supplied unique key for retry-safe POSTs. Best-effort in-process dedup over a 10-minute window. Multi-replica deployments will need a shared store before this is load-bearing across all writes." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackVideoRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Single_VideoResponse_" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Location": { "schema": { "type": "string" }, "description": "URI of the created resource." } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } } } } }, "/videos/{video_id}": { "get": { "tags": [ "Videos" ], "summary": "Get a video", "description": "Retrieve a single tracked post/video by its UUID.\n\nReturns the same enriched shape as the list endpoint (content fields,\nlatest metrics, and account context). Returns `404` if the video does\nnot exist or is not tracked by your organization.", "operationId": "get_video", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "video_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Tracked video UUID.", "title": "Video Id" }, "description": "Tracked video UUID." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Single_VideoResponse_" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag).", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } } } }, "patch": { "tags": [ "Videos" ], "summary": "Update a video", "description": "Update an individually tracked post/video.\n\nPartial update — only the fields you include change. Supports pausing/\nresuming tracking (`is_active`), editing `metadata`, and changing the\n`scrape_interval_hours`. Returns the updated video; `404` if it is not\ntracked by your organization.", "operationId": "update_video", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "video_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Tracked video UUID.", "title": "Video Id" }, "description": "Tracked video UUID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVideoRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Single_VideoResponse_" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } } } }, "delete": { "tags": [ "Videos" ], "summary": "Stop tracking a video", "description": "Remove an individually tracked post/video from tracking.\n\nStops future refreshes for this item; previously collected analytics\nare retained. **Idempotent** (RFC 9110 §9.2.2): returns `204 No\nContent` whether or not the item was tracked, so a retried or\nduplicated delete is not a spurious `404`.", "operationId": "delete_video", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "video_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Tracked video UUID.", "title": "Video Id" }, "description": "Tracked video UUID." } ], "responses": { "204": { "description": "Successful Response", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } } } } }, "/account-videos": { "get": { "tags": [ "Videos" ], "summary": "List account-discovered videos", "description": "Flattened stream of videos discovered from tracked accounts.\n\nReturns every post/video discovered on your organization's tracked\naccounts, across all of them, as one cursor-paginated stream (newest\nfirst by default) — instead of fanning out one request per account.\nPass `account_id` to scope to a single account, or use the nested\n`/accounts/{account_id}/videos` route. This differs from `/videos`,\nwhich lists items added individually via `POST /videos`.", "operationId": "list_all_account_videos", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "description": "Page size (1–200).", "default": 50, "title": "Limit" }, "description": "Page size (1–200)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque `pagination.next_cursor` from the previous page.", "title": "Cursor" }, "description": "Opaque `pagination.next_cursor` from the previous page." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "description": "Legacy signed sort string (e.g. `-create_time`). Prefer `order_by` + `order_direction`. Allowed keys: `create_time`, `view_count`, `like_count`, `play_count`.", "default": "-create_time", "title": "Sort" }, "description": "Legacy signed sort string (e.g. `-create_time`). Prefer `order_by` + `order_direction`. Allowed keys: `create_time`, `view_count`, `like_count`, `play_count`." }, { "name": "order_by", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "create_time", "view_count", "like_count", "play_count" ], "type": "string" }, { "type": "null" } ], "description": "Field to sort by. Overrides `sort`.", "title": "Order By" }, "description": "Field to sort by. Overrides `sort`." }, { "name": "order_direction", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "asc", "desc" ], "type": "string" }, { "type": "null" } ], "description": "Sort direction (default `desc`). Used with `order_by`.", "title": "Order Direction" }, "description": "Sort direction (default `desc`). Used with `order_by`." }, { "name": "platform", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "instagram", "tiktok" ], "type": "string" }, { "type": "null" } ], "description": "Filter by platform: `instagram` or `tiktok`.", "title": "Platform" }, "description": "Filter by platform: `instagram` or `tiktok`." }, { "name": "account_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Restrict to a single tracked account. Returns `404` if that account is not tracked by your organization.", "title": "Account Id" }, "description": "Restrict to a single tracked account. Returns `404` if that account is not tracked by your organization." }, { "name": "q", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Case-insensitive substring match against the post/video caption.", "title": "Q" }, "description": "Case-insensitive substring match against the post/video caption." }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When true, the response includes `pagination.total_count`. Adds one extra COUNT(*) query — leave off for cheap paging.", "default": false, "title": "Include Total" }, "description": "When true, the response includes `pagination.total_count`. Adds one extra COUNT(*) query — leave off for cheap paging." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." }, "Link": { "schema": { "type": "string" }, "description": "RFC 8288 pagination links (rel=\"first\"/\"next\")." } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag).", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } } } } }, "/account-videos/{video_id}": { "get": { "tags": [ "Videos" ], "summary": "Get an account-discovered video", "description": "Retrieve a single account-discovered video by its id.\n\nReturns the same enriched shape as the `/account-videos` list endpoint\n(content fields, latest metrics, account context). Lets the dashboard\nresolve an account-video directly on a deep link / refresh instead of\nscanning the paginated list. Returns `404` if no such video is tracked\nby your organization.", "operationId": "get_account_video", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "video_id", "in": "path", "required": true, "schema": { "type": "integer", "description": "Account-video id (per-platform bigint).", "title": "Video Id" }, "description": "Account-video id (per-platform bigint)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag).", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } } } } }, "/accounts/{account_id}/videos": { "get": { "tags": [ "Videos" ], "summary": "List one account's videos", "description": "List videos discovered from a single tracked account.\n\nThe nested, single-account form of `/account-videos`. Cursor-paginated,\nnewest first by default. Returns `404` if the account is not tracked by\nyour organization.", "operationId": "list_account_videos", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Tracked account UUID.", "title": "Account Id" }, "description": "Tracked account UUID." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "description": "Page size (1–200).", "default": 50, "title": "Limit" }, "description": "Page size (1–200)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque `pagination.next_cursor` from the previous page.", "title": "Cursor" }, "description": "Opaque `pagination.next_cursor` from the previous page." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "description": "Legacy signed sort string (e.g. `-create_time`). Prefer `order_by` + `order_direction`. Allowed keys: `create_time`, `view_count`, `like_count`, `play_count`.", "default": "-create_time", "title": "Sort" }, "description": "Legacy signed sort string (e.g. `-create_time`). Prefer `order_by` + `order_direction`. Allowed keys: `create_time`, `view_count`, `like_count`, `play_count`." }, { "name": "order_by", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "create_time", "view_count", "like_count", "play_count" ], "type": "string" }, { "type": "null" } ], "description": "Field to sort by. Overrides `sort`.", "title": "Order By" }, "description": "Field to sort by. Overrides `sort`." }, { "name": "order_direction", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "asc", "desc" ], "type": "string" }, { "type": "null" } ], "description": "Sort direction (default `desc`). Used with `order_by`.", "title": "Order Direction" }, "description": "Sort direction (default `desc`). Used with `order_by`." }, { "name": "include_total", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When true, the response includes `pagination.total_count`. Adds one extra COUNT(*) query — leave off for cheap paging.", "default": false, "title": "Include Total" }, "description": "When true, the response includes `pagination.total_count`. Adds one extra COUNT(*) query — leave off for cheap paging." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." }, "Link": { "schema": { "type": "string" }, "description": "RFC 8288 pagination links (rel=\"first\"/\"next\")." } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag).", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } } } } }, "/analytics/timeseries": { "get": { "tags": [ "Analytics" ], "summary": "Org timeseries", "description": "Org-wide daily {date, views, engagement} series, zero-filled.\n\nAccepts either a preset `period` (`7d`/`30d`/`90d`) or\n`period=custom` with explicit `start_date`/`end_date`. The custom\nwindow is capped at 366 days. Deep-audit finding\n`period-enum-no-custom-range`.", "operationId": "org_timeseries", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "period", "in": "query", "required": false, "schema": { "enum": [ "7d", "30d", "90d", "custom" ], "type": "string", "description": "Preset `7d`/`30d`/`90d`, or `custom` with dates.", "default": "7d", "title": "Period" }, "description": "Preset `7d`/`30d`/`90d`, or `custom` with dates." }, { "name": "start_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Inclusive start (YYYY-MM-DD); required for `custom`.", "title": "Start Date" }, "description": "Inclusive start (YYYY-MM-DD); required for `custom`." }, { "name": "end_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Inclusive end (YYYY-MM-DD); required for `custom`.", "title": "End Date" }, "description": "Inclusive end (YYYY-MM-DD); required for `custom`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TimeseriesPoint" } }, "meta": { "type": "object" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag).", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } } } } }, "/accounts/{account_id}/analytics/timeseries": { "get": { "tags": [ "Analytics" ], "summary": "Account timeseries", "description": "Per-account daily {date, views, engagement} series, zero-filled.\n\nAccepts custom windows via `period=custom` + `start_date`/`end_date`.", "operationId": "account_timeseries", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Tracked account UUID.", "title": "Account Id" }, "description": "Tracked account UUID." }, { "name": "period", "in": "query", "required": false, "schema": { "enum": [ "7d", "30d", "90d", "custom" ], "type": "string", "description": "Preset `7d`/`30d`/`90d`, or `custom` with dates.", "default": "7d", "title": "Period" }, "description": "Preset `7d`/`30d`/`90d`, or `custom` with dates." }, { "name": "start_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Inclusive start (YYYY-MM-DD); required for `custom`.", "title": "Start Date" }, "description": "Inclusive start (YYYY-MM-DD); required for `custom`." }, { "name": "end_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Inclusive end (YYYY-MM-DD); required for `custom`.", "title": "End Date" }, "description": "Inclusive end (YYYY-MM-DD); required for `custom`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TimeseriesPoint" } }, "meta": { "type": "object" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag).", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } } } } }, "/creators/{creator_id}/analytics/timeseries": { "get": { "tags": [ "Analytics" ], "summary": "Creator timeseries", "description": "Per-creator daily {date, views, engagement} series across all the\ncreator's accounts, zero-filled. Custom-range capable.", "operationId": "creator_timeseries", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "creator_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Creator UUID.", "title": "Creator Id" }, "description": "Creator UUID." }, { "name": "period", "in": "query", "required": false, "schema": { "enum": [ "7d", "30d", "90d", "custom" ], "type": "string", "description": "Preset `7d`/`30d`/`90d`, or `custom` with dates.", "default": "7d", "title": "Period" }, "description": "Preset `7d`/`30d`/`90d`, or `custom` with dates." }, { "name": "start_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Inclusive start (YYYY-MM-DD); required for `custom`.", "title": "Start Date" }, "description": "Inclusive start (YYYY-MM-DD); required for `custom`." }, { "name": "end_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Inclusive end (YYYY-MM-DD); required for `custom`.", "title": "End Date" }, "description": "Inclusive end (YYYY-MM-DD); required for `custom`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TimeseriesPoint" } }, "meta": { "type": "object" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag).", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } } } } }, "/videos/{video_id}/analytics/timeseries": { "get": { "tags": [ "Analytics" ], "summary": "Video timeseries", "description": "Single-video daily {date, views, engagement} series, zero-filled.\nCustom-range capable.", "operationId": "video_timeseries", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "video_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Tracked video UUID.", "title": "Video Id" }, "description": "Tracked video UUID." }, { "name": "period", "in": "query", "required": false, "schema": { "enum": [ "7d", "30d", "90d", "custom" ], "type": "string", "description": "Preset `7d`/`30d`/`90d`, or `custom` with dates.", "default": "7d", "title": "Period" }, "description": "Preset `7d`/`30d`/`90d`, or `custom` with dates." }, { "name": "start_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Inclusive start (YYYY-MM-DD); required for `custom`.", "title": "Start Date" }, "description": "Inclusive start (YYYY-MM-DD); required for `custom`." }, { "name": "end_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Inclusive end (YYYY-MM-DD); required for `custom`.", "title": "End Date" }, "description": "Inclusive end (YYYY-MM-DD); required for `custom`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TimeseriesPoint" } }, "meta": { "type": "object" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag).", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } } } } }, "/accounts/{account_id}/analytics": { "get": { "tags": [ "Analytics" ], "summary": "Account daily analytics", "description": "Per-metric daily analytics for one account over a date window.\n\nReturns one entry per day with the full per-metric breakdown (views,\nlikes, comments, shares, saves, plays, and platform-specific play/like\ncounts), plus `meta` describing the resolved window. Defaults to the\nlast 7 days when no dates are given. Returns `404` if the account is\nnot tracked by your organization. For a chart-ready\n`{views, engagement}` series, use `/analytics/timeseries` instead.", "operationId": "account_analytics", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Tracked account UUID.", "title": "Account Id" }, "description": "Tracked account UUID." }, { "name": "start_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Inclusive start (YYYY-MM-DD). Defaults to 6 days ago.", "title": "Start Date" }, "description": "Inclusive start (YYYY-MM-DD). Defaults to 6 days ago." }, { "name": "end_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Inclusive end (YYYY-MM-DD). Defaults to today (UTC).", "title": "End Date" }, "description": "Inclusive end (YYYY-MM-DD). Defaults to today (UTC)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DailyAnalyticsEntry" } }, "meta": { "type": "object" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag).", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } } } } }, "/creators/{creator_id}/analytics": { "get": { "tags": [ "Analytics" ], "summary": "Creator daily analytics", "description": "Per-metric daily analytics for a creator, summed across its accounts.\n\nSame per-day, per-metric shape as the account variant, aggregated over\nevery account linked to the creator. Defaults to the last 7 days.\nReturns `404` if the creator does not exist in your organization.", "operationId": "creator_analytics", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "creator_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Creator UUID.", "title": "Creator Id" }, "description": "Creator UUID." }, { "name": "start_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Inclusive start (YYYY-MM-DD). Defaults to 6 days ago.", "title": "Start Date" }, "description": "Inclusive start (YYYY-MM-DD). Defaults to 6 days ago." }, { "name": "end_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Inclusive end (YYYY-MM-DD). Defaults to today (UTC).", "title": "End Date" }, "description": "Inclusive end (YYYY-MM-DD). Defaults to today (UTC)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DailyAnalyticsEntry" } }, "meta": { "type": "object" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag).", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } } } } }, "/videos/{video_id}/analytics": { "get": { "tags": [ "Analytics" ], "summary": "Video daily analytics", "description": "Per-metric daily analytics for a single post/video over a window.\n\nSame per-day, per-metric shape as the account variant, scoped to one\nitem. Defaults to the last 7 days. Returns `404` if the video is not\ntracked by your organization.", "operationId": "video_analytics", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "video_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Tracked video UUID.", "title": "Video Id" }, "description": "Tracked video UUID." }, { "name": "start_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Inclusive start (YYYY-MM-DD). Defaults to 6 days ago.", "title": "Start Date" }, "description": "Inclusive start (YYYY-MM-DD). Defaults to 6 days ago." }, { "name": "end_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Inclusive end (YYYY-MM-DD). Defaults to today (UTC).", "title": "End Date" }, "description": "Inclusive end (YYYY-MM-DD). Defaults to today (UTC)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DailyAnalyticsEntry" } }, "meta": { "type": "object" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag).", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } } } } }, "/overview": { "get": { "tags": [ "Overview" ], "summary": "Organization overview stats", "description": "Headline stats for the organization over the selected period.\n\nReturns the current-period snapshot (total views, engagement rate,\nactive accounts, account-discovered videos, individually tracked\nvideos), the equivalent `previous` snapshot, and the percentage\n`changes` between them. Counts with no historical comparison yet are\n`null` (rather than a misleading `0`) so callers can tell \"no trend\"\napart from \"a trend of exactly zero\".", "operationId": "overview_stats", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "period", "in": "query", "required": false, "schema": { "enum": [ "7d", "30d", "90d" ], "type": "string", "description": "Reporting window for the headline figures.", "default": "7d", "title": "Period" }, "description": "Reporting window for the headline figures." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Single_OverviewResponse_" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag).", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } } } } }, "/search": { "get": { "tags": [ "Search" ], "summary": "Search accounts, creators & videos", "description": "Return up to `limit` matches per entity type, wrapped in the\nstandard v2 envelope.\n\nPowers the dashboard command palette (Cmd+K). Response shape:\n\n```\n{\n \"data\": {\n \"accounts\": [{ id, platform, username, display_name }, ...],\n \"creators\": [{ id, name }, ...],\n \"videos\": [{ id, platform, caption, account_id, account_username }, ...]\n },\n \"meta\": {\n \"query\": \"\",\n \"limit_per_section\": ,\n \"effective_caps\": { accounts, creators, videos }\n }\n}\n```\n\n`meta.effective_caps` surfaces the per-section cap the service\nactually applied — it is `min(limit, _MAX_*)` and previously the\nservice silently clamped lower than the router's `le=25` allowed,\nso a client sending `limit=25` could not tell why it only got 10\nresults. Deep-audit findings `search-no-response-envelope` and\n`search-service-hidden-cap`.\n\nEmpty / whitespace `q` returns empty sections.", "operationId": "search", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128, "description": "Case-insensitive substring matched against account usernames, creator names, and video captions in the caller's organization.", "default": "", "title": "Q" }, "description": "Case-insensitive substring matched against account usernames, creator names, and video captions in the caller's organization." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 25, "minimum": 1, "description": "Max matches per entity type (1–25).", "default": 10, "title": "Limit" }, "description": "Max matches per entity type (1–25)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "304": { "description": "Not Modified (If-None-Match matched the ETag).", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator; send back as If-None-Match for a 304." } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "422": { "description": "Validation Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Correlation id echoed (or minted) for this request." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request quota for the current rate-limit window." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } } } } } }, "components": { "schemas": { "AccountMetricsRequest": { "properties": { "account_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "maxItems": 200, "minItems": 1, "title": "Account Ids", "description": "Org account UUIDs to window (1–200)." }, "period": { "type": "string", "enum": [ "7d", "30d", "90d", "custom" ], "title": "Period", "description": "Preset window (7d/30d/90d) or 'custom' with start_date/end_date.", "default": "30d" }, "start_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Start Date", "description": "Inclusive UTC start; required when period=custom." }, "end_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "End Date", "description": "Inclusive UTC end; required when period=custom." } }, "type": "object", "required": [ "account_ids" ], "title": "AccountMetricsRequest" }, "AccountVideoMetricsRequest": { "properties": { "instagram_post_ids": { "items": { "type": "integer" }, "type": "array", "title": "Instagram Post Ids", "description": "Internal instagram_post ids." }, "tiktok_video_ids": { "items": { "type": "integer" }, "type": "array", "title": "Tiktok Video Ids", "description": "Internal tiktok_video ids." }, "period": { "type": "string", "enum": [ "7d", "30d", "90d", "custom" ], "title": "Period", "description": "Preset window (7d/30d/90d) or 'custom' with start_date/end_date.", "default": "30d" }, "start_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Start Date", "description": "Inclusive UTC start; required when period=custom." }, "end_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "End Date", "description": "Inclusive UTC end; required when period=custom." } }, "type": "object", "title": "AccountVideoMetricsRequest" }, "AccountsSummary": { "properties": { "total": { "type": "integer", "title": "Total", "description": "Number of linked accounts.", "default": 0 }, "platforms": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Platforms", "description": "Linked-account count per platform.", "default": {} }, "total_followers": { "type": "integer", "title": "Total Followers", "description": "Combined follower count across linked accounts.", "default": 0 } }, "type": "object", "title": "AccountsSummary", "description": "Roll-up of the accounts grouped under a creator." }, "Collection_CreatorResponse_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/CreatorResponse" }, "type": "array", "title": "Data" }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "filters": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Filters" } }, "type": "object", "required": [ "data", "pagination" ], "title": "Collection[CreatorResponse]" }, "Collection_VideoResponse_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/VideoResponse" }, "type": "array", "title": "Data" }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "filters": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Filters" } }, "type": "object", "required": [ "data", "pagination" ], "title": "Collection[VideoResponse]" }, "CreateAccountRequest": { "properties": { "platform": { "type": "string", "enum": [ "instagram", "tiktok" ], "title": "Platform", "description": "Platform to track: instagram or tiktok." }, "username": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Username", "description": "Account handle to track." }, "creator_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Creator Id", "description": "Optional creator to link this account to." }, "category": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "Category", "description": "Optional category label." }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Optional key/value tags (≤20 keys, ≤255 chars each)." }, "scrape_interval_hours": { "type": "integer", "maximum": 720, "minimum": 6, "title": "Scrape Interval Hours", "description": "Refresh cadence in hours (6–720). Defaults to 24.", "default": 24 } }, "type": "object", "required": [ "platform", "username" ], "title": "CreateAccountRequest", "examples": [ { "category": "tech", "platform": "tiktok", "scrape_interval_hours": 24, "username": "creatoraudit" } ] }, "CreateCreatorRequest": { "properties": { "name": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Name", "description": "Creator name (1–255 chars)." }, "is_active": { "type": "boolean", "title": "Is Active", "description": "Create as active (default true).", "default": true }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Optional key/value tags (≤20 keys, ≤255 chars each)." } }, "type": "object", "required": [ "name" ], "title": "CreateCreatorRequest", "examples": [ { "is_active": true, "name": "Jane Doe" } ] }, "CreatorResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Creator id; use it on all creator routes." }, "type": { "type": "string", "title": "Type", "description": "Resource type discriminator.", "default": "creator" }, "name": { "type": "string", "title": "Name", "description": "Creator name." }, "is_active": { "type": "boolean", "title": "Is Active", "description": "Whether the creator is active.", "default": false }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Caller-supplied key/value tags." }, "accounts_summary": { "$ref": "#/components/schemas/AccountsSummary", "description": "Roll-up of linked accounts.", "default": { "total": 0, "platforms": {}, "total_followers": 0 } } }, "type": "object", "required": [ "id", "name" ], "title": "CreatorResponse" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "HealthPayload": { "properties": { "type": { "type": "string", "title": "Type", "default": "health" }, "status": { "type": "string", "title": "Status", "default": "ok" }, "api_version": { "type": "string", "title": "Api Version", "default": "v2" } }, "type": "object", "title": "HealthPayload" }, "OverviewChanges": { "properties": { "total_views_pct": { "type": "number", "title": "Total Views Pct", "description": "Views change vs. previous period.", "default": 0 }, "engagement_rate_pct": { "type": "number", "title": "Engagement Rate Pct", "description": "Engagement-rate change vs. previous period.", "default": 0 }, "active_accounts_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Active Accounts Pct", "description": "Active-accounts change; null when no comparison exists.", "default": 0 }, "account_videos_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Account Videos Pct", "description": "Account-videos change; null when no comparison exists.", "default": 0 }, "tracked_videos_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Tracked Videos Pct", "description": "Tracked-videos change; null when no comparison exists.", "default": 0 } }, "type": "object", "title": "OverviewChanges", "description": "Period-over-period percentage changes for the headline stats." }, "OverviewResponse": { "properties": { "type": { "type": "string", "title": "Type", "description": "Resource type discriminator.", "default": "overview" }, "current": { "$ref": "#/components/schemas/PeriodSnapshot", "description": "Stats for the requested period." }, "previous": { "$ref": "#/components/schemas/PeriodSnapshot", "description": "Stats for the preceding period." }, "changes": { "$ref": "#/components/schemas/OverviewChanges", "description": "Period-over-period percent changes." } }, "type": "object", "required": [ "current", "previous", "changes" ], "title": "OverviewResponse" }, "PeriodSnapshot": { "properties": { "total_views": { "type": "integer", "title": "Total Views", "description": "Total views across the org this period.", "default": 0 }, "engagement_rate": { "type": "number", "title": "Engagement Rate", "description": "Engagement rate (0–1) across the org this period.", "default": 0 }, "active_accounts": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Active Accounts", "description": "Active tracked accounts; null when no comparison exists.", "default": 0 }, "account_videos": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Account Videos", "description": "Account-discovered videos; null when no comparison exists.", "default": 0 }, "tracked_videos": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tracked Videos", "description": "Individually tracked videos; null when no comparison exists.", "default": 0 } }, "type": "object", "title": "PeriodSnapshot", "description": "Headline org-wide stats for one period." }, "Single_CreatorResponse_": { "properties": { "data": { "$ref": "#/components/schemas/CreatorResponse" } }, "type": "object", "required": [ "data" ], "title": "Single[CreatorResponse]" }, "Single_HealthPayload_": { "properties": { "data": { "$ref": "#/components/schemas/HealthPayload" } }, "type": "object", "required": [ "data" ], "title": "Single[HealthPayload]" }, "Single_OverviewResponse_": { "properties": { "data": { "$ref": "#/components/schemas/OverviewResponse" } }, "type": "object", "required": [ "data" ], "title": "Single[OverviewResponse]" }, "Single_V2Meta_": { "properties": { "data": { "$ref": "#/components/schemas/V2Meta" } }, "type": "object", "required": [ "data" ], "title": "Single[V2Meta]" }, "Single_VideoResponse_": { "properties": { "data": { "$ref": "#/components/schemas/VideoResponse" } }, "type": "object", "required": [ "data" ], "title": "Single[VideoResponse]" }, "Single_WhoAmI_": { "properties": { "data": { "$ref": "#/components/schemas/WhoAmI" } }, "type": "object", "required": [ "data" ], "title": "Single[WhoAmI]" }, "TrackVideoRequest": { "properties": { "platform": { "type": "string", "enum": [ "instagram", "tiktok" ], "title": "Platform", "description": "Platform to track: instagram or tiktok." }, "identifier": { "type": "string", "maxLength": 512, "minLength": 1, "title": "Identifier", "description": "The post/video to track. Accepts a full URL (instagram.com/p/{shortcode}, tiktok.com/@user/video/{id}), a numeric id, or — for Instagram only — a bare shortcode. The server resolves and normalizes it." }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Optional key/value tags (≤20 keys, ≤255 chars each)." }, "is_active": { "type": "boolean", "title": "Is Active", "description": "Track as active (default true).", "default": true }, "scrape_interval_hours": { "type": "integer", "maximum": 720, "minimum": 6, "title": "Scrape Interval Hours", "description": "Refresh cadence in hours (6–720). Defaults to 24.", "default": 24 } }, "type": "object", "required": [ "platform", "identifier" ], "title": "TrackVideoRequest", "examples": [ { "identifier": "https://www.tiktok.com/@user/video/712345", "is_active": true, "platform": "tiktok" } ] }, "UpdateAccountRequest": { "properties": { "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Active", "description": "Pause (false) or resume (true) tracking." }, "category": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "Category", "description": "New category label." }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Replacement key/value tags (≤20 keys, ≤255 chars each)." }, "scrape_interval_hours": { "anyOf": [ { "type": "integer", "maximum": 720, "minimum": 6 }, { "type": "null" } ], "title": "Scrape Interval Hours", "description": "New refresh cadence in hours (6–720)." }, "creator_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Creator Id", "description": "Link to this creator, or null to unlink." }, "max_recent_posts_per_account": { "anyOf": [ { "type": "integer", "maximum": 5000, "minimum": 50 }, { "type": "null" } ], "title": "Max Recent Posts Per Account", "description": "Per-account recent-posts cap (50–5000); null inherits org default." }, "post_lookback_days": { "anyOf": [ { "type": "integer", "maximum": 7300, "minimum": 90 }, { "type": "null" } ], "title": "Post Lookback Days", "description": "Per-account history window in days (90–7300); null inherits." } }, "type": "object", "title": "UpdateAccountRequest", "examples": [ { "category": "fitness", "is_active": false } ] }, "UpdateCreatorRequest": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 255, "minLength": 1 }, { "type": "null" } ], "title": "Name", "description": "New creator name." }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Active", "description": "Activate or archive the creator." }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Replacement key/value tags (≤20 keys, ≤255 chars each)." } }, "type": "object", "title": "UpdateCreatorRequest", "examples": [ { "name": "Jane Q. Doe" } ] }, "UpdateVideoRequest": { "properties": { "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Active", "description": "Pause (false) or resume (true) tracking." }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Replacement key/value tags (≤20 keys, ≤255 chars each)." }, "scrape_interval_hours": { "anyOf": [ { "type": "integer", "maximum": 720, "minimum": 6 }, { "type": "null" } ], "title": "Scrape Interval Hours", "description": "New refresh cadence in hours (6–720)." } }, "type": "object", "title": "UpdateVideoRequest", "examples": [ { "is_active": false, "scrape_interval_hours": 48 } ] }, "V2Meta": { "properties": { "type": { "type": "string", "title": "Type", "default": "api_meta" }, "api_version": { "type": "string", "title": "Api Version", "default": "v2" }, "status": { "type": "string", "title": "Status", "default": "current" }, "docs_url": { "type": "string", "title": "Docs Url", "default": "/v2/docs" }, "openapi_url": { "type": "string", "title": "Openapi Url", "default": "/v2/openapi.json" }, "whoami_url": { "type": "string", "title": "Whoami Url", "default": "/v2/whoami" }, "deprecation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Deprecation" }, "sunset": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sunset" } }, "type": "object", "title": "V2Meta" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "VideoDeltasRequest": { "properties": { "video_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "maxItems": 200, "minItems": 1, "title": "Video Ids", "description": "Video UUIDs to fetch deltas for (1–200)." }, "windows": { "items": { "type": "integer", "maximum": 365, "minimum": 1 }, "type": "array", "maxItems": 10, "minItems": 1, "title": "Windows", "description": "Look-back windows in days (1–365) to compute each delta over. Duplicates are ignored; up to 10 windows.", "default": [ 1, 7, 14, 30 ] } }, "type": "object", "required": [ "video_ids" ], "title": "VideoDeltasRequest" }, "VideoMetricsRequest": { "properties": { "video_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "maxItems": 200, "minItems": 1, "title": "Video Ids", "description": "Org video/post UUIDs to window (1–200)." }, "period": { "type": "string", "enum": [ "7d", "30d", "90d", "custom" ], "title": "Period", "description": "Preset window (7d/30d/90d) or 'custom' with start_date/end_date.", "default": "30d" }, "start_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Start Date", "description": "Inclusive UTC start; required when period=custom." }, "end_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "End Date", "description": "Inclusive UTC end; required when period=custom." } }, "type": "object", "required": [ "video_ids" ], "title": "VideoMetricsRequest" }, "VideoResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Org-scoped video id; use it on all video routes." }, "type": { "type": "string", "title": "Type", "description": "Resource type discriminator.", "default": "video" }, "platform": { "type": "string", "enum": [ "instagram", "tiktok" ], "title": "Platform", "description": "Source platform: instagram or tiktok." }, "external_id": { "type": "string", "title": "External Id", "description": "Platform-native post/video id." }, "shortcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Shortcode", "description": "Instagram shortcode for the post URL (null for TikTok)." }, "is_active": { "type": "boolean", "title": "Is Active", "description": "Whether tracking is active (vs. paused).", "default": true }, "scrape_interval_hours": { "type": "integer", "title": "Scrape Interval Hours", "description": "How often the video is refreshed, in hours.", "default": 24 }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Caller-supplied key/value tags." }, "added_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Added At", "description": "When tracking of this video began." }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At", "description": "Last time the tracking record changed." }, "first_scrape_time": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "First Scrape Time", "description": "First successful refresh timestamp." }, "last_scrape_time": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Scrape Time", "description": "Most recent successful refresh timestamp." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Caption / description text." }, "create_time": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Create Time", "description": "When the post was published on the platform." }, "media_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Media Type", "description": "Media kind (e.g. VIDEO, IMAGE, CAROUSEL)." }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Duration", "description": "Duration in seconds, if a video." }, "is_unavailable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Unavailable", "description": "True if the post is private/removed/unreachable." }, "cover_image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cover Image Url", "description": "CDN-hosted cover/thumbnail URL." }, "cover_image_url_original": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cover Image Url Original", "description": "Original platform cover/thumbnail URL." }, "video_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Video Url", "description": "CDN-hosted video URL, if a video." }, "video_url_original": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Video Url Original", "description": "Original platform video URL, if a video." }, "view_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "View Count", "description": "Latest view count." }, "like_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Like Count", "description": "Latest like count." }, "comment_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Comment Count", "description": "Latest comment count." }, "share_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Share Count", "description": "Latest share count." }, "play_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Play Count", "description": "Latest play count." }, "saved_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Saved Count", "description": "Latest save count (Instagram only)." }, "total_views": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Views", "description": "Cumulative views to date." }, "total_plays": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Plays", "description": "Cumulative plays to date." }, "account_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Account Id", "description": "Org-scoped author account id; null when your org doesn't track the author (open the platform profile instead)." }, "account_username": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Account Username", "description": "Author's username, once the profile is scraped." }, "platform_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Platform Account Id", "description": "Global platform-account id (string), stable even when your org doesn't track the author." }, "platform_data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Platform Data", "description": "Raw platform-specific extras." } }, "type": "object", "required": [ "id", "platform", "external_id" ], "title": "VideoResponse", "description": "A tracked post/video with its content fields and latest metrics." }, "WhoAmI": { "properties": { "type": { "type": "string", "title": "Type", "default": "whoami" }, "organization_id": { "type": "string", "title": "Organization Id" }, "api_key_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Api Key Name" } }, "type": "object", "required": [ "organization_id" ], "title": "WhoAmI" }, "ProblemDetail": { "additionalProperties": true, "properties": { "type": { "title": "Type", "type": "string" }, "title": { "title": "Title", "type": "string" }, "status": { "title": "Status", "type": "integer" }, "detail": { "title": "Detail", "type": "string" }, "code": { "title": "Code", "type": "string", "enum": [ "BAD_REQUEST", "CONFLICT", "FORBIDDEN", "INSUFFICIENT_SCOPE", "INTERNAL_ERROR", "NOT_ACCEPTABLE", "NOT_FOUND", "QUOTA_EXCEEDED", "RATE_LIMITED", "SERVICE_UNAVAILABLE", "UNAUTHORIZED", "UNSUPPORTED_MEDIA_TYPE", "UPSTREAM_ERROR", "VALIDATION_ERROR" ] }, "instance": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Instance" }, "errors": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Errors" } }, "required": [ "type", "title", "status", "detail", "code" ], "title": "ProblemDetail", "type": "object" }, "PaginationMeta": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page; null on the last page." }, "has_next": { "type": "boolean", "description": "True when another page is available." }, "limit": { "type": "integer", "description": "Page size used." }, "total_count": { "type": [ "integer", "null" ], "description": "Total matches, only when include_total=true." } }, "required": [ "has_next", "limit" ] }, "AccountResponse": { "description": "A tracked Instagram or TikTok account with its latest engagement\nmetrics and per-account tracking configuration.", "properties": { "id": { "description": "Org-scoped account id; use it on all routes.", "format": "uuid", "title": "Id", "type": "string" }, "type": { "default": "account", "description": "Resource type discriminator.", "title": "Type", "type": "string" }, "platform": { "description": "Source platform: instagram or tiktok.", "enum": [ "instagram", "tiktok" ], "title": "Platform", "type": "string" }, "username": { "description": "Account handle on the platform.", "title": "Username", "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Display name, if known.", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Profile bio text.", "title": "Description" }, "profile_pic_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "CDN-hosted profile picture URL.", "title": "Profile Pic Url" }, "profile_pic_url_original": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Original platform profile picture URL.", "title": "Profile Pic Url Original" }, "is_verified": { "default": false, "description": "Platform verification badge.", "title": "Is Verified", "type": "boolean" }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Whether tracking is currently active (vs. paused).", "title": "Is Active" }, "is_unavailable": { "default": false, "description": "True if the profile is private/removed/unreachable.", "title": "Is Unavailable", "type": "boolean" }, "link_in_bio": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Bio link, if present.", "title": "Link In Bio" }, "creator_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "description": "Creator this account is grouped under, if any.", "title": "Creator Id" }, "creator_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Linked creator's name.", "title": "Creator Name" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Free-form category label.", "title": "Category" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Caller-supplied key/value tags.", "title": "Metadata" }, "added_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "When the org started tracking this account.", "title": "Added At" }, "first_scrape_time": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "First successful refresh timestamp.", "title": "First Scrape Time" }, "last_scrape_time": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "Most recent successful refresh timestamp.", "title": "Last Scrape Time" }, "scrape_interval_hours": { "default": 24, "description": "How often the account is refreshed, in hours.", "title": "Scrape Interval Hours", "type": "integer" }, "follower_count": { "default": 0, "description": "Latest follower count.", "title": "Follower Count", "type": "integer" }, "following_count": { "default": 0, "description": "Latest following count.", "title": "Following Count", "type": "integer" }, "profile_post_count": { "default": 0, "description": "Lifetime post count reported by the platform.", "title": "Profile Post Count", "type": "integer" }, "total_post_count": { "default": 0, "description": "Posts/videos discovered and tracked for this account.", "title": "Total Post Count", "type": "integer" }, "view_count": { "default": 0, "description": "Total views across tracked content.", "title": "View Count", "type": "integer" }, "like_count": { "default": 0, "description": "Total likes across tracked content.", "title": "Like Count", "type": "integer" }, "comment_count": { "default": 0, "description": "Total comments across tracked content.", "title": "Comment Count", "type": "integer" }, "share_count": { "default": 0, "description": "Total shares across tracked content.", "title": "Share Count", "type": "integer" }, "play_count": { "default": 0, "description": "Total plays across tracked content.", "title": "Play Count", "type": "integer" }, "saved_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Total saves (Instagram only; null for TikTok).", "title": "Saved Count" }, "fb_play_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Facebook plays (Instagram only; null for TikTok).", "title": "Fb Play Count" }, "ig_play_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Instagram plays (Instagram only; null for TikTok).", "title": "Ig Play Count" }, "fb_like_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Facebook likes (Instagram only; null for TikTok).", "title": "Fb Like Count" }, "max_recent_posts_per_account": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Per-account cap on recent posts to track; null = inherit org default.", "title": "Max Recent Posts Per Account" }, "post_lookback_days": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Per-account history window in days; null = inherit org default.", "title": "Post Lookback Days" }, "effective_max_recent_posts_per_account": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Resolved recent-posts cap after applying org defaults.", "title": "Effective Max Recent Posts Per Account" }, "effective_post_lookback_days": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Resolved lookback window after applying org defaults.", "title": "Effective Post Lookback Days" } }, "required": [ "id", "platform", "username" ], "title": "AccountResponse", "type": "object" }, "DailyAnalyticsEntry": { "description": "One calendar day's per-metric engagement totals (UTC).", "properties": { "date": { "description": "UTC calendar day this row covers.", "format": "date", "title": "Date", "type": "string" }, "view_count": { "default": 0, "description": "Views on this day.", "title": "View Count", "type": "integer" }, "like_count": { "default": 0, "description": "Likes on this day.", "title": "Like Count", "type": "integer" }, "comment_count": { "default": 0, "description": "Comments on this day.", "title": "Comment Count", "type": "integer" }, "share_count": { "default": 0, "description": "Shares on this day.", "title": "Share Count", "type": "integer" }, "saved_count": { "default": 0, "description": "Saves on this day (Instagram).", "title": "Saved Count", "type": "integer" }, "play_count": { "default": 0, "description": "Plays on this day.", "title": "Play Count", "type": "integer" }, "fb_play_count": { "default": 0, "description": "Facebook plays (Instagram).", "title": "Fb Play Count", "type": "integer" }, "fb_like_count": { "default": 0, "description": "Facebook likes (Instagram).", "title": "Fb Like Count", "type": "integer" }, "ig_play_count": { "default": 0, "description": "Instagram plays.", "title": "Ig Play Count", "type": "integer" } }, "required": [ "date" ], "title": "DailyAnalyticsEntry", "type": "object" }, "TimeseriesPoint": { "description": "One day's headline views + engagement, for charting.", "properties": { "date": { "description": "UTC calendar day this point covers.", "format": "date", "title": "Date", "type": "string" }, "views": { "default": 0, "description": "Views on this day.", "title": "Views", "type": "integer" }, "engagement": { "default": 0, "description": "Engagement (likes+comments+…) this day.", "title": "Engagement", "type": "integer" } }, "required": [ "date" ], "title": "TimeseriesPoint", "type": "object" } }, "securitySchemes": { "HTTPBearer": { "type": "http", "scheme": "bearer" } } }, "tags": [ { "name": "Accounts", "description": "Track and manage Instagram/TikTok accounts. Listing, retrieval, creation (which begins automated tracking), updates, and removal." }, { "name": "Videos", "description": "Individually tracked posts/videos, account-discovered videos, and batch engagement deltas." }, { "name": "Creators", "description": "Creators group one or more accounts under a single entity for roll-up analytics. Includes account linking and the top-creators leaderboard." }, { "name": "Analytics", "description": "Daily engagement series for the org, accounts, creators, and individual videos, plus per-metric daily breakdowns for accounts, creators, and videos." }, { "name": "Overview", "description": "Org-wide headline stats with period-over-period changes." }, { "name": "Search", "description": "Cross-entity search over accounts, creators, and videos." }, { "name": "System", "description": "Unauthenticated liveness and service-health checks." } ] }