{"openapi":"3.1.0","info":{"title":"ViralDashboard Public API","version":"1.0.0","summary":"Programmatic access to brands, posts, social accounts, media, analytics, link-in-bio, content plans and feeds.","description":"Programmatic access to everything you can do in ViralDashboard: brands, social accounts, posts,\nmedia, analytics, link-in-bio, content plans, feeds, webhooks, AI and reports.\n\n## Getting started\n\n1. Mint a key in **Settings \u2192 API & Webhooks \u2192 API Keys**. The secret is shown **once** \u2014 store it now.\n2. Send it as a Bearer token: `Authorization: Bearer vd_live_\u2026`\n3. Find your brand id: `GET /brands`. Every resource below is nested under a brand.\n\n```bash\ncurl https://vm.viraldashboard.io/api/public/v1/brands \\\n  -H \"Authorization: Bearer $VD_API_KEY\"\n```\n\n## The rules that apply everywhere\n\n- **Keys carry scopes.** A call needing a scope the key lacks returns `403 insufficient_scope`.\n- **Test keys are read-only.** A `vd_test_\u2026` key on any write returns `403 test_mode_write_forbidden`.\n- **Brands are authorized, not just filtered.** A brand your key's user can't reach returns `403 brand_forbidden` \u2014 never an empty list.\n- **Every write needs an `Idempotency-Key`.** Missing it is `400`. Replaying the same key with the same body returns the stored response (`Idempotent-Replayed: true`); reusing it with a *different* body is `409`.\n- **Plan limits are enforced.** Hitting a cap or a feature you don't own returns `402` \u2014 with a `code` telling you which (`limit_reached`, `feature_not_available`, `insufficient_credits`, `storage_limit_exceeded`).\n- **Errors share one envelope**, always: `{ \"error\": { \"type\", \"code\", \"message\" } }`.\n- **Rate limits are per key**, surfaced on every response in `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`; a `429` also carries `Retry-After`.\n\n## Long-running work\n\nMedia import, report export and publishing are asynchronous. They return `202` with a poll URL \u2014\npoll it until the status is terminal, or subscribe to a webhook and let us call you."},"servers":[{"url":"https://vm.viraldashboard.io/api/public/v1","description":"This environment"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Brands"},{"name":"Social Accounts"},{"name":"Posts"},{"name":"Media"},{"name":"Analytics"},{"name":"Link-in-Bio"},{"name":"Content Plans"},{"name":"Feeds"},{"name":"Webhooks"},{"name":"AI"},{"name":"Reports"},{"name":"Inbox"}],"paths":{"/brands":{"get":{"tags":["Brands"],"summary":"List accessible brands","description":"Requires scope `brands:read`. Returns only brands the key\u2019s user can access.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Brand"}},"links":{"$ref":"#/components/schemas/PaginationLinks"},"meta":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["Brands"],"summary":"Create a brand","description":"Requires scope `brands:write` and a live key. Test-mode keys return 403 test_mode_write_forbidden.","parameters":[{"$ref":"#/components/parameters/idempotencyKey"}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Brand"}}}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"400":{"$ref":"#/components/responses/IdempotencyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"website":{"type":"string","format":"uri"},"timezone":{"type":"string"}}},"example":{"name":"Acme Coffee","description":"Speciality roaster","website":"https://acme.coffee","timezone":"Europe/London"}}}}}},"/brands/{brand}":{"get":{"tags":["Brands"],"summary":"Get a brand","description":"Requires scope `brands:read`.","parameters":[{"$ref":"#/components/parameters/brand"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Brand"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/brands/{brand}/social-accounts":{"get":{"tags":["Social Accounts"],"summary":"List connected social accounts","description":"Requires scope `accounts:read`.","parameters":[{"$ref":"#/components/parameters/brand"},{"$ref":"#/components/parameters/perPage"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SocialAccount"}},"links":{"$ref":"#/components/schemas/PaginationLinks"},"meta":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["Social Accounts"],"summary":"Connect a self_connect platform with credentials","description":"Requires scope `accounts:write` and a live key. Test-mode keys return 403 test_mode_write_forbidden.","parameters":[{"$ref":"#/components/parameters/idempotencyKey"},{"$ref":"#/components/parameters/brand"}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SocialAccount"}},"links":{"$ref":"#/components/schemas/PaginationLinks"},"meta":{"$ref":"#/components/schemas/Pagination"}}}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"400":{"$ref":"#/components/responses/IdempotencyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","description":"A self_connect platform: telegram, bluesky, wordpress, woocommerce."},"credentials":{"type":"object","description":"Platform credential fields (see /social-accounts/platforms). URL fields are SSRF-guarded."}}},"example":{"platform":"telegram","credentials":{"bot_token":"8012345678:AAH\u2026","chat_id":"@testtelegramo"}}}}}}},"/brands/{brand}/social-accounts/platforms":{"get":{"tags":["Social Accounts"],"summary":"List connectable platforms + credential fields","description":"Requires scope `accounts:read`. Returns each platform\u2019s mode (oauth | self_connect | self_connect_oauth), connect_method, and the credential fields self_connect needs.","parameters":[{"$ref":"#/components/parameters/brand"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Platform"}},"links":{"$ref":"#/components/schemas/PaginationLinks"},"meta":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/brands/{brand}/social-accounts/authorize":{"post":{"tags":["Social Accounts"],"summary":"Issue a one-time OAuth authorization URL","description":"Requires scope `accounts:write` and a live key. Test-mode keys return 403 test_mode_write_forbidden.","parameters":[{"$ref":"#/components/parameters/idempotencyKey"},{"$ref":"#/components/parameters/brand"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AuthorizationGrant"}}}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"400":{"$ref":"#/components/responses/IdempotencyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","description":"A browser-OAuth platform (facebook, instagram, twitter, linkedin, \u2026)."},"target":{"type":"string","enum":["default","page"]}}},"example":{"platform":"facebook","target":"page"}}}}}},"/brands/{brand}/social-accounts/{account}/refresh":{"post":{"tags":["Social Accounts"],"summary":"Refresh an account token","description":"Requires scope `accounts:write` and a live key. Test-mode keys return 403 test_mode_write_forbidden.","parameters":[{"$ref":"#/components/parameters/idempotencyKey"},{"$ref":"#/components/parameters/brand"},{"name":"account","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SocialAccount"}}}}}},"409":{"description":"Reconnect required (unrefreshable / legacy account)."},"400":{"$ref":"#/components/responses/IdempotencyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/brands/{brand}/social-accounts/{account}":{"delete":{"tags":["Social Accounts"],"summary":"Disconnect an account","description":"Requires scope `accounts:write` and a live key. Test-mode keys return 403 test_mode_write_forbidden.","parameters":[{"$ref":"#/components/parameters/idempotencyKey"},{"$ref":"#/components/parameters/brand"},{"name":"account","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DisconnectResult"}}}}}},"400":{"$ref":"#/components/responses/IdempotencyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/brands/{brand}/posts":{"get":{"tags":["Posts"],"summary":"List posts","description":"Requires scope `posts:read`.","parameters":[{"$ref":"#/components/parameters/brand"},{"$ref":"#/components/parameters/perPage"},{"name":"status","in":"query","schema":{"type":"string"},"description":"Filter by post status."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Post"}},"links":{"$ref":"#/components/schemas/PaginationLinks"},"meta":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["Posts"],"summary":"Create a post","description":"Requires scope `posts:write` and a live key. Test-mode keys return 403 test_mode_write_forbidden.","parameters":[{"$ref":"#/components/parameters/idempotencyKey"},{"$ref":"#/components/parameters/brand"}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PostDetail"}}}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"400":{"$ref":"#/components/responses/IdempotencyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string"},"schedule_type":{"type":"string","enum":["now","scheduled","draft"]},"scheduled_at":{"type":"string","format":"date-time"},"accounts":{"type":"array","items":{"type":"integer"},"description":"Social account ids (required unless draft)."}}},"example":{"content":"Ship day. The new API is live \ud83d\ude80","schedule_type":"scheduled","scheduled_at":"2026-07-13T09:00:00+00:00","accounts":[3310]}}}}}},"/brands/{brand}/posts/{post}":{"get":{"tags":["Posts"],"summary":"Get a post","description":"Requires scope `posts:read`.","parameters":[{"$ref":"#/components/parameters/brand"},{"name":"post","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PostDetail"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"put":{"tags":["Posts"],"summary":"Update a post","description":"Requires scope `posts:write` and a live key. Test-mode keys return 403 test_mode_write_forbidden.","parameters":[{"$ref":"#/components/parameters/idempotencyKey"},{"$ref":"#/components/parameters/brand"},{"name":"post","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PostDetail"}}}}}},"400":{"$ref":"#/components/responses/IdempotencyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string"},"schedule_type":{"type":"string","enum":["now","scheduled","draft"]}}}}}}},"delete":{"tags":["Posts"],"summary":"Delete a post","description":"Requires scope `posts:write` and a live key. Test-mode keys return 403 test_mode_write_forbidden.","parameters":[{"$ref":"#/components/parameters/idempotencyKey"},{"$ref":"#/components/parameters/brand"},{"name":"post","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"204":{"description":"Created"},"400":{"$ref":"#/components/responses/IdempotencyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/brands/{brand}/posts/{post}/submit":{"post":{"tags":["Posts"],"summary":"Submit a draft for approval","description":"Requires scope `posts:write` and a live key. Test-mode keys return 403 test_mode_write_forbidden.","parameters":[{"$ref":"#/components/parameters/idempotencyKey"},{"$ref":"#/components/parameters/brand"},{"name":"post","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PostDetail"}}}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"400":{"$ref":"#/components/responses/IdempotencyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/brands/{brand}/posts/{post}/status":{"get":{"tags":["Posts"],"summary":"Get post status","description":"Requires scope `posts:read`. Lightweight status/schedule view.","parameters":[{"$ref":"#/components/parameters/brand"},{"name":"post","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PostStatus"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/brands/{brand}/media":{"get":{"tags":["Media"],"summary":"List media assets","description":"Requires scope `media:read`.","parameters":[{"$ref":"#/components/parameters/brand"},{"$ref":"#/components/parameters/perPage"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MediaAsset"}},"links":{"$ref":"#/components/schemas/PaginationLinks"},"meta":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["Media"],"summary":"Upload an image (multipart)","description":"Requires scope `media:write` and a live key. MIME is validated by MAGIC BYTES (raster JPEG/PNG/GIF/WebP only \u2014 SVG rejected). Rejected early on Content-Length (413); storage projection enforced before persisting (402).","parameters":[{"$ref":"#/components/parameters/brand"},{"$ref":"#/components/parameters/idempotencyKey"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"},"asset_type":{"type":"string","enum":["image","icon","logo"]}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MediaAsset"}}}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"400":{"$ref":"#/components/responses/IdempotencyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/brands/{brand}/media/from-url":{"post":{"tags":["Media"],"summary":"Import an image from a URL (async)","description":"Requires scope `media:write` and a live key. Test-mode keys return 403 test_mode_write_forbidden.","parameters":[{"$ref":"#/components/parameters/idempotencyKey"},{"$ref":"#/components/parameters/brand"}],"responses":{"202":{"description":"Accepted (async)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MediaJobAccepted"}}}}}},"400":{"$ref":"#/components/responses/IdempotencyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"asset_type":{"type":"string","enum":["image","icon","logo"]}}},"example":{"url":"https://acme.coffee/press/launch-banner.jpg","asset_type":"image"}}}}}},"/brands/{brand}/jobs/{job}":{"get":{"tags":["Media"],"summary":"Poll an async media job","description":"Requires scope `media:read`. Status: pending | processing | completed | failed.","parameters":[{"$ref":"#/components/parameters/brand"},{"name":"job","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MediaJob"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/brands/{brand}/analytics/posts":{"get":{"tags":["Analytics"],"summary":"Post analytics","description":"Requires scope `analytics:read` and the `basic_analytics` (or `analytics`) plan feature. `start` is clamped to the plan\u2019s retention window.","parameters":[{"$ref":"#/components/parameters/brand"},{"name":"start","in":"query","schema":{"type":"string","format":"date"}},{"name":"end","in":"query","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsSeries"}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/brands/{brand}/analytics/accounts":{"get":{"tags":["Analytics"],"summary":"Account analytics","description":"Requires scope `analytics:read` and the `basic_analytics` (or `analytics`) plan feature.","parameters":[{"$ref":"#/components/parameters/brand"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsSeries"}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/brands/{brand}/link-in-bio":{"get":{"tags":["Link-in-Bio"],"summary":"List Link-in-Bio pages","description":"Requires scope `linkinbio:read` and the `link_in_bio` plan feature.","parameters":[{"$ref":"#/components/parameters/brand"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/LinkInBioPage"}},"links":{"$ref":"#/components/schemas/PaginationLinks"},"meta":{"$ref":"#/components/schemas/Pagination"}}}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["Link-in-Bio"],"summary":"Create a page","description":"Requires scope `linkinbio:write` and a live key. Test-mode keys return 403 test_mode_write_forbidden.","parameters":[{"$ref":"#/components/parameters/idempotencyKey"},{"$ref":"#/components/parameters/brand"}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/LinkInBioPage"}}}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"400":{"$ref":"#/components/responses/IdempotencyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"slug":{"type":"string"},"theme":{"type":"string"},"bio":{"type":"string"},"links":{"type":"array","items":{"type":"object"}}}}}}}}},"/brands/{brand}/link-in-bio/{linkInBio}":{"put":{"tags":["Link-in-Bio"],"summary":"Update a page","description":"Requires scope `linkinbio:write` and a live key. Test-mode keys return 403 test_mode_write_forbidden.","parameters":[{"$ref":"#/components/parameters/idempotencyKey"},{"$ref":"#/components/parameters/brand"},{"name":"linkInBio","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/LinkInBioPage"}}}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"400":{"$ref":"#/components/responses/IdempotencyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"slug":{"type":"string"},"theme":{"type":"string"}}}}}}},"delete":{"tags":["Link-in-Bio"],"summary":"Delete a page","description":"Requires scope `linkinbio:write` and a live key. Test-mode keys return 403 test_mode_write_forbidden.","parameters":[{"$ref":"#/components/parameters/idempotencyKey"},{"$ref":"#/components/parameters/brand"},{"name":"linkInBio","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"204":{"description":"Created"},"402":{"$ref":"#/components/responses/PaymentRequired"},"400":{"$ref":"#/components/responses/IdempotencyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/brands/{brand}/content-plans":{"get":{"tags":["Content Plans"],"summary":"List content plans","description":"Requires scope `content:read` and the `content_strategy` plan feature.","parameters":[{"$ref":"#/components/parameters/brand"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ContentPlan"}},"links":{"$ref":"#/components/schemas/PaginationLinks"},"meta":{"$ref":"#/components/schemas/Pagination"}}}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/brands/{brand}/content-plans/{plan}/items/{item}/schedule":{"post":{"tags":["Content Plans"],"summary":"Schedule a plan item into a post","description":"Requires scope `content:write` and a live key. Test-mode keys return 403 test_mode_write_forbidden.","parameters":[{"$ref":"#/components/parameters/idempotencyKey"},{"$ref":"#/components/parameters/brand"},{"name":"plan","in":"path","required":true,"schema":{"type":"integer"}},{"name":"item","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ScheduledPost"}}}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"400":{"$ref":"#/components/responses/IdempotencyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"account_ids":{"type":"array","items":{"type":"integer"}},"destination":{"type":"string","enum":["calendar","draft","approval"],"default":"calendar"}}}}}}}},"/brands/{brand}/feeds":{"get":{"tags":["Feeds"],"summary":"List RSS feeds","description":"Requires scope `feeds:read` and the `feed_reader` plan feature.","parameters":[{"$ref":"#/components/parameters/brand"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RssFeed"}},"links":{"$ref":"#/components/schemas/PaginationLinks"},"meta":{"$ref":"#/components/schemas/Pagination"}}}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["Feeds"],"summary":"Add an RSS feed","description":"Requires scope `feeds:write` and a live key. Test-mode keys return 403 test_mode_write_forbidden.","parameters":[{"$ref":"#/components/parameters/idempotencyKey"},{"$ref":"#/components/parameters/brand"}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RssFeed"}}}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"400":{"$ref":"#/components/responses/IdempotencyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string","format":"uri"},"type":{"type":"string","enum":["rss","atom","wordpress","json"]}}}}}}}},"/brands/{brand}/feeds/{feed}":{"put":{"tags":["Feeds"],"summary":"Update a feed","description":"Requires scope `feeds:write` and a live key. Test-mode keys return 403 test_mode_write_forbidden.","parameters":[{"$ref":"#/components/parameters/idempotencyKey"},{"$ref":"#/components/parameters/brand"},{"name":"feed","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RssFeed"}}}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"400":{"$ref":"#/components/responses/IdempotencyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string","format":"uri"}}}}}}},"delete":{"tags":["Feeds"],"summary":"Delete a feed","description":"Requires scope `feeds:write` and a live key. Test-mode keys return 403 test_mode_write_forbidden.","parameters":[{"$ref":"#/components/parameters/idempotencyKey"},{"$ref":"#/components/parameters/brand"},{"name":"feed","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"204":{"description":"Created"},"402":{"$ref":"#/components/responses/PaymentRequired"},"400":{"$ref":"#/components/responses/IdempotencyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/brands/{brand}/feeds/{feed}/articles":{"get":{"tags":["Feeds"],"summary":"List feed articles","description":"Requires scope `feeds:read` and the `feed_reader` plan feature.","parameters":[{"$ref":"#/components/parameters/brand"},{"name":"feed","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RssArticle"}},"links":{"$ref":"#/components/schemas/PaginationLinks"},"meta":{"$ref":"#/components/schemas/Pagination"}}}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/webhook-events":{"get":{"tags":["Webhooks"],"summary":"List available webhook events","description":"Requires scope `webhooks:read`.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEventList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/webhooks":{"get":{"tags":["Webhooks"],"summary":"List webhook endpoints","description":"Requires scope `webhooks:read` + the `webhooks` plan feature.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}},"links":{"$ref":"#/components/schemas/PaginationLinks"},"meta":{"$ref":"#/components/schemas/Pagination"}}}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["Webhooks"],"summary":"Create a webhook endpoint","description":"Requires scope `webhooks:write` and a live key. Test-mode keys return 403 test_mode_write_forbidden.","parameters":[{"$ref":"#/components/parameters/idempotencyKey"}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookEndpoint"}}}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"400":{"$ref":"#/components/responses/IdempotencyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"},"description":"Event names from /webhook-events (includes brand.created)."},"description":{"type":"string"},"is_active":{"type":"boolean"}}},"example":{"url":"https://hooks.acme.coffee/viraldashboard","events":["post.published","account.connected"],"description":"Production listener","is_active":true}}}}}},"/webhooks/{webhook}":{"get":{"tags":["Webhooks"],"summary":"Get a webhook endpoint","parameters":[{"name":"webhook","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookEndpoint"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"put":{"tags":["Webhooks"],"summary":"Update a webhook endpoint","description":"Requires scope `webhooks:write` and a live key. Test-mode keys return 403 test_mode_write_forbidden.","parameters":[{"$ref":"#/components/parameters/idempotencyKey"},{"name":"webhook","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookEndpoint"}}}}}},"400":{"$ref":"#/components/responses/IdempotencyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"is_active":{"type":"boolean"}}}}}}},"delete":{"tags":["Webhooks"],"summary":"Delete a webhook endpoint","description":"Requires scope `webhooks:write` and a live key. Test-mode keys return 403 test_mode_write_forbidden.","parameters":[{"$ref":"#/components/parameters/idempotencyKey"},{"name":"webhook","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"204":{"description":"Created"},"400":{"$ref":"#/components/responses/IdempotencyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/webhooks/{webhook}/rotate-secret":{"post":{"tags":["Webhooks"],"summary":"Rotate the signing secret","description":"Requires scope `webhooks:write` and a live key. Test-mode keys return 403 test_mode_write_forbidden.","parameters":[{"$ref":"#/components/parameters/idempotencyKey"},{"name":"webhook","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookEndpoint"}}}}}},"400":{"$ref":"#/components/responses/IdempotencyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/webhooks/{webhook}/deliveries":{"get":{"tags":["Webhooks"],"summary":"List deliveries","parameters":[{"name":"webhook","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}},"links":{"$ref":"#/components/schemas/PaginationLinks"},"meta":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/webhooks/{webhook}/deliveries/{delivery}/retry":{"post":{"tags":["Webhooks"],"summary":"Retry a delivery","description":"Requires scope `webhooks:write` and a live key. Test-mode keys return 403 test_mode_write_forbidden.","parameters":[{"$ref":"#/components/parameters/idempotencyKey"},{"name":"webhook","in":"path","required":true,"schema":{"type":"integer"}},{"name":"delivery","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookDelivery"}}}}}},"400":{"$ref":"#/components/responses/IdempotencyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/brands/{brand}/ai/captions":{"post":{"tags":["AI"],"summary":"Generate captions (15 credits)","description":"Requires scope `ai:write` and a live key. Test-mode keys return 403 test_mode_write_forbidden.","parameters":[{"$ref":"#/components/parameters/idempotencyKey"},{"$ref":"#/components/parameters/brand"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AiCaptionResult"}}}}}},"402":{"$ref":"#/components/responses/InsufficientCredits"},"400":{"$ref":"#/components/responses/IdempotencyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string"},"options":{"type":"object"}}},"example":{"prompt":"Announce our new cold brew, playful tone","options":{"platform":"instagram","count":2}}}}}}},"/brands/{brand}/ai/hashtags":{"post":{"tags":["AI"],"summary":"Suggest hashtags (12 credits)","description":"Requires scope `ai:write` and a live key. Test-mode keys return 403 test_mode_write_forbidden.","parameters":[{"$ref":"#/components/parameters/idempotencyKey"},{"$ref":"#/components/parameters/brand"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AiHashtagResult"}}}}}},"402":{"$ref":"#/components/responses/InsufficientCredits"},"400":{"$ref":"#/components/responses/IdempotencyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string"},"platform":{"type":"string"}}},"example":{"content":"Cold brew season is officially open.","platform":"instagram"}}}}}},"/brands/{brand}/ai/images":{"post":{"tags":["AI"],"summary":"Generate an image (240/1000 credits)","description":"Requires scope `ai:write` and a live key. Test-mode keys return 403 test_mode_write_forbidden.","parameters":[{"$ref":"#/components/parameters/idempotencyKey"},{"$ref":"#/components/parameters/brand"}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AiImageResult"}}}}}},"402":{"$ref":"#/components/responses/InsufficientCredits"},"400":{"$ref":"#/components/responses/IdempotencyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string"},"options":{"type":"object","properties":{"size":{"type":"string"},"quality":{"type":"string","enum":["low","medium","high","auto"]}}}}},"example":{"prompt":"A glass of cold brew on a sunlit caf\u00e9 table, photographic","options":{"size":"1024x1024","quality":"medium"}}}}}}},"/brands/{brand}/reports":{"get":{"tags":["Reports"],"summary":"List reports","parameters":[{"$ref":"#/components/parameters/brand"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Report"}},"links":{"$ref":"#/components/schemas/PaginationLinks"},"meta":{"$ref":"#/components/schemas/Pagination"}}}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["Reports"],"summary":"Create a report","description":"Requires scope `reports:write` and a live key. Test-mode keys return 403 test_mode_write_forbidden.","parameters":[{"$ref":"#/components/parameters/idempotencyKey"},{"$ref":"#/components/parameters/brand"}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Report"}}}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"400":{"$ref":"#/components/responses/IdempotencyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"widgets":{"type":"array","items":{"type":"object"}}}}}}}}},"/brands/{brand}/reports/{report}":{"get":{"tags":["Reports"],"summary":"Get a report","parameters":[{"$ref":"#/components/parameters/brand"},{"name":"report","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Report"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"put":{"tags":["Reports"],"summary":"Update a report","description":"Requires scope `reports:write` and a live key. Test-mode keys return 403 test_mode_write_forbidden.","parameters":[{"$ref":"#/components/parameters/idempotencyKey"},{"$ref":"#/components/parameters/brand"},{"name":"report","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Report"}}}}}},"400":{"$ref":"#/components/responses/IdempotencyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}}}}}}},"delete":{"tags":["Reports"],"summary":"Delete a report","description":"Requires scope `reports:write` and a live key. Test-mode keys return 403 test_mode_write_forbidden.","parameters":[{"$ref":"#/components/parameters/idempotencyKey"},{"$ref":"#/components/parameters/brand"},{"name":"report","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"204":{"description":"Created"},"400":{"$ref":"#/components/responses/IdempotencyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/brands/{brand}/reports/{report}/export":{"post":{"tags":["Reports"],"summary":"Export a report (async)","description":"Requires scope `reports:write` and a live key. Test-mode keys return 403 test_mode_write_forbidden.","parameters":[{"$ref":"#/components/parameters/idempotencyKey"},{"$ref":"#/components/parameters/brand"},{"name":"report","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"202":{"description":"Accepted (async)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ReportExportAccepted"}}}}}},"400":{"$ref":"#/components/responses/IdempotencyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"format":{"type":"string","enum":["pdf","csv","json","pptx","xlsx"]},"start":{"type":"string","format":"date"},"end":{"type":"string","format":"date"}}},"example":{"format":"pdf","start":"2026-06-12","end":"2026-07-12"}}}}}},"/brands/{brand}/reports/deliveries/{delivery}":{"get":{"tags":["Reports"],"summary":"Poll an export delivery","parameters":[{"$ref":"#/components/parameters/brand"},{"name":"delivery","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ReportDelivery"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/brands/{brand}/reports/deliveries/{delivery}/download":{"get":{"tags":["Reports"],"summary":"Download the generated report","description":"Requires scope `reports:read`. Streams the file once status is \"sent\" (409 report_not_ready otherwise). The internal storage path is never exposed.","parameters":[{"$ref":"#/components/parameters/brand"},{"name":"delivery","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"The report file","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"409":{"$ref":"#/components/responses/ReportNotReady"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/brands/{brand}/reports/{report}/schedules":{"post":{"tags":["Reports"],"summary":"Schedule recurring delivery","description":"Requires scope `reports:write` and a live key. Test-mode keys return 403 test_mode_write_forbidden.","parameters":[{"$ref":"#/components/parameters/idempotencyKey"},{"$ref":"#/components/parameters/brand"},{"name":"report","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ReportSchedule"}}}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"400":{"$ref":"#/components/responses/IdempotencyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"frequency":{"type":"string","enum":["daily","weekly","monthly","cron"]},"recipients":{"type":"array","items":{"type":"string","format":"email"}},"format":{"type":"string"}}}}}}}},"/brands/{brand}/reports/{report}/schedules/{schedule}":{"delete":{"tags":["Reports"],"summary":"Delete a schedule","description":"Requires scope `reports:write` and a live key. Test-mode keys return 403 test_mode_write_forbidden.","parameters":[{"$ref":"#/components/parameters/idempotencyKey"},{"$ref":"#/components/parameters/brand"},{"name":"report","in":"path","required":true,"schema":{"type":"integer"}},{"name":"schedule","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"204":{"description":"Created"},"400":{"$ref":"#/components/responses/IdempotencyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/brands/{brand}/conversations":{"get":{"tags":["Inbox"],"summary":"List conversations","description":"Requires scope `inbox:read` and the `inbox` plan feature. Filter with `status`, `type` (dm|comment|mention), `platform`, `search`.","parameters":[{"$ref":"#/components/parameters/brand"},{"$ref":"#/components/parameters/perPage"},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"type","in":"query","schema":{"type":"string","enum":["dm","comment","mention"]}},{"name":"platform","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Conversation"}},"links":{"$ref":"#/components/schemas/PaginationLinks"},"meta":{"$ref":"#/components/schemas/Pagination"}}}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/brands/{brand}/conversations/{conversation}":{"get":{"tags":["Inbox"],"summary":"Get a conversation","description":"Requires scope `inbox:read` + the `inbox` feature. Includes the full message thread.","parameters":[{"$ref":"#/components/parameters/brand"},{"name":"conversation","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConversationDetail"}}}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/brands/{brand}/conversations/{conversation}/reply":{"post":{"tags":["Inbox"],"summary":"Reply to a conversation (async)","description":"Requires scope `inbox:write` and a live key. Test-mode keys return 403 test_mode_write_forbidden.","parameters":[{"$ref":"#/components/parameters/idempotencyKey"},{"$ref":"#/components/parameters/brand"},{"name":"conversation","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"202":{"description":"Accepted (async)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Message"}}}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"422":{"description":"This platform/type cannot be replied to over the API (e.g. Instagram DMs) \u2014 `platform_capability_unavailable`, checked before enqueue.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"400":{"$ref":"#/components/responses/IdempotencyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","description":"The reply text."}}},"example":{"body":"Thanks for reaching out! We ship worldwide."}}}}}},"/brands/{brand}/conversations/{conversation}/status":{"put":{"tags":["Inbox"],"summary":"Update conversation status","description":"Requires scope `inbox:write` and a live key. Test-mode keys return 403 test_mode_write_forbidden.","parameters":[{"$ref":"#/components/parameters/idempotencyKey"},{"$ref":"#/components/parameters/brand"},{"name":"conversation","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConversationDetail"}}}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"400":{"$ref":"#/components/responses/IdempotencyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["open","assigned","snoozed","resolved","spam"]},"snoozed_until":{"type":"string","format":"date-time","description":"Required when status is `snoozed`."}}}}}}}},"/brands/{brand}/conversations/{conversation}/assign":{"put":{"tags":["Inbox"],"summary":"Assign a conversation","description":"Requires scope `inbox:write` and a live key. Test-mode keys return 403 test_mode_write_forbidden.","parameters":[{"$ref":"#/components/parameters/idempotencyKey"},{"$ref":"#/components/parameters/brand"},{"name":"conversation","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConversationDetail"}}}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"400":{"$ref":"#/components/responses/IdempotencyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"user_id":{"type":["integer","null"],"description":"Team member id, or null to unassign."}}}}}}}},"/brands/{brand}/conversations/{conversation}/tags":{"put":{"tags":["Inbox"],"summary":"Set conversation tags","description":"Requires scope `inbox:write` and a live key. Test-mode keys return 403 test_mode_write_forbidden.","parameters":[{"$ref":"#/components/parameters/idempotencyKey"},{"$ref":"#/components/parameters/brand"},{"name":"conversation","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConversationDetail"}}}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"400":{"$ref":"#/components/responses/IdempotencyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"string"},"description":"Replaces the existing tags."}}}}}}}},"/brands/{brand}/conversations/{conversation}/priority":{"put":{"tags":["Inbox"],"summary":"Set conversation priority","description":"Requires scope `inbox:write` and a live key. Test-mode keys return 403 test_mode_write_forbidden.","parameters":[{"$ref":"#/components/parameters/idempotencyKey"},{"$ref":"#/components/parameters/brand"},{"name":"conversation","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConversationDetail"}}}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"400":{"$ref":"#/components/responses/IdempotencyRequired"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"priority":{"type":"string","enum":["urgent","high","normal","low"]}}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"vd_{live|test}_{40}","description":"Send your key as `Authorization: Bearer vd_live_\u2026`. Scopes held by the key:\n\n- brands:read \u2014 Brands \u2014 read\n- accounts:read \u2014 Social accounts \u2014 read\n- posts:read \u2014 Posts \u2014 read\n- media:read \u2014 Media library \u2014 read\n- analytics:read \u2014 Analytics \u2014 read\n- linkinbio:read \u2014 Link-in-Bio \u2014 read\n- content:read \u2014 Content plans \u2014 read\n- feeds:read \u2014 Feeds \u2014 read\n- posts:write \u2014 Posts \u2014 write\n- media:write \u2014 Media library \u2014 write\n- linkinbio:write \u2014 Link-in-Bio \u2014 write\n- content:write \u2014 Content plans \u2014 write\n- feeds:write \u2014 Feeds \u2014 write\n- brands:write \u2014 Brands \u2014 write\n- webhooks:read \u2014 Webhooks \u2014 read\n- webhooks:write \u2014 Webhooks \u2014 write\n- ai:write \u2014 AI generation\n- reports:read \u2014 Reports \u2014 read\n- reports:write \u2014 Reports \u2014 write\n- accounts:write \u2014 Social accounts \u2014 connect/disconnect\n- inbox:read \u2014 Inbox \u2014 read conversations\n- inbox:write \u2014 Inbox \u2014 reply + triage"}},"parameters":{"brand":{"name":"brand","in":"path","required":true,"schema":{"type":"integer"},"description":"Brand id. Must be a brand the key\u2019s user can access, or the request returns 403 `brand_forbidden`."},"perPage":{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","default":20,"maximum":100}},"idempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Required on ALL writes. Replaying the same key with the same body returns the stored response (Idempotent-Replayed: true); a different body returns 409."}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per hour for this key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix epoch seconds when the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying (on 429)."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["type","code","message"],"properties":{"type":{"type":"string","enum":["authentication_error","invalid_request_error","validation_error","rate_limit_error","idempotency_error","api_error"]},"code":{"type":"string","examples":["unauthorized","brand_forbidden","insufficient_scope","not_found","rate_limited","test_mode_write_forbidden","idempotency_key_required","idempotency_error","invalid_request","limit_reached","feature_not_available","payload_too_large","unsupported_media_type","storage_limit_exceeded","invalid_media_url","invalid_feed_url","invalid_account","invalid_webhook_url","insufficient_credits","report_not_ready","invalid_credentials","invalid_site_url","oauth_required","not_oauth_platform","interactive_setup_required","reconnect_required","platform_capability_unavailable"]},"message":{"type":"string"},"errors":{"type":"object","description":"Field-level messages (validation_error only)."}}}},"examples":[{"error":{"type":"invalid_request_error","code":"brand_forbidden","message":"You do not have access to this brand."}}]},"Brand":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"slug":{"type":"string"},"website":{"type":["string","null"]},"logo":{"type":["string","null"]},"logo_url":{"type":["string","null"]},"timezone":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"examples":[{"id":412,"name":"Acme Coffee","slug":"acme-coffee","website":"https://acme.coffee","logo":"brands/412/logo.png","logo_url":"https://cdn.viraldashboard.io/brands/412/logo.png","timezone":"Europe/London","created_at":"2026-07-01T10:04:00+00:00","updated_at":"2026-07-11T08:12:33+00:00"}]},"AnalyticsRange":{"type":"object","properties":{"start":{"type":"string","format":"date"},"end":{"type":"string","format":"date"},"analytics_retention_days":{"type":"integer","description":"The plan\u2019s retention window; `start` is clamped to it."}}},"Post":{"type":"object","properties":{"id":{"type":"integer"},"content":{"type":["string","null"]},"status":{"type":"string","description":"draft | pending_approval | scheduled | publishing | published | failed"},"scheduled_at":{"type":["string","null"],"format":"date-time"},"published_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"user":{"type":["string","null"],"description":"Author\u2019s name (the list endpoint eager-loads it)."},"tags":{"type":["array","null"],"items":{"type":"string"}},"campaign":{"type":["string","null"]},"platforms":{"type":"array","items":{"type":"string"}},"media_count":{"type":"integer"}},"examples":[{"id":1000241,"content":"Ship day. The new API is live \ud83d\ude80","status":"published","scheduled_at":"2026-07-12T09:00:00+00:00","published_at":"2026-07-12T09:00:04+00:00","created_at":"2026-07-11T16:20:11+00:00","user":"Rahul","tags":["launch"],"campaign":"v2-launch","platforms":["telegram","linkedin"],"media_count":1}]},"PostDetail":{"type":"object","properties":{"id":{"type":"integer"},"content":{"type":["string","null"]},"status":{"type":"string"},"scheduled_at":{"type":["string","null"],"format":"date-time"},"published_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"user":{"type":["object","null"],"properties":{"id":{"type":"integer"},"name":{"type":"string"}}},"tags":{"type":["array","null"],"items":{"type":"string"}},"campaign":{"type":["string","null"]},"utm_parameters":{"type":["object","null"]},"is_recycled":{"type":["boolean","null"]},"platforms":{"type":"array","items":{"type":"string"}},"variants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"social_account_id":{"type":"integer"},"platform":{"type":["string","null"]},"account_name":{"type":["string","null"]},"content":{"type":["string","null"]},"status":{"type":"string"},"platform_post_url":{"type":["string","null"]},"published_at":{"type":["string","null"],"format":"date-time"}}}},"media":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string"},"url":{"type":"string"},"mime_type":{"type":["string","null"]},"size":{"type":["integer","null"]},"alt_text":{"type":["string","null"]},"sort_order":{"type":"integer"}}}}},"examples":[{"id":1000241,"content":"Ship day. The new API is live \ud83d\ude80","status":"scheduled","scheduled_at":"2026-07-13T09:00:00+00:00","published_at":null,"created_at":"2026-07-12T16:20:11+00:00","updated_at":"2026-07-12T16:20:11+00:00","user":{"id":7,"name":"Rahul"},"tags":["launch"],"campaign":"v2-launch","utm_parameters":null,"is_recycled":false,"platforms":["telegram"],"variants":[{"id":5521,"social_account_id":3310,"platform":"telegram","account_name":"testtelegramo","content":"Ship day. The new API is live \ud83d\ude80","status":"scheduled","platform_post_url":null,"published_at":null}],"media":[{"id":8814,"type":"image","url":"https://cdn.viraldashboard.io/media/8814.jpg","mime_type":"image/jpeg","size":148233,"alt_text":"Launch banner","sort_order":0}]}]},"SocialAccount":{"type":"object","properties":{"id":{"type":"integer"},"platform":{"type":"string"},"platform_account_id":{"type":"string"},"name":{"type":["string","null"]},"username":{"type":["string","null"]},"avatar":{"type":["string","null"]},"status":{"type":"string","description":"active | expired | revoked | error"},"access_token_expires_at":{"type":["string","null"],"format":"date-time"},"last_synced_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}},"examples":[{"id":3310,"platform":"telegram","platform_account_id":"-1002145558877","name":"testtelegramo","username":"testtelegramo","avatar":null,"status":"active","access_token_expires_at":null,"last_synced_at":"2026-07-12T11:02:00+00:00","created_at":"2026-07-12T10:58:41+00:00"}]},"MediaAsset":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"type":{"type":"string"},"mime_type":{"type":["string","null"]},"file_size":{"type":["integer","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"url":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}},"examples":[{"id":8814,"name":"launch-banner.jpg","type":"image","mime_type":"image/jpeg","file_size":148233,"width":1200,"height":675,"url":"https://cdn.viraldashboard.io/media/8814.jpg","created_at":"2026-07-12T16:18:02+00:00"}]},"LinkInBioPage":{"type":"object","properties":{"id":{"type":"integer"},"slug":{"type":"string"},"title":{"type":["string","null"]},"is_published":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}},"ContentPlan":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":["string","null"]},"status":{"type":"string"},"start_date":{"type":["string","null"],"format":"date"},"created_at":{"type":"string","format":"date-time"}}},"RssFeed":{"type":"object","properties":{"id":{"type":"integer"},"brand_id":{"type":"integer"},"name":{"type":"string"},"url":{"type":"string"},"type":{"type":"string"},"refresh_interval":{"type":["string","null"]},"auto_publish":{"type":"boolean"},"is_active":{"type":"boolean"},"post_template":{"type":["object","null"]},"articles_count":{"type":["integer","null"]},"last_fetched_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"RssArticle":{"type":"object","properties":{"id":{"type":"integer"},"rss_feed_id":{"type":"integer"},"title":{"type":"string"},"excerpt":{"type":["string","null"]},"url":{"type":"string"},"image_url":{"type":["string","null"]},"author":{"type":["string","null"]},"is_bookmarked":{"type":"boolean"},"is_posted":{"type":"boolean"},"post_id":{"type":["integer","null"]},"published_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"integer"},"url":{"type":"string"},"description":{"type":["string","null"]},"events":{"type":"array","items":{"type":"string"}},"is_active":{"type":"boolean"},"failure_count":{"type":["integer","null"]},"last_triggered_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"secret":{"type":"string","description":"Returned ONCE on create + rotate only; never on read."}},"examples":[{"id":59,"url":"https://hooks.acme.coffee/viraldashboard","description":"Production listener","events":["post.published","account.connected"],"is_active":true,"failure_count":0,"last_triggered_at":"2026-07-12T12:41:09+00:00","created_at":"2026-07-10T09:00:00+00:00","secret":"whsec_9f3c2a7e5b18d4460c1e7a92f83b6d05 \u2014 shown on create/rotate only"}]},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"integer"},"event":{"type":"string"},"payload":{"type":"object"},"response_code":{"type":["integer","null"]},"status":{"type":"string","description":"pending | delivered | failed"},"attempts":{"type":"integer"},"max_attempts":{"type":"integer"},"duration_ms":{"type":["number","null"]},"delivered_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}},"examples":[{"id":1204,"event":"post.published","payload":{"event":"post.published","data":{"post_id":1000241,"brand_id":412,"platform":"telegram"}},"response_code":200,"status":"delivered","attempts":1,"max_attempts":5,"duration_ms":214.7,"delivered_at":"2026-07-12T12:41:09+00:00","created_at":"2026-07-12T12:41:08+00:00"}]},"Report":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":["string","null"]},"brand_id":{"type":"integer"},"cover_title":{"type":["string","null"]},"cover_description":{"type":["string","null"]},"filters":{"type":["object","null"]},"branding":{"type":["object","null"]},"is_template":{"type":"boolean"},"widgets_count":{"type":["integer","null"]},"schedules_count":{"type":["integer","null"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ReportDelivery":{"type":"object","properties":{"id":{"type":"integer"},"status":{"type":"string","description":"pending | generating | sent | failed"},"format":{"type":"string"},"error":{"type":["string","null"]},"ready":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"}},"examples":[{"id":77,"status":"sent","format":"pdf","error":null,"ready":true,"created_at":"2026-07-12T13:00:00+00:00","completed_at":"2026-07-12T13:00:01+00:00"}]},"Platform":{"type":"object","properties":{"platform":{"type":"string"},"mode":{"type":"string","description":"oauth | self_connect | self_connect_oauth"},"connect_method":{"type":"string","description":"credentials | authorize_url"},"credential_fields":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"required":{"type":"boolean"}}}}},"examples":[{"platform":"telegram","mode":"self_connect","connect_method":"credentials","credential_fields":[{"name":"bot_token","label":"Bot token","type":"password","required":true},{"name":"chat_id","label":"Channel / chat id","type":"text","required":true}]}]},"Pagination":{"type":"object","properties":{"current_page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"},"last_page":{"type":["integer","null"]},"from":{"type":["integer","null"]},"to":{"type":["integer","null"]},"path":{"type":["string","null"]},"links":{"type":"array","description":"Page-number descriptors for rendering a pager.","items":{"type":"object","properties":{"url":{"type":["string","null"]},"label":{"type":"string"},"page":{"type":["integer","null"]},"active":{"type":"boolean"}}}}},"examples":[{"current_page":1,"per_page":20,"total":43,"last_page":3,"from":1,"to":20,"path":"https://vm.viraldashboard.io/api/public/v1/brands/412/posts","links":[{"url":null,"label":"« Previous","page":null,"active":false}]}]},"PaginationLinks":{"type":"object","properties":{"first":{"type":["string","null"]},"last":{"type":["string","null"]},"prev":{"type":["string","null"],"description":"null on the first page."},"next":{"type":["string","null"],"description":"null on the last page \u2014 the loop terminator."}},"examples":[{"first":"https://vm.viraldashboard.io/api/public/v1/brands/412/posts?page=1","last":"https://vm.viraldashboard.io/api/public/v1/brands/412/posts?page=3","prev":null,"next":"https://vm.viraldashboard.io/api/public/v1/brands/412/posts?page=2"}]},"AuthorizationGrant":{"type":"object","properties":{"platform":{"type":"string"},"authorization_url":{"type":"string","description":"One-time capability/secret \u2014 single-use, expires. Send only to the intended person."},"expires_in":{"type":"integer","description":"Seconds until the URL expires."}},"examples":[{"platform":"facebook","authorization_url":"https://vm.viraldashboard.io/social/connect/facebook?state=eyJhbGciOi\u2026","expires_in":1800}]},"DisconnectResult":{"type":"object","properties":{"result":{"type":"string","description":"detached (still on other brands) | revoked (token revoked + deleted)"}},"examples":[{"result":"revoked"}]},"PostStatus":{"type":"object","properties":{"id":{"type":"integer"},"status":{"type":"string"},"scheduled_at":{"type":["string","null"],"format":"date-time"},"published_at":{"type":["string","null"],"format":"date-time"}},"examples":[{"id":1000241,"status":"published","scheduled_at":"2026-07-12T09:00:00+00:00","published_at":"2026-07-12T09:00:04+00:00"}]},"MediaJobAccepted":{"type":"object","properties":{"job_id":{"type":"integer"},"status":{"type":"string","description":"pending"},"poll_url":{"type":"string"}},"examples":[{"job_id":91,"status":"pending","poll_url":"https://vm.viraldashboard.io/api/public/v1/brands/412/jobs/91"}]},"MediaJob":{"type":"object","properties":{"job_id":{"type":"integer"},"status":{"type":"string","description":"pending | processing | completed | failed"},"workspace_asset_id":{"type":["integer","null"]},"size_bytes":{"type":["integer","null"]},"error":{"type":["string","null"]}},"examples":[{"job_id":91,"status":"completed","workspace_asset_id":8814,"size_bytes":148233,"error":null}]},"ScheduledPost":{"type":"object","properties":{"post_id":{"type":"integer"},"post_status":{"type":"string"},"item_status":{"type":"string"}},"examples":[{"post_id":1000242,"post_status":"scheduled","item_status":"scheduled"}]},"ReportExportAccepted":{"type":"object","properties":{"delivery_id":{"type":"integer"},"status":{"type":"string"},"poll_url":{"type":"string"}},"examples":[{"delivery_id":77,"status":"pending","poll_url":"https://vm.viraldashboard.io/api/public/v1/brands/412/reports/deliveries/77"}]},"ReportSchedule":{"type":"object","properties":{"id":{"type":"integer"},"frequency":{"type":"string","description":"daily | weekly | monthly | cron"},"format":{"type":["string","null"]},"is_active":{"type":"boolean"},"next_send_at":{"type":["string","null"],"format":"date-time"}}},"Conversation":{"type":"object","properties":{"id":{"type":"integer"},"platform":{"type":"string"},"type":{"type":"string","description":"dm | comment | mention"},"status":{"type":"string","description":"open | assigned | snoozed | resolved | spam"},"priority":{"type":"string","description":"urgent | high | normal | low"},"subject":{"type":["string","null"]},"contact":{"type":["object","null"],"properties":{"id":{"type":"integer"},"name":{"type":["string","null"]},"avatar":{"type":["string","null"]}}},"account":{"type":["object","null"],"properties":{"platform":{"type":"string"},"name":{"type":["string","null"]}}},"assignee":{"type":["string","null"]},"tags":{"type":["array","null"],"items":{"type":"string"}},"sentiment":{"type":["number","null"]},"intent":{"type":["string","null"]},"message_count":{"type":"integer"},"last_message_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"examples":[{"id":5521,"platform":"facebook","type":"comment","status":"open","priority":"normal","subject":null,"contact":{"id":88,"name":"Sam Rivera","avatar":null},"account":{"platform":"facebook","name":"Acme Coffee"},"assignee":null,"tags":["vip"],"sentiment":0.4,"intent":"question","message_count":3,"last_message_at":"2026-07-13T12:41:09+00:00","updated_at":"2026-07-13T12:41:09+00:00"}]},"ConversationDetail":{"type":"object","properties":{"id":{"type":"integer"},"platform":{"type":"string"},"type":{"type":"string"},"status":{"type":"string"},"priority":{"type":"string"},"subject":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"sentiment":{"type":["number","null"]},"intent":{"type":["string","null"]},"assigned_to":{"type":["integer","null"]},"detected_language":{"type":["string","null"]},"ai_confidence":{"type":["number","null"]},"needs_escalation":{"type":["boolean","null"]},"escalation_reason":{"type":["string","null"]},"contact":{"type":["object","null"]},"account":{"type":["object","null"]},"assignee":{"type":["string","null"]},"messages":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"last_message_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Message":{"type":"object","properties":{"id":{"type":"integer"},"direction":{"type":"string","description":"inbound | outbound"},"body":{"type":["string","null"]},"attachments":{"type":["array","null"],"items":{"type":"object"}},"sender_type":{"type":"string","description":"contact | user | system"},"is_note":{"type":["boolean","null"]},"delivery_status":{"type":["string","null"],"description":"Outbound lifecycle the async reply poll watches: pending | sent | failed. null for inbound + notes."},"delivery_error":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"examples":[{"id":9012,"direction":"outbound","body":"Thanks for reaching out!","attachments":null,"sender_type":"user","is_note":false,"delivery_status":"pending","delivery_error":null,"created_at":"2026-07-13T12:45:00+00:00","updated_at":"2026-07-13T12:45:00+00:00"}]},"WebhookEventList":{"type":"object","properties":{"data":{"type":"array","items":{"type":"string"},"description":"Available event names (e.g. post.published, brand.created, account.connected)."}}},"AiCaptionResult":{"type":"object","properties":{"captions":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"hashtags":{"type":"array","items":{"type":"string"}}}}},"error":{"type":["string","null"],"description":"Present only on generation failure (request is refunded)."}},"examples":[{"captions":[{"text":"Cold brew season is officially open. \u2615","hashtags":["#coldbrew","#coffee"]},{"text":"Your 3pm slump called. We answered.","hashtags":["#coffeetime","#cafe"]}],"error":null}]},"AiHashtagResult":{"type":"object","properties":{"hashtags":{"type":"array","items":{"type":"string"}},"categories":{"type":"object","properties":{"popular":{"type":"array","items":{"type":"string"}},"niche":{"type":"array","items":{"type":"string"}},"branded":{"type":"array","items":{"type":"string"}}}},"error":{"type":["string","null"]}},"examples":[{"hashtags":["#coldbrew","#specialtycoffee","#acmecoffee"],"categories":{"popular":["#coffee","#coffeelover"],"niche":["#coldbrew","#specialtycoffee"],"branded":["#acmecoffee"]},"error":null}]},"AiImageResult":{"type":"object","properties":{"url":{"type":["string","null"],"description":"Same-origin stored image URL (provider URLs are re-hosted)."},"error":{"type":["string","null"]}},"examples":[{"url":"https://cdn.viraldashboard.io/media/8901.png","error":null}]},"AnalyticsSeries":{"type":"object","properties":{"data":{"description":"Metric rows (posts) or a summary object (accounts) \u2014 shape depends on the endpoint."},"range":{"$ref":"#/components/schemas/AnalyticsRange"}}}},"responses":{"Unauthorized":{"description":"Missing/invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Brand not accessible, or key missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"PaymentRequired":{"description":"The tenant\u2019s plan does not include this feature.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Per-key rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"IdempotencyRequired":{"description":"Missing Idempotency-Key on a write.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"The Idempotency-Key was reused with a different request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"PayloadTooLarge":{"description":"Upload exceeds the maximum size.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UnsupportedMediaType":{"description":"The uploaded bytes are not an allowed image type (validated by magic bytes).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unprocessable":{"description":"Validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InsufficientCredits":{"description":"Not enough AI credits for this operation (or storage limit exceeded before charge).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ReportNotReady":{"description":"The report export is still generating \u2014 poll the delivery until status is \"sent\".","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}