{ "openapi": "3.1.0", "info": { "title": "SmartlyQ API", "version": "1.0.0", "description": "# SmartlyQ API\n\nREST API for the SmartlyQ platform: generate content, manage social posts, chatbots, media, and more.\n\n## Quick Start\n\n1. Get an API key from [app.smartlyq.com/my/developer](https://app.smartlyq.com/my/developer).\n2. Send your first request:\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_API_KEY\" https://api.smartlyq.com/v1/me\n```\n\n## Idempotency\n\nEvery `POST`/`PUT`/`PATCH` endpoint supports safe retries: send an `X-Idempotency-Key` header (any unique string, e.g. a UUID). If the same key is replayed within 24 hours with the same request, you get the original response back - the action never runs twice, and you are never double-billed. Reusing a key with a *different* body or endpoint returns `409 IDEMPOTENCY_CONFLICT`.\n\n```bash\ncurl -X POST https://api.smartlyq.com/v1/social/posts/schedule \\\n -H \"Authorization: Bearer sqk_live_xxxx\" \\\n -H \"X-Idempotency-Key: 5f0c9a4e-2b7d-4d1a-9c58-e2ff10c3a771\" \\\n -d '{...}'\n```\n\n## Authentication\n\nAll requests (except health/docs) require a **Bearer token**. Use your API key as the token:\n\n- **Key types:** `sqk_live_*` (live) or `sqk_test_*` (test/sandbox).\n- **Header:** `Authorization: Bearer sqk_live_xxxx` or `Authorization: Bearer sqk_test_xxxx`.\n\n| Scope | Description |\n|-------|-------------|\n| `articles:read` | List and get articles |\n| `articles:write` | Generate, delete articles |\n| `images:read` | List and get images |\n| `images:write` | Generate, delete images |\n| `videos:read` | List and get videos |\n| `videos:write` | Generate, delete videos |\n| `presentations:read` | List and get presentations |\n| `presentations:write` | Generate presentations |\n| `social:read` | Accounts (health, follower stats, platform lookups), posts, queues, comments, DMs, reviews, pre-flight validation, Reddit research |\n| `social:write` | Create/schedule/bulk posts, recycling, unpublish, queues, reply to comments/DMs/reviews, account rename/move, account groups |\n| `audio:read` | Get audio resources |\n| `audio:write` | Text-to-speech, speech-to-text |\n| `urls:read` | List and get short URLs and stats |\n| `urls:write` | Shorten, delete URLs |\n| `captain:use` | AI Captain messages and conversations |\n| `chatbot:use` | Chatbots, train, messages, conversations |\n| `media:read` | List and get media |\n| `media:write` | Upload, delete media |\n| `analytics:read` | Overview, post and account analytics, derived insights (best-time, decay, frequency), inbox analytics |\n| `jobs:read` | List and get async jobs, cancel |\n| `seo:read` | Keyword research, SERP, rank tracking, competitors, backlinks, on-page audits |\n| `contacts:read` | List and get CRM contacts, tags, notes; list automations and their runs |\n| `contacts:write` | Create/update/delete contacts (single or bulk); tags and notes; enroll in, activate and trigger automations |\n| `opportunities:read` | List pipelines and deals/opportunities |\n| `opportunities:write` | Create/update deals, move stages, set status |\n| `webhooks:read` | List webhooks and delivery logs |\n| `webhooks:write` | Create, update, test and delete webhooks |\n| `logs:read` | Read your API request + webhook delivery logs |\n| `workspaces:read` | List and get sub-account workspaces |\n| `workspaces:write` | Create, disable SaaS, and delete sub-account workspaces |\n| `workspaces:bulk` | Apply pause / resume / disable-SaaS to many sub-accounts at once (high-trust; requires an active SaaS plan) |\n\n## Billing & Credits\n\n- **Prepaid wallet:** API usage is deducted from your Developer API wallet (credits in SQC).\n- **Pricing:** See the [pricing table](https://smartlyq.com/pricing) and in-app Developer dashboard for per-operation costs.\n- **How it works:** Each billable request (e.g. generate, post, chatbot message) consumes credits; response may include `usage` with `cost` and `balance_remaining`.\n- **Top up:** Add credits via [app.smartlyq.com/my/developer](https://app.smartlyq.com/my/developer) (wallet / top-up).\n\n## Rate Limiting\n\nLimits apply per API key (and may be enforced per user or IP). Default is 60 requests per minute per key (overridable per key).\n\nResponse headers:\n\n| Header | Description |\n|--------|-------------|\n| `X-RateLimit-Limit` | Max requests per window |\n| `X-RateLimit-Remaining` | Remaining in current window |\n| `X-RateLimit-Reset` | Unix timestamp when the window resets |\n\nWhen exceeded: HTTP `429` with `Retry-After` header.\n\n## Errors\n\nErrors are JSON with a consistent shape:\n\n```json\n{\n \"success\": false,\n \"error\": {\n \"code\": \"ERROR_CODE\",\n \"message\": \"Human-readable message\",\n \"details\": {}\n },\n \"meta\": { \"request_id\": \"...\", \"timestamp\": \"...\" }\n}\n```\n\n| HTTP | Code | Meaning |\n|-----|------|---------|\n| 400 | `BAD_REQUEST` | Malformed or invalid request |\n| 401 | `UNAUTHORIZED` | Missing or invalid API key |\n| 402 | `INSUFFICIENT_BALANCE` | Not enough credits |\n| 403 | `FORBIDDEN` | Valid key but insufficient scope or access |\n| 404 | `RESOURCE_NOT_FOUND` | Resource does not exist |\n| 409 | `CONFLICT` | Conflict (e.g. duplicate idempotency) |\n| 422 | `VALIDATION_ERROR` | Validation failed (fields in details) |\n| 429 | `RATE_LIMIT_EXCEEDED` | Too many requests |\n| 500 | `INTERNAL_ERROR` | Server error |\n\n## Async Jobs & Polling\n\nSome operations (e.g. article or video generation) return **HTTP 202 Accepted** with a `job_id`. Poll for status:\n\n- **Poll:** `GET /jobs/{job_id}` until `status` is `completed`, `failed`, or `cancelled`.\n- Response includes `result` or `error` when finished.\n\n## Webhooks\n\nConfigure webhook URLs in the Developer dashboard. We send HTTP POST to your URL with a signed payload.\n\n- **Verification:** Validate signature using your webhook secret (see dashboard).\n- **Events:** 25 events across posting, accounts, inbox, jobs, billing, and CRM - e.g. `post.published`, `comment.received`, `contact.created`. Full catalog with payload schemas: the `webhooks` object in this spec and the [Webhooks guide](https://docs.smartlyq.com/guides/webhooks).\n\n## Idempotency\n\nFor POST/PUT/PATCH, send **`X-Idempotency-Key`** (unique value per logical operation). Within 24 hours, the same key returns the same response without re-executing.\n\n## Pagination\n\n- **Offset:** `page` (1-based) and `per_page` (default 20, max 100).\n- Response includes `pagination` with `page`, `per_page`, `total`, `pages`.\n\n## Versioning\n\nCurrent version is **v1**. Base path: `https://api.smartlyq.com/v1`. Future versions will use new path prefixes (e.g. `/v2/`).\n", "contact": { "name": "SmartlyQ Support", "url": "https://smartlyq.com", "email": "support@smartlyq.com" }, "license": { "name": "Proprietary", "url": "https://smartlyq.com/terms" } }, "servers": [ { "url": "https://api.smartlyq.com/v1", "description": "Production" } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "CRM Contacts", "description": "CRM contacts: create, update, upsert, tags and notes" }, { "name": "CRM Custom Fields", "description": "Custom field (custom attribute) definitions" }, { "name": "CRM Opportunities", "description": "Sales pipelines and deals/opportunities" }, { "name": "Workspaces", "description": "Create sub-account workspaces" }, { "name": "Articles", "description": "Long-form article generation and management" }, { "name": "Images", "description": "AI image generation and listing" }, { "name": "Videos", "description": "AI video generation and listing" }, { "name": "Social", "description": "Social accounts and post scheduling" }, { "name": "Content", "description": "Content rewriting" }, { "name": "Audio", "description": "Text-to-speech and speech-to-text" }, { "name": "URLs", "description": "URL shortening and analytics" }, { "name": "AI Captain", "description": "AI Captain conversations" }, { "name": "Chatbot", "description": "Chatbots, training, and conversations" }, { "name": "Media", "description": "Media library and uploads" }, { "name": "Analytics", "description": "Analytics overview and reports" }, { "name": "Jobs", "description": "Async job status and cancellation" }, { "name": "SEO", "description": "DataForSEO-backed keyword research, SERP, rank tracking, competitors, backlinks and on-page audits" }, { "name": "Account", "description": "Current user, usage, and balance" }, { "name": "Comments", "description": "Comments endpoints" }, { "name": "Direct Messages", "description": "Direct Messages endpoints" }, { "name": "Webhooks", "description": "Subscribe to event notifications (HMAC-signed deliveries with retries)." }, { "name": "Shorts", "description": "Magic Shorts: turn long videos into ranked viral clips" }, { "name": "Presentations", "description": "AI presentation (slide deck) generation from a prompt" }, { "name": "Logs", "description": "Your own API request and webhook delivery history." }, { "name": "WhatsApp", "description": "WhatsApp Business Cloud messaging, templates and business profile." } ], "paths": { "/articles/generate": { "post": { "summary": "Generate article", "description": "Start article generation. Returns 202 with job_id; poll GET /jobs/{job_id} for result. Either `topic` or `keywords` must be provided.", "operationId": "generateArticle", "tags": [ "Articles" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArticleGenerateRequest" } } } }, "responses": { "202": { "description": "Accepted; poll job for result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobCreatedResponse" }, "example": { "success": true, "data": { "job_id": "ext_7f2c91" }, "usage": { "units": 1, "cost": "0.0150", "balance_remaining": "99.9850" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientBalance" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/articles": { "get": { "summary": "List articles", "operationId": "listArticles", "tags": [ "Articles" ], "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PerPageParam" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "draft", "published" ] } }, { "name": "search", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of articles", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArticleListResponse" }, "example": { "success": true, "data": [ { "id": 128, "title": "Product launch announcement", "content": "Big news - our summer collection is live! ☀️", "status": "published", "created_at": "2026-07-26T09:41:22Z" } ], "pagination": { "page": 1, "per_page": 1, "total": 42, "pages": 1 }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/articles/{article_id}": { "get": { "summary": "Get article", "operationId": "getArticle", "tags": [ "Articles" ], "parameters": [ { "$ref": "#/components/parameters/ArticleIdParam" } ], "responses": { "200": { "description": "Single article", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArticleSingleResponse" }, "example": { "success": true, "data": { "id": 128, "title": "Product launch announcement", "content": "Big news - our summer collection is live! ☀️", "status": "published", "created_at": "2026-07-26T09:41:22Z" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "summary": "Delete article", "operationId": "deleteArticle", "tags": [ "Articles" ], "parameters": [ { "$ref": "#/components/parameters/ArticleIdParam" } ], "responses": { "204": { "description": "Article deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/images/generate": { "post": { "summary": "Generate image", "description": "Returns 202 with job_id for async generation. Either `prompt` or `description` must be provided.", "operationId": "generateImage", "tags": [ "Images" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageGenerateRequest" } } } }, "responses": { "202": { "description": "Accepted; poll job for result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobCreatedResponse" }, "example": { "success": true, "data": { "job_id": "ext_7f2c91" }, "usage": { "units": 1, "cost": "0.0150", "balance_remaining": "99.9850" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientBalance" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/images": { "get": { "summary": "List images", "operationId": "listImages", "tags": [ "Images" ], "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PerPageParam" }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "style", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of images", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageListResponse" }, "example": { "success": true, "data": [ { "id": 128, "url": "https://example.com/launch", "prompt": "example-prompt", "style": "example-style", "created_at": "2026-07-26T09:41:22Z" } ], "pagination": { "page": 1, "per_page": 1, "total": 42, "pages": 1 }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/images/{image_id}": { "get": { "summary": "Get image", "operationId": "getImage", "tags": [ "Images" ], "parameters": [ { "$ref": "#/components/parameters/ImageIdParam" } ], "responses": { "200": { "description": "Single image", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageSingleResponse" }, "example": { "success": true, "data": { "id": 128, "url": "https://example.com/launch", "prompt": "example-prompt", "style": "example-style", "created_at": "2026-07-26T09:41:22Z" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "summary": "Delete image", "operationId": "deleteImage", "tags": [ "Images" ], "parameters": [ { "$ref": "#/components/parameters/ImageIdParam" } ], "responses": { "204": { "description": "Image deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/videos/models": { "get": { "summary": "List available video models", "description": "Returns every model currently available for video generation, including valid parameter values for each model and generation type.\n\nCall this endpoint before submitting a generation request to discover what options a specific model supports. Empty arrays (`[]`) mean the parameter is not applicable. Boolean `supports_*` flags indicate optional feature availability.", "operationId": "listVideoModels", "tags": [ "Videos" ], "responses": { "200": { "description": "List of available models with their capabilities", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoModelsResponse" }, "example": { "success": true, "data": [ { "model": "kling-v2-1", "type": "text_to_video", "params": { "duration": [ 5, 10 ], "resolution": [], "mode": [ "Standard", "Professional" ], "aspect_ratio": [ "16:9", "9:16", "1:1" ], "style": [], "movement": [], "supports_negative_prompt": true, "supports_seed": false, "supports_generate_audio": false, "supports_camera_fixed": false, "prompt_max_length": 2500 } }, { "model": "pixverse-v4-5", "type": "text_to_video", "params": { "duration": [ 5, 8 ], "resolution": [ "360p", "540p", "720p", "1080p" ], "mode": [ "Normal", "Fast" ], "aspect_ratio": [ "16:9", "9:16", "1:1", "4:3", "3:4" ], "style": [ "Auto", "Anime", "3D Animation", "Comic", "Clay", "Cyberpunk" ], "movement": [], "supports_negative_prompt": false, "supports_seed": true, "supports_generate_audio": false, "supports_camera_fixed": false, "prompt_max_length": 2000 } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/videos/generate": { "post": { "summary": "Generate video", "description": "Submits a video generation request. Returns `202 Accepted` immediately with a `job_uid`; poll `GET /v1/jobs/{job_uid}` for status and the final video URL.\n\n**Before submitting:** call `GET /v1/videos/models` to retrieve the valid parameter values (`duration`, `resolution`, `mode`, `aspect_ratio`, etc.) for your chosen model. Passing an unsupported value returns a `422` validation error.\n\n**Billing:** the cost is deducted from your API wallet when the job is accepted. If video generation fails on the provider side the charge is automatically refunded.", "operationId": "generateVideo", "tags": [ "Videos" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoGenerateRequest" }, "examples": { "text_to_video": { "summary": "Text-to-video (Kling v2.1)", "value": { "model": "kling-v2-1", "type": "text_to_video", "prompt": "A lone astronaut walks across a crimson desert at sunset", "duration": 10, "mode": "Professional", "aspect_ratio": "16:9" } }, "image_to_video": { "summary": "Image-to-video (Pixverse v4.5)", "value": { "model": "pixverse-v4-5", "type": "image_to_video", "image_url": "https://example.com/my-image.jpg", "prompt": "Camera slowly pulls back to reveal the full scene", "duration": 5, "resolution": "1080p", "style": "Anime" } } } } } }, "responses": { "202": { "description": "Accepted — poll GET /v1/jobs/{job_uid} for result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoJobCreatedResponse" }, "example": { "success": true, "data": { "job_uid": "job_a1b2c3d4e5f6", "status": "queued" }, "usage": { "units": 1, "cost": "0.2800", "balance_remaining": "14.7200" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientBalance" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/videos": { "get": { "summary": "List videos", "operationId": "listVideos", "tags": [ "Videos" ], "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PerPageParam" }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "style", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of videos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoListResponse" }, "example": { "success": true, "data": [ { "id": "a1b2c3d4e5f6", "model": "kling-v2-1", "prompt": "example-prompt", "url": "https://example.com/launch", "status": 1, "created": "2026-07-26T09:41:22Z" } ], "pagination": { "page": 1, "per_page": 1, "total": 42, "pages": 1 }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/videos/{video_id}": { "get": { "summary": "Get video", "operationId": "getVideo", "tags": [ "Videos" ], "parameters": [ { "$ref": "#/components/parameters/VideoIdParam" } ], "responses": { "200": { "description": "Single video", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoSingleResponse" }, "example": { "success": true, "data": { "id": "a1b2c3d4e5f6", "model": "kling-v2-1", "prompt": "example-prompt", "url": "https://example.com/launch", "status": 1, "created": "2026-07-26T09:41:22Z" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "summary": "Delete video", "operationId": "deleteVideo", "tags": [ "Videos" ], "parameters": [ { "$ref": "#/components/parameters/VideoIdParam" } ], "responses": { "204": { "description": "Video deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/social/accounts": { "get": { "summary": "List social accounts", "description": "Returns all connected social media accounts for the authenticated user.", "operationId": "listSocialAccounts", "tags": [ "Social" ], "responses": { "200": { "description": "List of social accounts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SocialAccountListResponse" }, "example": { "success": true, "data": [ { "id": 128, "platform": "twitter", "name": "Acme Corp" } ], "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "parameters": [ { "$ref": "#/components/parameters/ProfileHeader" } ] } }, "/social/posts": { "post": { "summary": "Create post (publish immediately)", "operationId": "createSocialPost", "tags": [ "Social" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SocialPostCreateRequest" } } } }, "responses": { "201": { "description": "Post created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SocialPostResponse" }, "example": { "success": true, "data": { "id": 128, "content": "Big news - our summer collection is live! ☀️", "platforms": [ "twitter" ], "status": "published", "scheduled_time": "2026-07-26T09:41:22Z", "published_at": "2026-07-26T09:41:22Z", "created_at": "2026-07-26T09:41:22Z" }, "usage": { "units": 1, "cost": "0.0150", "balance_remaining": "99.9850" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientBalance" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "409": { "description": "Duplicate content within 24h", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "DUPLICATE_CONTENT" ] }, "message": { "type": "string" }, "details": { "type": "object", "properties": { "existing_post_id": { "type": "integer" } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } } } }, "parameters": [ { "$ref": "#/components/parameters/ProfileHeader" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 64, "pattern": "^[A-Za-z0-9._:-]{1,64}$" }, "description": "Client idempotency key (X-Request-Id accepted as an alias). Send a fresh key per logical post and REUSE it when retrying that exact call after a timeout / 5xx / connection reset: the retry returns the original post with HTTP 200 and `idempotent_replay: true` instead of creating a duplicate. A key permanently identifies its post in the workspace (deleting the post frees the key). See the Idempotency guide." } ] }, "get": { "summary": "List social posts", "operationId": "listSocialPosts", "tags": [ "Social" ], "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PerPageParam" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "scheduled", "published", "failed" ] } }, { "name": "platform", "in": "query", "schema": { "type": "string" }, "description": "Filter by social platform" }, { "$ref": "#/components/parameters/ProfileHeader" } ], "responses": { "200": { "description": "Paginated list of posts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SocialPostListResponse" }, "example": { "success": true, "data": [ { "id": 128, "content": "Big news - our summer collection is live! ☀️", "platforms": [ "twitter" ], "status": "published", "scheduled_time": "2026-07-26T09:41:22Z", "published_at": "2026-07-26T09:41:22Z", "created_at": "2026-07-26T09:41:22Z" } ], "pagination": { "page": 1, "per_page": 1, "total": 42, "pages": 1 }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "description": " Posts imported by external sync carry status 'external' - filter with ?status=external." } }, "/social/posts/schedule": { "post": { "summary": "Schedule post", "operationId": "scheduleSocialPost", "tags": [ "Social" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SocialPostScheduleRequest" } } } }, "responses": { "201": { "description": "Post scheduled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SocialPostResponse" }, "example": { "success": true, "data": { "id": 128, "content": "Big news - our summer collection is live! ☀️", "platforms": [ "twitter" ], "status": "published", "scheduled_time": "2026-07-26T09:41:22Z", "published_at": "2026-07-26T09:41:22Z", "created_at": "2026-07-26T09:41:22Z" }, "usage": { "units": 1, "cost": "0.0150", "balance_remaining": "99.9850" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientBalance" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "409": { "description": "Duplicate content within 24h", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "DUPLICATE_CONTENT" ] }, "message": { "type": "string" }, "details": { "type": "object", "properties": { "existing_post_id": { "type": "integer" } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } } } }, "parameters": [ { "$ref": "#/components/parameters/ProfileHeader" }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 64, "pattern": "^[A-Za-z0-9._:-]{1,64}$" }, "description": "Client idempotency key (X-Request-Id accepted as an alias). Send a fresh key per logical post and REUSE it when retrying that exact call after a timeout / 5xx / connection reset: the retry returns the original post with HTTP 200 and `idempotent_replay: true` instead of creating a duplicate. A key permanently identifies its post in the workspace (deleting the post frees the key). See the Idempotency guide." } ], "description": " Pass queue_id (instead of scheduled_time) to drop the post into a posting queue's next open slot. Supports evergreen recycling via the optional `recycle` object: each published occurrence automatically schedules the next one until the chain hits its bound." } }, "/social/posts/{post_id}": { "get": { "summary": "Get social post", "operationId": "getSocialPost", "tags": [ "Social" ], "parameters": [ { "$ref": "#/components/parameters/PostIdParam" } ], "responses": { "200": { "description": "Single post", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SocialPostSingleResponse" }, "example": { "success": true, "data": { "id": 128, "content": "Big news - our summer collection is live! ☀️", "platforms": [ "twitter" ], "status": "published", "scheduled_time": "2026-07-26T09:41:22Z", "published_at": "2026-07-26T09:41:22Z", "created_at": "2026-07-26T09:41:22Z" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "summary": "Update social post", "operationId": "updateSocialPost", "tags": [ "Social" ], "parameters": [ { "$ref": "#/components/parameters/PostIdParam" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SocialPostUpdateRequest" } } } }, "responses": { "200": { "description": "Updated post", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SocialPostSingleResponse" }, "example": { "success": true, "data": { "id": 128, "content": "Big news - our summer collection is live! ☀️", "platforms": [ "twitter" ], "status": "published", "scheduled_time": "2026-07-26T09:41:22Z", "published_at": "2026-07-26T09:41:22Z", "created_at": "2026-07-26T09:41:22Z" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "summary": "Delete social post", "operationId": "deleteSocialPost", "tags": [ "Social" ], "parameters": [ { "$ref": "#/components/parameters/PostIdParam" } ], "responses": { "204": { "description": "Post deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/content/rewrite": { "post": { "summary": "Rewrite content", "operationId": "rewriteContent", "tags": [ "Content" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentRewriteRequest" } } } }, "responses": { "202": { "description": "Rewrite accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentRewriteResponse" }, "example": { "success": true, "data": { "text": "example-text" }, "usage": { "units": 1, "cost": "0.0150", "balance_remaining": "99.9850" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientBalance" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/seo/keyword-research": { "post": { "summary": "Keyword research", "description": "Keyword suggestions for a seed keyword with real monthly search volume, CPC and competition.", "operationId": "seoKeywordResearch", "tags": [ "SEO" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "keyword" ], "properties": { "keyword": { "type": "string", "description": "Seed keyword to expand." }, "location": { "type": "string", "default": "United States", "description": "Market location name." }, "language": { "type": "string", "default": "en", "description": "Language code." }, "limit": { "type": "integer", "minimum": 5, "maximum": 50, "default": 20, "description": "Max keywords to return." } } } } } }, "responses": { "200": { "description": "Keyword suggestions with volume, CPC and competition", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "keywords": { "type": "array", "items": { "type": "object", "properties": { "keyword": { "type": "string" }, "volume": { "type": "integer" }, "cpc": { "type": "number" }, "competition": { "type": "number" } } } }, "seed": { "type": "string" }, "location": { "type": "string" }, "total_found": { "type": "integer" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "keywords": [ { "keyword": "seo software", "volume": 18100, "cpc": 12.4, "competition": 0.78 }, { "keyword": "best seo tools", "volume": 8100, "cpc": 9.2, "competition": 0.65 } ], "seed": "seo tools", "location": "United States", "total_found": 2 }, "meta": { "request_id": "req_1a2b3c4d", "timestamp": "2026-07-01T12:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientBalance" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/seo/serp": { "post": { "summary": "Live SERP lookup", "description": "Live Google organic SERP for a keyword: ranked results, SERP features and People Also Ask.", "operationId": "seoSerp", "tags": [ "SEO" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "keyword" ], "properties": { "keyword": { "type": "string", "description": "Keyword to look up." }, "location": { "type": "string", "default": "United States", "description": "Market location name." }, "language": { "type": "string", "default": "en", "description": "Language code." }, "device": { "type": "string", "enum": [ "desktop", "mobile" ], "default": "desktop", "description": "Device." }, "depth": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "Number of results to fetch." } } } } } }, "responses": { "200": { "description": "Organic SERP results plus SERP features", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "integer" }, "title": { "type": "string" }, "url": { "type": "string" }, "description": { "type": "string" }, "domain": { "type": "string" } } } }, "keyword": { "type": "string" }, "location": { "type": "string" }, "serp_features": { "type": "array", "items": { "type": "string" } }, "people_also_ask": { "type": "array", "items": { "type": "string" } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "results": [ { "position": 1, "title": "Best SEO Tools (2026)", "url": "https://example.com/seo-tools", "description": "Compare the top SEO tools for 2026.", "domain": "example.com" } ], "keyword": "seo tools", "location": "United States", "serp_features": [ "featured_snippet", "people_also_ask" ], "people_also_ask": [ "What is the best SEO tool?", "Are SEO tools worth it?" ] }, "meta": { "request_id": "req_1a2b3c4d", "timestamp": "2026-07-01T12:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientBalance" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/seo/keyword-difficulty": { "post": { "summary": "Keyword difficulty", "description": "Bulk keyword difficulty scores (0-100) for a list of keywords.", "operationId": "seoKeywordDifficulty", "tags": [ "SEO" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "keywords" ], "properties": { "keywords": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Keywords to score." }, "location": { "type": "string", "default": "United States", "description": "Market location name." }, "language": { "type": "string", "default": "en", "description": "Language code." } } } } } }, "responses": { "200": { "description": "Difficulty score per keyword", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "difficulty": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Map of keyword -> difficulty score (0-100)." } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "difficulty": { "seo tools": 67, "keyword research": 54 } }, "meta": { "request_id": "req_1a2b3c4d", "timestamp": "2026-07-01T12:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientBalance" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/seo/ranked-keywords": { "post": { "summary": "Ranked keywords (rank tracking)", "description": "Every keyword a domain ranks for, with position, search volume and estimated traffic.", "operationId": "seoRankedKeywords", "tags": [ "SEO" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "target" ], "properties": { "target": { "type": "string", "description": "Domain to inspect, e.g. example.com." }, "location": { "type": "string", "default": "United States", "description": "Market location name." }, "language": { "type": "string", "default": "en", "description": "Language code." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Max keywords to return." } } } } } }, "responses": { "200": { "description": "Ranked keywords with position, volume and ETV", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "target": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "object", "properties": { "keyword": { "type": "string" }, "position": { "type": "integer" }, "url": { "type": "string" }, "type": { "type": "string" }, "search_volume": { "type": "integer" }, "cpc": { "type": "number" }, "etv": { "type": "number" } } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "target": "example.com", "keywords": [ { "keyword": "seo tools", "position": 3, "url": "https://example.com/seo-tools", "type": "organic", "search_volume": 18100, "cpc": 12.4, "etv": 2450.5 } ] }, "meta": { "request_id": "req_1a2b3c4d", "timestamp": "2026-07-01T12:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientBalance" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/seo/domain-overview": { "post": { "summary": "Domain rank overview", "description": "Organic rank overview for a domain: estimated keyword count, traffic value and position buckets.", "operationId": "seoDomainOverview", "tags": [ "SEO" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "target" ], "properties": { "target": { "type": "string", "description": "Domain to inspect, e.g. example.com." }, "location": { "type": "string", "default": "United States", "description": "Market location name." }, "language": { "type": "string", "default": "en", "description": "Language code." } } } } } }, "responses": { "200": { "description": "Organic overview metrics", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "target": { "type": "string" }, "overview": { "type": "object", "properties": { "organic_keywords": { "type": "integer" }, "organic_etv": { "type": "number" }, "pos_1": { "type": "integer" }, "pos_2_3": { "type": "integer" }, "pos_4_10": { "type": "integer" }, "pos_11_20": { "type": "integer" }, "is_new": { "type": "integer" }, "is_up": { "type": "integer" }, "is_down": { "type": "integer" } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "target": "example.com", "overview": { "organic_keywords": 12500, "organic_etv": 48230.7, "pos_1": 320, "pos_2_3": 540, "pos_4_10": 2100, "pos_11_20": 3800, "is_new": 45, "is_up": 210, "is_down": 130 } }, "meta": { "request_id": "req_1a2b3c4d", "timestamp": "2026-07-01T12:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientBalance" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/seo/competitors": { "post": { "summary": "Organic competitors", "description": "Domains overlapping a target on shared keywords, with common-keyword counts and traffic.", "operationId": "seoCompetitors", "tags": [ "SEO" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "target" ], "properties": { "target": { "type": "string", "description": "Domain to inspect, e.g. example.com." }, "location": { "type": "string", "default": "United States", "description": "Market location name." }, "language": { "type": "string", "default": "en", "description": "Language code." }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10, "description": "Max competitors to return." } } } } } }, "responses": { "200": { "description": "Competitor domains with overlap metrics", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "target": { "type": "string" }, "competitors": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "common_keywords": { "type": "integer" }, "organic_keywords": { "type": "integer" }, "organic_etv": { "type": "number" } } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "target": "example.com", "competitors": [ { "domain": "rival.com", "common_keywords": 1840, "organic_keywords": 22500, "organic_etv": 75200 } ] }, "meta": { "request_id": "req_1a2b3c4d", "timestamp": "2026-07-01T12:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientBalance" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/seo/backlinks-summary": { "post": { "summary": "Backlink profile summary", "description": "Backlink profile summary for a domain: authority rank, totals, referring domains, broken links and link types.", "operationId": "seoBacklinksSummary", "tags": [ "SEO" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "target" ], "properties": { "target": { "type": "string", "description": "Domain or URL to inspect." } } } } } }, "responses": { "200": { "description": "Backlink profile summary", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "target": { "type": "string" }, "summary": { "type": "object", "properties": { "rank": { "type": "integer" }, "backlinks": { "type": "integer" }, "referring_domains": { "type": "integer" }, "referring_main_domains": { "type": "integer" }, "broken_backlinks": { "type": "integer" }, "referring_links_types": { "type": "object" }, "referring_links_attributes": { "type": "object" } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "target": "example.com", "summary": { "rank": 412, "backlinks": 185400, "referring_domains": 3120, "referring_main_domains": 2850, "broken_backlinks": 240, "referring_links_types": { "anchor": 150000, "image": 35400 }, "referring_links_attributes": { "nofollow": 42000, "dofollow": 143400 } } }, "meta": { "request_id": "req_1a2b3c4d", "timestamp": "2026-07-01T12:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientBalance" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/seo/audit": { "post": { "summary": "On-page SEO audit", "description": "Instant on-page SEO audit for a single URL: on-page score and flagged checks.", "operationId": "seoAudit", "tags": [ "SEO" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Full page URL to audit." }, "max_pages": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10, "description": "Max pages to crawl." } } } } } }, "responses": { "200": { "description": "On-page audit result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "url": { "type": "string" }, "audit": { "type": "object", "properties": { "crawl_progress": { "type": "string" }, "pages_crawled": { "type": "integer" }, "pages_with_errors": { "type": "integer" }, "onpage_score": { "type": "number" }, "checks": { "type": "object" } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "url": "https://example.com/page", "audit": { "crawl_progress": "finished", "pages_crawled": 1, "pages_with_errors": 0, "onpage_score": 92.5, "checks": { "no_title": false, "no_description": false, "low_content_rate": false } } }, "meta": { "request_id": "req_1a2b3c4d", "timestamp": "2026-07-01T12:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientBalance" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/seo/backlink-prospects": { "post": { "summary": "Backlink prospects (link gap)", "description": "Find link-building prospects: referring domains that link to competitors of the target but not to the target itself.", "operationId": "seoBacklinkProspects", "tags": [ "SEO" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "target" ], "properties": { "target": { "type": "string", "description": "Your domain, e.g. example.com." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "Max prospects to return." } } } } } }, "responses": { "200": { "description": "Backlink prospects (link gap)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "target": { "type": "string" }, "competitors": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "rank": { "type": "integer" }, "intersections": { "type": "integer" } } } }, "prospects": { "type": "array", "items": { "type": "object", "properties": { "referring_domain": { "type": "string" }, "rank": { "type": "integer" }, "links_to_competitors": { "type": "integer" }, "example_source_url": { "type": "string" } } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "target": "example.com", "competitors": [ { "domain": "rival.com", "rank": 412, "intersections": 340 } ], "prospects": [ { "referring_domain": "authority-blog.com", "rank": 520, "links_to_competitors": 3, "example_source_url": "https://authority-blog.com/best-tools" } ] }, "meta": { "request_id": "req_1a2b3c4d", "timestamp": "2026-07-01T12:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientBalance" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/seo/referring-domains": { "post": { "summary": "Referring domains", "description": "List the top referring domains for a domain by authority, with backlink counts, first-seen date and dofollow counts.", "operationId": "seoReferringDomains", "tags": [ "SEO" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "target" ], "properties": { "target": { "type": "string", "description": "Domain or URL to inspect." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Max referring domains." } } } } } }, "responses": { "200": { "description": "Referring domains", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "target": { "type": "string" }, "domains": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "rank": { "type": "integer" }, "backlinks": { "type": "integer" }, "first_seen": { "type": "string" }, "dofollow": { "type": "integer" } } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "target": "example.com", "domains": [ { "domain": "techblog.com", "rank": 480, "backlinks": 1200, "first_seen": "2024-03-12", "dofollow": 1100 } ] }, "meta": { "request_id": "req_1a2b3c4d", "timestamp": "2026-07-01T12:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientBalance" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/seo/backlink-anchors": { "post": { "summary": "Backlink anchors", "description": "List the top backlink anchor texts for a domain, with backlink and referring-domain counts.", "operationId": "seoBacklinkAnchors", "tags": [ "SEO" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "target" ], "properties": { "target": { "type": "string", "description": "Domain or URL to inspect." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Max anchors." } } } } } }, "responses": { "200": { "description": "Backlink anchors", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "target": { "type": "string" }, "anchors": { "type": "array", "items": { "type": "object", "properties": { "anchor": { "type": "string" }, "backlinks": { "type": "integer" }, "referring_domains": { "type": "integer" } } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "target": "example.com", "anchors": [ { "anchor": "seo tools", "backlinks": 5400, "referring_domains": 320 } ] }, "meta": { "request_id": "req_1a2b3c4d", "timestamp": "2026-07-01T12:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientBalance" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/seo/spam-score": { "post": { "summary": "Backlink spam score", "description": "Get the backlink spam/toxicity score (0-100) for one or more domains.", "operationId": "seoSpamScore", "tags": [ "SEO" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "targets" ], "properties": { "targets": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Domains to score." } } } } } }, "responses": { "200": { "description": "Backlink spam score", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "spam": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Map of domain -> spam score (0-100)." } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "spam": { "example.com": 12, "spammy-site.net": 78 } }, "meta": { "request_id": "req_1a2b3c4d", "timestamp": "2026-07-01T12:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientBalance" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/seo/rank-history": { "post": { "summary": "Historical rank overview", "description": "Historical organic rank/traffic trend by month. Premium lookup. Async: returns 202 + job_uid - poll GET /jobs/{job_uid} for the result.\n\nHistorical organic keyword count and traffic (ETV) trend by month. Premium lookup (priced ~10x a normal SEO call).", "operationId": "seoRankHistory", "tags": [ "SEO" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "target" ], "properties": { "target": { "type": "string", "description": "Domain to inspect, e.g. example.com." }, "location": { "type": "string", "default": "United States", "description": "Market location name." }, "language": { "type": "string", "default": "en", "description": "Language code." } } } } } }, "responses": { "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientBalance" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "202": { "description": "Accepted - job queued. Poll GET /jobs/{job_uid}; on completion result_data contains the same payload the old 200 body carried.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobCreatedResponse" }, "example": { "success": true, "data": { "job_id": "ext_7f2c91" }, "usage": { "units": 1, "cost": "0.0150", "balance_remaining": "99.9850" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } } }, "/seo/site-audit": { "post": { "summary": "Deep site audit", "description": "Deep crawl-based technical site audit. Async: returns 202 + job_uid - poll GET /jobs/{job_uid}; result_data carries the audit (typically 30-90s).\n\nCrawl-based technical SEO audit: overall on-page score, crawl issues, and the worst-scoring pages with their flagged checks. Slower (~10-15s).", "operationId": "seoSiteAudit", "tags": [ "SEO" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Site URL to crawl." }, "max_pages": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Max pages to crawl." } } } } } }, "responses": { "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientBalance" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "202": { "description": "Accepted - job queued. Poll GET /jobs/{job_uid}; on completion result_data contains the same payload the old 200 body carried.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobCreatedResponse" }, "example": { "success": true, "data": { "job_id": "ext_7f2c91" }, "usage": { "units": 1, "cost": "0.0150", "balance_remaining": "99.9850" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } } }, "/seo/brand-lookup": { "post": { "summary": "AI Visibility: brand lookup", "description": "AI Visibility brand/domain citation lookup. Async: returns 202 + job_uid - poll GET /jobs/{job_uid} for the result (may take ~1 minute).\n\nHow often ChatGPT and Google AI Overview cite a brand, domain or keyword: total mentions, AI search volume, estimated impressions (split by platform), the citing prompts, cited source domains, related pages and a 12-month trend.", "operationId": "seoBrandLookup", "tags": [ "SEO" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "value" ], "properties": { "value": { "type": "string", "description": "Brand name, domain, or keyword to look up." }, "type": { "type": "string", "enum": [ "keyword", "domain" ], "default": "keyword", "description": "Whether `value` is a brand/keyword or a domain." }, "location": { "type": "string", "default": "United States", "description": "Location name." } } }, "example": { "value": "nike.com", "type": "domain", "location": "United States" } } } }, "responses": { "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientBalance" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "202": { "description": "Accepted - job queued. Poll GET /jobs/{job_uid}; on completion result_data contains the same payload the old 200 body carried.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobCreatedResponse" }, "example": { "success": true, "data": { "job_id": "ext_7f2c91" }, "usage": { "units": 1, "cost": "0.0150", "balance_remaining": "99.9850" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } } }, "/seo/prompt-explorer": { "post": { "summary": "AI Visibility: prompt explorer", "description": "Run a prompt across ChatGPT/Claude/Gemini/Perplexity. Async: returns 202 + job_uid - poll GET /jobs/{job_uid} for the result (1-2 minutes).\n\nRun one prompt across ChatGPT, Claude, Gemini and Perplexity side-by-side. Returns each model's answer text, citations and fan-out queries; pass `brand` to get a mentions_brand flag per answer.", "operationId": "seoPromptExplorer", "tags": [ "SEO" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "prompt" ], "properties": { "prompt": { "type": "string", "description": "The prompt to run across the AI models." }, "models": { "type": "array", "items": { "type": "string", "enum": [ "chat_gpt", "claude", "gemini", "perplexity" ] }, "description": "Which models to query (default all four)." }, "web_search": { "type": "boolean", "default": true, "description": "Allow the models to use web search." }, "country": { "type": "string", "description": "Two-letter ISO country code to geolocate web search (e.g. 'US')." }, "brand": { "type": "string", "description": "Optional brand to flag mentions of in each answer." } } }, "example": { "prompt": "What is the best CRM for a small agency?", "brand": "SmartlyQ" } } } }, "responses": { "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientBalance" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "202": { "description": "Accepted - job queued. Poll GET /jobs/{job_uid}; on completion result_data contains the same payload the old 200 body carried.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobCreatedResponse" }, "example": { "success": true, "data": { "job_id": "ext_7f2c91" }, "usage": { "units": 1, "cost": "0.0150", "balance_remaining": "99.9850" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } } }, "/seo/ai-audit": { "post": { "summary": "AI Visibility Audit (async)", "description": "Zero-input GEO audit: give a website URL and the audit auto-generates realistic customer queries in the market's language (or accepts your own), runs every query across ChatGPT, Claude, Gemini and Perplexity, and scores unaided brand presence. The result contains an AI Presence Score (0-100 = share of query x model checks whose answer mentions the brand or domain), per-query mention results, and the competitors AI recommends instead. Long-running (typically 5-15 minutes): returns 202 with a job_id - poll GET /jobs/{job_id}. Billed per (query x model) check.", "operationId": "seoAiAudit", "tags": [ "SEO" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "The business website URL to audit." }, "brand": { "type": "string", "description": "Brand name to detect in answers (auto-detected from the site when omitted)." }, "location": { "type": "string", "default": "United States", "description": "Market/location name (queries are generated in its language)." }, "language": { "type": "string", "description": "ISO language code override for generated queries." }, "queries": { "type": "array", "maxItems": 12, "items": { "type": "string" }, "description": "Custom customer queries (max 12). Omit to auto-generate 8 from the website." }, "models": { "type": "array", "items": { "type": "string", "enum": [ "chat_gpt", "claude", "gemini", "perplexity" ] }, "description": "Which models to check (default all four)." }, "name": { "type": "string", "description": "Optional audit name." } } }, "example": { "url": "acme-plumbing.com", "location": "United Kingdom" } } } }, "responses": { "202": { "description": "Accepted; poll job for the audit report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobCreatedResponse" }, "example": { "success": true, "data": { "job_id": "ext_7f2c91" }, "usage": { "units": 1, "cost": "0.0150", "balance_remaining": "99.9850" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientBalance" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/audio/text-to-speech": { "post": { "summary": "Text to speech", "operationId": "textToSpeech", "tags": [ "Audio" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextToSpeechRequest" } } } }, "responses": { "202": { "description": "TTS generation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobCreatedResponse" }, "example": { "success": true, "data": { "job_id": "ext_7f2c91" }, "usage": { "units": 1, "cost": "0.0150", "balance_remaining": "99.9850" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientBalance" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/audio/speech-to-text": { "post": { "summary": "Speech to text", "operationId": "speechToText", "tags": [ "Audio" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpeechToTextRequest" } } } }, "responses": { "202": { "description": "Transcription accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobCreatedResponse" }, "example": { "success": true, "data": { "job_id": "ext_7f2c91" }, "usage": { "units": 1, "cost": "0.0150", "balance_remaining": "99.9850" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientBalance" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/audio/{audio_id}": { "get": { "summary": "Get audio", "operationId": "getAudio", "tags": [ "Audio" ], "parameters": [ { "$ref": "#/components/parameters/AudioIdParam" } ], "responses": { "200": { "description": "Audio resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudioSingleResponse" }, "example": { "success": true, "data": { "id": 128, "url": "https://example.com/launch", "duration_seconds": 1.5, "created_at": "2026-07-26T09:41:22Z" }, "usage": { "units": 1, "cost": "0.0150", "balance_remaining": "99.9850" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/urls/shorten": { "post": { "summary": "Shorten URL", "operationId": "shortenUrl", "tags": [ "URLs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UrlShortenRequest" } } } }, "responses": { "201": { "description": "Short URL created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UrlSingleResponse" }, "example": { "success": true, "data": { "id": 128, "short_url": "https://cdn.example.com/launch.jpg", "long_url": "https://cdn.example.com/launch.jpg", "code": "example-code", "title": "Product launch announcement", "expires_at": "2026-07-26T09:41:22Z", "created_at": "2026-07-26T09:41:22Z" }, "usage": { "units": 1, "cost": "0.0150", "balance_remaining": "99.9850" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientBalance" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/urls": { "get": { "summary": "List short URLs", "operationId": "listUrls", "tags": [ "URLs" ], "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PerPageParam" }, { "name": "search", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of URLs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UrlListResponse" }, "example": { "success": true, "data": [ { "id": 128, "short_url": "https://cdn.example.com/launch.jpg", "long_url": "https://cdn.example.com/launch.jpg", "code": "example-code", "title": "Product launch announcement", "expires_at": "2026-07-26T09:41:22Z", "created_at": "2026-07-26T09:41:22Z" } ], "pagination": { "page": 1, "per_page": 1, "total": 42, "pages": 1 }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/urls/{url_id}": { "get": { "summary": "Get short URL", "operationId": "getUrl", "tags": [ "URLs" ], "parameters": [ { "$ref": "#/components/parameters/UrlIdParam" } ], "responses": { "200": { "description": "Short URL details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UrlSingleResponse" }, "example": { "success": true, "data": { "id": 128, "short_url": "https://cdn.example.com/launch.jpg", "long_url": "https://cdn.example.com/launch.jpg", "code": "example-code", "title": "Product launch announcement", "expires_at": "2026-07-26T09:41:22Z", "created_at": "2026-07-26T09:41:22Z" }, "usage": { "units": 1, "cost": "0.0150", "balance_remaining": "99.9850" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "summary": "Delete short URL", "operationId": "deleteUrl", "tags": [ "URLs" ], "parameters": [ { "$ref": "#/components/parameters/UrlIdParam" } ], "responses": { "204": { "description": "URL deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/urls/{url_id}/stats": { "get": { "summary": "Get short URL stats", "operationId": "getUrlStats", "tags": [ "URLs" ], "parameters": [ { "$ref": "#/components/parameters/UrlIdParam" } ], "responses": { "200": { "description": "Click statistics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UrlStatsResponse" }, "example": { "success": true, "data": { "clicks": 1, "last_click_at": "2026-07-26T09:41:22Z" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/captain/messages": { "post": { "summary": "Send AI Captain message", "operationId": "sendCaptainMessage", "tags": [ "AI Captain" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptainMessageRequest" } } } }, "responses": { "202": { "description": "Message accepted; AI Captain reply included", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptainMessageResponse" }, "example": { "success": true, "data": { "message": { "id": "example-id", "role": "user", "content": "Big news - our summer collection is live! ☀️", "created_at": "2026-07-26T09:41:22Z" }, "conversation_id": "ext_7f2c91" }, "usage": { "units": 1, "cost": "0.0150", "balance_remaining": "99.9850" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientBalance" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/captain/conversations": { "get": { "summary": "List AI Captain conversations", "operationId": "listCaptainConversations", "tags": [ "AI Captain" ], "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PerPageParam" } ], "responses": { "200": { "description": "Paginated list of conversations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationListResponse" }, "example": { "success": true, "data": [ { "id": "example-id", "messages": [ { "id": "example-id", "role": "user", "content": "Big news - our summer collection is live! ☀️", "created_at": "2026-07-26T09:41:22Z" } ], "created_at": "2026-07-26T09:41:22Z" } ], "pagination": { "page": 1, "per_page": 1, "total": 42, "pages": 1 }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/captain/conversations/{conversation_id}": { "get": { "summary": "Get AI Captain conversation", "operationId": "getCaptainConversation", "tags": [ "AI Captain" ], "parameters": [ { "$ref": "#/components/parameters/ConversationIdParam" } ], "responses": { "200": { "description": "Single conversation with messages", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationSingleResponse" }, "example": { "success": true, "data": { "id": "example-id", "messages": [ { "id": "example-id", "role": "user", "content": "Big news - our summer collection is live! ☀️", "created_at": "2026-07-26T09:41:22Z" } ], "created_at": "2026-07-26T09:41:22Z" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/chatbots": { "post": { "summary": "Create chatbot", "operationId": "createChatbot", "tags": [ "Chatbot" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "description": "Chatbot display name" }, "config": { "type": "object", "description": "Chatbot configuration (model, temperature, etc.)" } } } } } }, "responses": { "201": { "description": "Chatbot created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "success": true, "data": "example-data", "usage": { "units": 1, "cost": "0.0150", "balance_remaining": "99.9850" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "summary": "List chatbots", "operationId": "listChatbots", "tags": [ "Chatbot" ], "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PerPageParam" }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "search", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of chatbots", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedList" }, "example": { "success": true, "data": [ "example-data" ], "pagination": { "page": 1, "per_page": 1, "total": 42, "pages": 1 }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/chatbots/{id}": { "get": { "summary": "Get chatbot", "operationId": "getChatbot", "tags": [ "Chatbot" ], "parameters": [ { "$ref": "#/components/parameters/ChatbotIdParam" } ], "responses": { "200": { "description": "Chatbot details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "success": true, "data": "example-data", "usage": { "units": 1, "cost": "0.0150", "balance_remaining": "99.9850" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "summary": "Update chatbot", "operationId": "updateChatbot", "tags": [ "Chatbot" ], "parameters": [ { "$ref": "#/components/parameters/ChatbotIdParam" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "config": { "type": "object" } } } } } }, "responses": { "200": { "description": "Updated chatbot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "success": true, "data": "example-data", "usage": { "units": 1, "cost": "0.0150", "balance_remaining": "99.9850" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "summary": "Delete chatbot", "operationId": "deleteChatbot", "tags": [ "Chatbot" ], "parameters": [ { "$ref": "#/components/parameters/ChatbotIdParam" } ], "responses": { "204": { "description": "Chatbot deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/chatbots/{id}/train": { "post": { "summary": "Start chatbot training", "description": "Triggers training using the chatbot's existing training data (training_text, training_url, and FAQs). No request body required. Poll GET /chatbots/{id}/train-status for completion.", "operationId": "trainChatbot", "tags": [ "Chatbot" ], "parameters": [ { "$ref": "#/components/parameters/ChatbotIdParam" } ], "responses": { "202": { "description": "Training accepted; poll train-status for completion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "success": true, "data": "example-data", "usage": { "units": 1, "cost": "0.0150", "balance_remaining": "99.9850" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/chatbots/{id}/train-status": { "get": { "summary": "Get chatbot training status", "operationId": "getChatbotTrainStatus", "tags": [ "Chatbot" ], "parameters": [ { "$ref": "#/components/parameters/ChatbotIdParam" } ], "responses": { "200": { "description": "Training status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "success": true, "data": "example-data", "usage": { "units": 1, "cost": "0.0150", "balance_remaining": "99.9850" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/chatbots/{id}/messages": { "post": { "summary": "Send chatbot message", "operationId": "sendChatbotMessage", "tags": [ "Chatbot" ], "parameters": [ { "$ref": "#/components/parameters/ChatbotIdParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "conversation_id": { "type": "string", "description": "Continue an existing conversation" } } } } } }, "responses": { "200": { "description": "Chatbot reply", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "success": true, "data": "example-data", "usage": { "units": 1, "cost": "0.0150", "balance_remaining": "99.9850" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientBalance" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/chatbots/{id}/conversations": { "get": { "summary": "List chatbot conversations", "operationId": "listChatbotConversations", "tags": [ "Chatbot" ], "parameters": [ { "$ref": "#/components/parameters/ChatbotIdParam" }, { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PerPageParam" } ], "responses": { "200": { "description": "Paginated list of conversations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedList" }, "example": { "success": true, "data": [ "example-data" ], "pagination": { "page": 1, "per_page": 1, "total": 42, "pages": 1 }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/chatbots/{id}/conversations/{conv_id}/messages": { "get": { "summary": "Get conversation messages", "operationId": "getChatbotConversationMessages", "tags": [ "Chatbot" ], "parameters": [ { "$ref": "#/components/parameters/ChatbotIdParam" }, { "$ref": "#/components/parameters/ConvIdParam" } ], "responses": { "200": { "description": "List of messages in the conversation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedList" }, "example": { "success": true, "data": [ "example-data" ], "pagination": { "page": 1, "per_page": 1, "total": 42, "pages": 1 }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/media": { "get": { "summary": "List media", "operationId": "listMedia", "tags": [ "Media" ], "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PerPageParam" }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "content_type", "in": "query", "schema": { "type": "string" }, "description": "Filter by MIME type" }, { "name": "type", "in": "query", "schema": { "type": "string" }, "description": "Filter by media type" } ], "responses": { "200": { "description": "Paginated list of media", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaListResponse" }, "example": { "success": true, "data": [ { "id": 128, "url": "https://example.com/launch", "filename": "example-filename", "size_bytes": 482113, "mime_type": "example-mime-type", "created_at": "2026-07-26T09:41:22Z" } ], "pagination": { "page": 1, "per_page": 1, "total": 42, "pages": 1 }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/media/{media_id}": { "get": { "summary": "Get media", "operationId": "getMedia", "tags": [ "Media" ], "parameters": [ { "$ref": "#/components/parameters/MediaIdParam" } ], "responses": { "200": { "description": "Media record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaSingleResponse" }, "example": { "success": true, "data": { "id": 128, "url": "https://example.com/launch", "filename": "example-filename", "size_bytes": 482113, "mime_type": "example-mime-type", "created_at": "2026-07-26T09:41:22Z" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "summary": "Delete media", "operationId": "deleteMedia", "tags": [ "Media" ], "parameters": [ { "$ref": "#/components/parameters/MediaIdParam" } ], "responses": { "204": { "description": "Media deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/media/upload-url": { "post": { "summary": "Get presigned upload URL", "operationId": "getMediaUploadUrl", "tags": [ "Media" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaUploadUrlRequest" } } } }, "responses": { "200": { "description": "Presigned URL for upload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaUploadUrlResponse" }, "example": { "success": true, "data": { "upload_url": "https://cdn.example.com/launch.jpg", "media_id": 128 }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/analytics/overview": { "get": { "summary": "Get analytics overview", "operationId": "getAnalyticsOverview", "tags": [ "Analytics" ], "parameters": [ { "name": "period", "in": "query", "description": "Time period for analytics", "schema": { "type": "string", "enum": [ "today", "7d", "30d", "90d" ], "default": "30d" } }, { "$ref": "#/components/parameters/ProfileHeader" } ], "responses": { "200": { "description": "Analytics overview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "success": true, "data": "example-data", "usage": { "units": 1, "cost": "0.0150", "balance_remaining": "99.9850" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/analytics/posts": { "get": { "summary": "Get post analytics", "operationId": "getAnalyticsPosts", "tags": [ "Analytics" ], "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PerPageParam" }, { "name": "platform", "in": "query", "schema": { "type": "string" }, "description": "Filter by social platform" }, { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Start date (YYYY-MM-DD)" }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "End date (YYYY-MM-DD)" } ], "responses": { "200": { "description": "Post analytics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "success": true, "data": "example-data", "usage": { "units": 1, "cost": "0.0150", "balance_remaining": "99.9850" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/analytics/accounts/{account_id}": { "get": { "summary": "Get account analytics", "operationId": "getAnalyticsAccount", "tags": [ "Analytics" ], "parameters": [ { "$ref": "#/components/parameters/AccountIdParam" }, { "name": "period", "in": "query", "description": "Time period for analytics", "schema": { "type": "string", "enum": [ "today", "7d", "30d", "90d" ], "default": "30d" } } ], "responses": { "200": { "description": "Account analytics data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" }, "example": { "success": true, "data": "example-data", "usage": { "units": 1, "cost": "0.0150", "balance_remaining": "99.9850" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/jobs": { "get": { "summary": "List jobs", "operationId": "listJobs", "tags": [ "Jobs" ], "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PerPageParam" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "cancelled" ] } }, { "name": "type", "in": "query", "schema": { "type": "string" }, "description": "Filter by job type" } ], "responses": { "200": { "description": "Paginated list of jobs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobListResponse" }, "example": { "success": true, "data": [ { "id": "example-id", "type": "example-type", "status": "pending", "result": {}, "error": {}, "created_at": "2026-07-26T09:41:22Z", "updated_at": "2026-07-26T09:41:22Z" } ], "pagination": { "page": 1, "per_page": 1, "total": 42, "pages": 1 }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/jobs/{job_id}": { "get": { "summary": "Get job", "operationId": "getJob", "tags": [ "Jobs" ], "parameters": [ { "$ref": "#/components/parameters/JobIdParam" } ], "responses": { "200": { "description": "Job status and result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobSingleResponse" }, "example": { "success": true, "data": { "id": "example-id", "type": "example-type", "status": "pending", "result": {}, "error": {}, "created_at": "2026-07-26T09:41:22Z", "updated_at": "2026-07-26T09:41:22Z" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/jobs/{job_id}/cancel": { "post": { "summary": "Cancel job", "operationId": "cancelJob", "tags": [ "Jobs" ], "description": "Cancels a queued or processing job. The request body may be empty, but `Content-Type: application/json` **must** still be set — omitting it returns a 400 error.", "parameters": [ { "$ref": "#/components/parameters/JobIdParam" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Job cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobSingleResponse" }, "example": { "success": true, "data": { "id": "example-id", "type": "example-type", "status": "pending", "result": {}, "error": {}, "created_at": "2026-07-26T09:41:22Z", "updated_at": "2026-07-26T09:41:22Z" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/me": { "get": { "summary": "Get current user profile", "operationId": "getMe", "tags": [ "Account" ], "responses": { "200": { "description": "Current user profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserProfileResponse" }, "example": { "success": true, "data": { "id": 128, "name": "Acme Corp", "email": "ada@example.com", "plan": "example-plan", "created_at": "2026-07-26T09:41:22Z" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/me/usage": { "get": { "summary": "Get usage summary", "operationId": "getMeUsage", "tags": [ "Account" ], "parameters": [ { "name": "period", "in": "query", "description": "Time period for usage report", "schema": { "type": "string", "enum": [ "today", "7d", "30d", "90d", "all" ], "default": "30d" } } ], "responses": { "200": { "description": "Usage summary for the period", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageSummaryResponse" }, "example": { "success": true, "data": { "total_requests": 1, "total_credits_used": 1.5 }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/me/balance": { "get": { "summary": "Get wallet balance", "operationId": "getMeBalance", "tags": [ "Account" ], "responses": { "200": { "description": "Current wallet balance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceResponse" }, "example": { "success": true, "data": { "balance": "100.0000", "purchased_balance": "50.0000", "monthly_balance": "50.0000", "monthly_reset_at": "2026-07-26T09:41:22Z", "currency": "USD" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/social/accounts/{account_id}": { "patch": { "summary": "Rename account", "operationId": "updateSocialAccount", "tags": [ "Social" ], "description": "Rename a connected social account (display name inside SmartlyQ - does not change anything on the platform). Requires scope `social:write`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "account_name" ], "properties": { "account_name": { "type": "string", "maxLength": 255 } } } } } }, "responses": { "200": { "description": "Renamed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "platform": { "type": "string" }, "account_name": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "id": 128, "platform": "twitter", "account_name": "Acme Corp Main" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "summary": "Disconnect a social account", "operationId": "disconnectSocialAccount", "tags": [ "Social" ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Connected account id" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "null", "description": "No payload on success." }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": null, "meta": { "request_id": "req_abc123", "timestamp": "2026-03-01T16:00:00Z" } } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/social/accounts/{account_id}/health": { "get": { "summary": "Account health", "operationId": "getAccountHealth", "tags": [ "Social" ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Connected account id" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "platform": { "type": "string" }, "account_name": { "type": "string" }, "status": { "type": "string", "description": "connected | expired | error" }, "token_expired": { "type": "boolean" }, "validity_days": { "type": "integer", "description": "Days until the token expires." } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "id": 123, "platform": "facebook", "account_name": "My Business Page", "status": "connected", "token_expired": false, "validity_days": 45 }, "meta": { "request_id": "req_abc123", "timestamp": "2026-03-01T16:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/social/accounts/{account_id}/reconnect-url": { "get": { "summary": "Account reconnect URL", "operationId": "getAccountReconnectUrl", "tags": [ "Social" ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Connected account id" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "reconnect_url": { "type": "string", "format": "uri" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "reconnect_url": "https://app.smartlyq.com/connect/facebook?token=..." }, "meta": { "request_id": "req_abc123", "timestamp": "2026-03-01T16:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/social/accounts/{account_id}/pause": { "post": { "summary": "Pause posting to an account", "operationId": "pauseSocialAccount", "tags": [ "Social" ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Connected account id" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "paused": { "type": "boolean" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "id": 123, "paused": true }, "meta": { "request_id": "req_abc123", "timestamp": "2026-03-01T16:00:00Z" } } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/social/accounts/{account_id}/resume": { "post": { "summary": "Resume posting to an account", "operationId": "resumeSocialAccount", "tags": [ "Social" ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Connected account id" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "paused": { "type": "boolean" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "id": 123, "paused": false }, "meta": { "request_id": "req_abc123", "timestamp": "2026-03-01T16:00:00Z" } } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/social/posts/{post_id}/retry": { "post": { "summary": "Retry publishing a post", "operationId": "retrySocialPost", "tags": [ "Social" ], "parameters": [ { "name": "post_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Post id" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "platforms": { "type": "array", "items": { "type": "string" }, "description": "Platforms to retry, e.g. ['facebook']" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean" }, "retried": { "type": "array", "items": { "type": "string" }, "description": "Platforms that were retried." }, "final_status": { "type": "string", "description": "published | partial | failed" }, "platform_results": { "type": "array", "items": { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "string", "nullable": true } } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "success": true, "retried": [ "facebook", "instagram" ], "final_status": "published", "platform_results": [ { "success": true, "error": null }, { "success": true, "error": null } ] }, "meta": { "request_id": "req_abc123", "timestamp": "2026-03-01T16:00:00Z" } } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/social/comments": { "get": { "summary": "List comments", "operationId": "listComments", "tags": [ "Comments" ], "parameters": [ { "name": "platform", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" }, { "name": "social_account_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "" }, { "$ref": "#/components/parameters/ProfileHeader" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "post_id": { "type": "integer" }, "remote_post_id": { "type": "string" }, "content": { "type": "string" }, "permalink": { "type": "string", "nullable": true }, "platform": { "type": "string" }, "social_account_id": { "type": "integer" }, "account_name": { "type": "string" }, "comment_count": { "type": "integer" }, "comments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "content": { "type": "string" }, "author_name": { "type": "string" }, "author_avatar": { "type": "string", "nullable": true }, "like_count": { "type": "integer" }, "commented_at": { "type": "string" }, "is_own": { "type": "integer", "description": "1 if authored by your account." }, "remote_comment_id": { "type": "string" }, "platform": { "type": "string" }, "children": { "type": "array", "items": { "type": "object", "properties": {} }, "description": "Nested replies, same shape as a comment." } } } } } } } } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "posts": [ { "id": 456, "post_id": 456, "remote_post_id": "123_987", "content": "Our new launch!", "permalink": "https://facebook.com/123_987", "platform": "facebook", "social_account_id": 789, "account_name": "My Business Page", "comment_count": 2, "comments": [ { "id": 1, "content": "Love this!", "author_name": "Jane", "author_avatar": null, "like_count": 3, "commented_at": "2026-03-01 11:00:00", "is_own": 0, "remote_comment_id": "c_1", "platform": "facebook", "children": [] } ] } ] }, "pagination": { "page": 1, "per_page": 20, "total": 1 }, "meta": { "request_id": "req_abc123", "timestamp": "2026-03-01T16:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/social/comments/{comment_id}/reply": { "post": { "summary": "Reply to a comment", "operationId": "replyToComment", "tags": [ "Comments" ], "parameters": [ { "name": "comment_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Comment id" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "description": "Reply text" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean" }, "remote_id": { "type": "string", "description": "Platform-side id of the created reply." } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "success": true, "remote_id": "c_2" }, "meta": { "request_id": "req_abc123", "timestamp": "2026-03-01T16:00:00Z" } } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/social/comments/{comment_id}/hide": { "post": { "summary": "Hide or unhide a comment", "operationId": "hideComment", "tags": [ "Comments" ], "parameters": [ { "name": "comment_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Comment id" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean" }, "hidden": { "type": "boolean" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "success": true, "hidden": true }, "meta": { "request_id": "req_abc123", "timestamp": "2026-03-01T16:00:00Z" } } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/social/comments/{comment_id}/moderate": { "post": { "summary": "Approve or reject a comment", "operationId": "moderateComment", "description": "Full moderation status change, optionally banning the author. YouTube only - other platforms only support hide/unhide (POST .../hide) and delete (DELETE .../{comment_id}), which every platform honors. Requires social:write.", "tags": [ "Comments" ], "parameters": [ { "name": "comment_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Comment id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "approved", "rejected" ] }, "ban_author": { "type": "boolean", "description": "Reject the comment AND ban this author from commenting again. Only meaningful with status=rejected.", "default": false } } }, "example": { "status": "rejected", "ban_author": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean" }, "status": { "type": "string" }, "banned_author": { "type": "boolean" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "success": true, "status": "rejected", "banned_author": false }, "meta": { "request_id": "req_abc123", "timestamp": "2026-08-04T16:00:00Z" } } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/social/comments/{comment_id}/like": { "post": { "summary": "Like a comment", "operationId": "likeComment", "description": "Like a comment as the connected account. Facebook only - Instagram's Graph API has no comment-like edge. Requires social:write.", "tags": [ "Comments" ], "parameters": [ { "name": "comment_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Comment id" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean" }, "liked": { "type": "boolean" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "success": true, "liked": true }, "meta": { "request_id": "req_abc123", "timestamp": "2026-08-04T16:00:00Z" } } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "summary": "Unlike a comment", "operationId": "unlikeComment", "description": "Remove your like from a comment. Facebook only. Requires social:write.", "tags": [ "Comments" ], "parameters": [ { "name": "comment_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Comment id" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean" }, "liked": { "type": "boolean" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "success": true, "liked": false }, "meta": { "request_id": "req_abc123", "timestamp": "2026-08-04T16:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/social/comments/{comment_id}": { "delete": { "summary": "Delete a comment", "operationId": "deleteComment", "tags": [ "Comments" ], "parameters": [ { "name": "comment_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Comment id" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "null", "description": "No payload on success." }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": null, "meta": { "request_id": "req_abc123", "timestamp": "2026-03-01T16:00:00Z" } } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/social/conversations": { "get": { "summary": "List DM conversations", "operationId": "listConversations", "tags": [ "Direct Messages" ], "parameters": [ { "name": "platform", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" }, { "name": "social_account_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "" }, { "$ref": "#/components/parameters/ProfileHeader" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "conversations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "social_account_id": { "type": "integer" }, "platform": { "type": "string" }, "participant_name": { "type": "string" }, "participant_avatar": { "type": "string", "nullable": true }, "snippet": { "type": "string" }, "unread_count": { "type": "integer" }, "last_message_at": { "type": "string" }, "status": { "type": "string", "description": "open | closed" }, "meta_window_open": { "type": "boolean", "description": "Meta only: whether the 24h reply window is open." } } } } } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "conversations": [ { "id": 101, "social_account_id": 789, "platform": "facebook", "participant_name": "Alice", "participant_avatar": null, "snippet": "Hi, a question…", "unread_count": 2, "last_message_at": "2026-03-01 15:45:00", "status": "open", "meta_window_open": true } ] }, "pagination": { "page": 1, "per_page": 20, "total": 1 }, "meta": { "request_id": "req_abc123", "timestamp": "2026-03-01T16:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/social/conversations/{conversation_id}/messages": { "get": { "summary": "List messages in a conversation", "operationId": "listMessages", "tags": [ "Direct Messages" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Conversation id" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "conversation_id": { "type": "integer" }, "direction": { "type": "string", "description": "in | out" }, "content": { "type": "string", "nullable": true }, "media_url": { "type": "string", "nullable": true }, "media_type": { "type": "string", "nullable": true }, "remote_message_id": { "type": "string" }, "sender_name": { "type": "string" }, "status": { "type": "string" }, "sent_at": { "type": "string" } } } }, "meta_window": { "type": "object", "properties": { "open": { "type": "boolean" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true } } } } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "messages": [ { "id": 1001, "conversation_id": 101, "direction": "in", "content": "Hi!", "media_url": null, "media_type": null, "remote_message_id": "m_1", "sender_name": "Alice", "status": "sent", "sent_at": "2026-03-01 15:30:00" } ], "meta_window": { "open": true, "expires_at": "2026-03-02 15:30:00" } }, "pagination": { "page": 1, "per_page": 20, "total": 1 }, "meta": { "request_id": "req_abc123", "timestamp": "2026-03-01T16:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "summary": "Send a direct message", "operationId": "sendDirectMessage", "tags": [ "Direct Messages" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Conversation id" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "description": "Message text" }, "image_url": { "type": "string", "description": "Optional image URL" }, "media_type": { "type": "string", "enum": [ "image", "video", "audio", "file", "document" ], "default": "image", "description": "Type of the attached media." }, "buttons": { "type": "array", "maxItems": 3, "items": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 20 }, "url": { "type": "string", "format": "uri" } } }, "description": "Up to 3 link buttons under the text (Facebook button template; Instagram rejects buttons - use quick_replies).", "example": [ { "title": "View order", "url": "https://acme.shop/orders/42" } ] }, "quick_replies": { "type": "array", "maxItems": 13, "items": { "type": "string", "maxLength": 20 }, "description": "Tappable text chips (Facebook + Instagram).", "example": [ "Yes please", "No thanks" ] } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object", "properties": { "id": { "type": "integer" }, "conversation_id": { "type": "integer" }, "direction": { "type": "string", "description": "in | out" }, "content": { "type": "string", "nullable": true }, "media_url": { "type": "string", "nullable": true }, "media_type": { "type": "string", "nullable": true }, "remote_message_id": { "type": "string" }, "sender_name": { "type": "string" }, "status": { "type": "string" }, "sent_at": { "type": "string" } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "success": true, "message": { "id": 1003, "conversation_id": 101, "direction": "out", "content": "Thanks!", "media_url": null, "media_type": null, "remote_message_id": "m_3", "sender_name": "You", "status": "sent", "sent_at": "2026-03-01 16:00:00" } }, "meta": { "request_id": "req_abc123", "timestamp": "2026-03-01T16:00:00Z" } } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } }, "description": " Supports structured payloads: buttons (Facebook) and quick_replies (Facebook + Instagram)." } }, "/social/conversations/{conversation_id}/read": { "post": { "summary": "Mark a conversation read", "operationId": "markConversationRead", "tags": [ "Direct Messages" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Conversation id" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "read": { "type": "boolean" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "id": 101, "read": true }, "meta": { "request_id": "req_abc123", "timestamp": "2026-03-01T16:00:00Z" } } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/webhooks": { "get": { "summary": "List webhooks", "operationId": "listWebhooks", "tags": [ "Webhooks" ], "description": "List the workspace's webhook subscriptions and the available event names. Requires scope `webhooks:read`.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "webhooks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "description": "active | disabled" }, "last_triggered_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } } }, "events": { "type": "array", "items": { "type": "string" }, "description": "Catalog of subscribable event names." } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "webhooks": [ { "id": 1, "url": "https://example.com/hooks", "events": [ "post.published", "comment.received" ], "status": "active", "last_triggered_at": "2026-03-01 15:30:00", "created_at": "2026-02-10 10:00:00" } ], "events": [ "post.published", "post.failed", "post.partial", "account.connected", "account.disconnected", "account.token_expired", "comment.received", "message.received", "job.completed", "job.failed" ] }, "meta": { "request_id": "req_abc123", "timestamp": "2026-03-01T16:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "post": { "summary": "Create webhook", "operationId": "createWebhook", "tags": [ "Webhooks" ], "description": "Subscribe a public HTTPS URL to events. The signing `secret` is returned once at creation. Requires scope `webhooks:write`. Max 10 active webhooks per workspace. Events: post.published, post.failed, post.partial, account.connected, account.disconnected, account.token_expired, comment.received, message.received, job.completed, job.failed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Public HTTPS endpoint that receives signed POSTs." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "post.published", "post.partial", "post.failed", "account.connected", "account.disconnected", "account.token_expired", "comment.received", "message.received", "job.completed", "job.failed", "balance.low", "balance.depleted", "key.revoked", "wallet.recharge.succeeded", "wallet.recharge.failed", "account_billing.charged", "account_billing.failed", "contact.created", "contact.updated", "contact.tag_added", "contact.tag_removed", "deal.created", "deal.stage_changed", "deal.won", "deal.lost", "post.scheduled", "post.cancelled", "post.recycled", "post.external.created", "post.external.updated", "message.sent", "conversation.started", "reaction.received", "review.new", "review.updated", "message.delivered", "message.read", "message.failed" ] }, "description": "Events to subscribe to. Must be from the 25-event catalog (see the webhooks object in this spec and the Webhooks guide)." } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "secret": { "type": "string", "description": "Signing secret — returned ONLY here, at creation. Store it now." } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "id": 2, "url": "https://example.com/hooks", "events": [ "post.published" ], "status": "active", "secret": "whsec_a1b2c3d4e5f6" }, "meta": { "request_id": "req_abc123", "timestamp": "2026-03-01T16:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/webhooks/{id}": { "delete": { "summary": "Delete webhook", "operationId": "deleteWebhook", "tags": [ "Webhooks" ], "description": "Delete a webhook subscription. Requires scope `webhooks:write`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Webhook id." } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "null", "description": "No payload on success." }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": null, "meta": { "request_id": "req_abc123", "timestamp": "2026-03-01T16:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "summary": "Update webhook", "operationId": "updateWebhook", "tags": [ "Webhooks" ], "description": "Update a webhook's `url`, `events`, or `status`. Only supplied fields change. `url` is re-validated (public HTTPS, SSRF-guarded); `events` must all come from the 25-event catalog (unknown names are rejected); setting `status` to `active` also recovers an endpoint auto-paused as `failing`. Requires scope `webhooks:write`. Not available under X-Profile-Id delegation - webhooks live on your developer workspace and receive profile events automatically (with profile_id attached).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Webhook id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Provide at least one field.", "properties": { "url": { "type": "string", "format": "uri", "description": "Public HTTPS endpoint." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "post.published", "post.partial", "post.failed", "account.connected", "account.disconnected", "account.token_expired", "comment.received", "message.received", "job.completed", "job.failed", "balance.low", "balance.depleted", "key.revoked", "wallet.recharge.succeeded", "wallet.recharge.failed", "account_billing.charged", "account_billing.failed", "contact.created", "contact.updated", "contact.tag_added", "contact.tag_removed", "deal.created", "deal.stage_changed", "deal.won", "deal.lost", "post.scheduled", "post.cancelled", "post.recycled", "post.external.created", "post.external.updated", "message.sent", "conversation.started", "reaction.received", "review.new", "review.updated", "message.delivered", "message.read", "message.failed" ] }, "description": "Full replacement list of subscribed events." }, "status": { "type": "string", "enum": [ "active", "paused" ], "description": "Pause or resume deliveries." } } }, "example": { "events": [ "post.published", "post.failed", "comment.received" ], "status": "active" } } } }, "responses": { "200": { "description": "Updated webhook", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "description": "active | paused | failing" }, "last_triggered_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "id": 128, "url": "https://example.com/launch", "events": [ "post.published" ], "status": "published", "last_triggered_at": "2026-07-26T09:41:22Z", "created_at": "2026-07-26T09:41:22Z" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/social/connect/{platform}": { "post": { "summary": "Start headless account connection", "description": "Begin connecting a NEW social account from your own UI (no SmartlyQ dashboard session needed). Returns a one-time `connect_url` (valid 15 minutes) — open it in a browser so the user can authorize. After they approve, the platform's OAuth callback completes the connection and (if provided) redirects to `return_url` with `?connected=&platform=`. Supported on all platforms. Platforms that expose multiple targets (YouTube channels, Google Business locations, Tumblr blogs, LinkedIn pages) connect them all automatically. Poll completion with `GET /social/connect/{state_token}`. Requires scope `social:write`.\n\nSome platforms connect with credentials instead of a browser round trip, and return the connected account directly rather than a `connect_url`: Telegram (`bot_token` + `chat`), WhatsApp (`waba_id` + `phone_number_id` + `access_token`) and Bluesky (`identifier` + `app_password`).", "operationId": "connectSocialAccount", "tags": [ "Social" ], "parameters": [ { "name": "platform", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "facebook", "instagram", "twitter", "linkedin", "youtube", "tiktok", "threads", "bluesky", "pinterest", "reddit", "snapchat", "tumblr", "gmb", "discord", "telegram", "whatsapp" ] }, "description": "Platform to connect. All 15 platforms are supported (use `twitter` for X, `gmb` for Google Business). 14 are OAuth flows returning a `connect_url` (`discord` runs the server-webhook authorize flow). `telegram` is a CREDENTIAL connect instead: pass `bot_token` + `chat` in the body and the account connects immediately - no URL to open. `whatsapp` is a credential connect too: POST body { waba_id, phone_number_id, access_token } (a Meta system-user token) links one WhatsApp Business number." }, { "$ref": "#/components/parameters/ProfileHeader" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "return_url": { "type": "string", "format": "uri", "description": "Optional URL to redirect the user to after they finish authorizing." }, "bot_token": { "type": "string", "description": "Telegram only (required for it): your bot's token from @BotFather (e.g. `123456:AA...`). Verified against Telegram (getMe/getChat/getChatMember - the bot must have posting rights in the chat) and stored encrypted." }, "chat": { "type": "string", "description": "Telegram only (required for it): the target channel/group as `@channelusername` or a numeric chat id. Private chats are rejected." }, "identifier": { "type": "string", "description": "Bluesky only: your handle (e.g. yourname.bsky.social), DID, or account email. Send it with `app_password` to connect without a browser." }, "app_password": { "type": "string", "description": "Bluesky only: an app password generated in Bluesky settings (format xxxx-xxxx-xxxx-xxxx) - never your account password, which is rejected. Supplying this connects the account immediately instead of returning a connect_url." }, "waba_id": { "type": "string", "description": "WhatsApp only (required for it): your WhatsApp Business Account id." }, "phone_number_id": { "type": "string", "description": "WhatsApp only (required for it): the phone number id to connect, from the WABA." }, "access_token": { "type": "string", "description": "WhatsApp only (required for it): a system-user access token with whatsapp_business_messaging and whatsapp_business_management. Stored encrypted." } } } } } }, "responses": { "201": { "description": "Connection link created. For `telegram` the response has no `connect_url` - the account is connected immediately and returned as `{platform, account}`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "platform": { "type": "string" }, "connect_url": { "type": "string", "format": "uri", "description": "Open in a browser to authorize. Expires in 15 minutes." }, "expires_at": { "type": "string", "format": "date-time" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "platform": "twitter", "connect_url": "https://example.com/launch", "expires_at": "2026-07-26T09:41:22Z" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "summary": "Poll headless connection status", "description": "Poll whether a headless connection finished, using the `state_token` embedded in the `connect_url` returned by `POST /social/connect/{platform}`. Useful when your app can't observe the `return_url` redirect (server-to-server, or the user closed the tab). Verifies the signed token and reports `connected` (with the new account), `pending`, or `expired`. Requires scope `social:read`.", "operationId": "connectSocialAccountStatus", "tags": [ "Social" ], "parameters": [ { "name": "platform", "in": "path", "required": true, "schema": { "type": "string" }, "description": "For this GET, pass the `state_token` from the `connect_url` (NOT a platform name)." }, { "$ref": "#/components/parameters/ProfileHeader" } ], "responses": { "200": { "description": "Connection status", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "platform": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "connected", "expired" ] }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "account": { "type": "object", "nullable": true, "description": "Present when status is `connected`.", "properties": { "account_id": { "type": "integer" }, "name": { "type": "string" }, "username": { "type": "string" }, "platform": { "type": "string" } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "platform": "twitter", "status": "pending", "expires_at": "2026-07-26T09:41:22Z", "account": { "account_id": 128, "name": "Acme Corp", "username": "example-username", "platform": "twitter" } }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/videos/hook": { "post": { "summary": "Generate a viral hook line", "description": "Writes ONE scroll-stopping hook line (<=8 words) to overlay on a short's first seconds. Provide `script` or `transcript_words`. Billed per request from your API wallet; refunded on failure.", "operationId": "generateVideoHook", "tags": [ "Videos" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "script": { "type": "string", "description": "Plain script/transcript text." }, "transcript_words": { "type": "array", "items": { "type": "object" }, "description": "Word-level transcript [{word,start,end}] (alternative to script)." } } } } } }, "responses": { "200": { "description": "The generated hook line.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "hook": { "type": "string", "example": "Stop scrolling - this 10-second trick doubled our reach." } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "hook": "Stop scrolling - this 10-second trick doubled our reach." }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientBalance" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/videos/broll-suggest": { "post": { "summary": "Suggest B-roll moments", "description": "Suggests B-roll moments (with timings) for a word-level transcript. Billed per request; refunded on failure.", "operationId": "suggestBroll", "tags": [ "Videos" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "transcript_words" ], "properties": { "transcript_words": { "type": "array", "items": { "type": "object", "properties": { "word": { "type": "string" }, "start": { "type": "integer", "description": "ms" }, "end": { "type": "integer", "description": "ms" } } }, "description": "Word-level transcript with millisecond start/end." }, "target_count": { "type": "integer", "default": 5, "description": "How many suggestions (3-10)." } } } } } }, "responses": { "200": { "description": "B-roll suggestions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "suggestions": { "type": "array", "items": { "type": "object", "properties": { "start_ms": { "type": "integer", "example": 4200 }, "end_ms": { "type": "integer", "example": 7800 }, "query": { "type": "string", "example": "city skyline timelapse" }, "reason": { "type": "string", "example": "Speaker references rapid growth." } } }, "example": [ { "start_ms": 4200, "end_ms": 7800, "query": "city skyline timelapse", "reason": "Speaker references rapid growth." } ] } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "suggestions": [ { "start_ms": 4200, "end_ms": 7800, "query": "city skyline timelapse", "reason": "Speaker references rapid growth." } ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientBalance" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/videos/emphasis": { "post": { "summary": "Suggest on-screen emphasis", "description": "Picks on-screen emphasis moments (punchy full-screen text with timings) from a word-level transcript. Billed per request; refunded on failure.", "operationId": "suggestEmphasis", "tags": [ "Videos" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "transcript_words" ], "properties": { "transcript_words": { "type": "array", "items": { "type": "object", "properties": { "word": { "type": "string" }, "start": { "type": "integer", "description": "ms" }, "end": { "type": "integer", "description": "ms" } } }, "description": "Word-level transcript with millisecond start/end." }, "target_count": { "type": "integer", "default": 8, "description": "How many picks (3-15)." } } } } } }, "responses": { "200": { "description": "Emphasis picks.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "emphasis": { "type": "array", "items": { "type": "object", "properties": { "word": { "type": "string", "example": "doubled" }, "start_ms": { "type": "integer", "example": 5300 }, "style": { "type": "string", "example": "highlight" } } }, "example": [ { "word": "doubled", "start_ms": 5300, "style": "highlight" } ] } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "emphasis": [ { "word": "doubled", "start_ms": 5300, "style": "highlight" } ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientBalance" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/videos/viral-thumbnail": { "post": { "summary": "Generate a viral thumbnail", "description": "Generates a viral, click-optimized thumbnail from a video title (optionally guided by a reference image) and returns a hosted `image_url`. Billed per request; refunded on failure.", "operationId": "generateViralThumbnail", "tags": [ "Videos" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "description": "Video title (1-300 chars)." }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16" ], "default": "16:9", "description": "16:9 (YouTube) or 9:16 (Shorts/Reels/TikTok)." }, "image_url": { "type": "string", "description": "Optional https reference image whose subject is preserved." } } } } } }, "responses": { "200": { "description": "The generated thumbnail (image_url + media_id).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "image_url": { "type": "string", "example": "https://cdn.smartlyq.com/thumbnails/thumb-8f21c04a.png" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "image_url": "https://cdn.smartlyq.com/thumbnails/thumb-8f21c04a.png" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientBalance" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/content/caption": { "post": { "summary": "Generate a social caption", "description": "Writes ONE platform-tuned social caption (with hashtags) for a short-form video. Billed per request; refunded on failure.", "operationId": "generateCaption", "tags": [ "Content" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "twitter", "tiktok", "instagram", "facebook", "linkedin", "youtube" ], "description": "Destination platform (sets length + voice)." }, "tone": { "type": "string", "default": "engaging" }, "title": { "type": "string" }, "content": { "type": "string", "description": "What the video says (transcript) so the caption is on-topic." }, "current_caption": { "type": "string", "description": "An existing caption to improve." }, "instruction": { "type": "string", "description": "Extra instruction, e.g. 'add a CTA'." } } } } } }, "responses": { "200": { "description": "The generated caption.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "caption": { "type": "string", "example": "We just doubled our reach in 30 days - here is the exact playbook 🧵" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "caption": "We just doubled our reach in 30 days - here is the exact playbook 🧵" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientBalance" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/shorts/generate": { "post": { "summary": "Generate viral shorts from a long video", "description": "Turns one long video into ranked, ready-to-post vertical (9:16) clips with hooks + virality scores. Provide `video_url` (direct media) OR `source_url` (a YouTube/Vimeo/TikTok link). Returns `202 Accepted` with a `job_uid`; poll `GET /v1/shorts/{uid}`. Billed per REQUESTED clip from your API wallet; a wholly-failed job is refunded automatically.", "operationId": "generateShorts", "tags": [ "Shorts" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "video_url": { "type": "string", "description": "Direct media URL (provide this or source_url)." }, "source_url": { "type": "string", "description": "Platform link (YouTube/Vimeo/TikTok/Loom/...), downloaded server-side." }, "clip_count": { "type": "integer", "default": 10, "description": "Clips to produce (3-20). Billed per requested clip." }, "language": { "type": "string", "default": "en", "description": "Spoken language code." } } } } } }, "responses": { "202": { "description": "Accepted — poll GET /v1/shorts/{uid} for the ranked clips", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "job_uid": { "type": "string", "example": "shorts_8f21c04a" }, "status": { "type": "string", "example": "queued" }, "clip_count": { "type": "integer", "example": 3 } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "job_uid": "shorts_8f21c04a", "status": "queued", "clip_count": 3 }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientBalance" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/shorts": { "get": { "summary": "List shorts jobs", "description": "Lists your workspace's Magic Shorts jobs.", "operationId": "listShorts", "tags": [ "Shorts" ], "parameters": [ { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Items per page (max 100)." } ], "responses": { "200": { "description": "A list of shorts jobs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "shorts": { "type": "array", "items": { "type": "object", "properties": { "job_uid": { "type": "string", "example": "shorts_8f21c04a" }, "status": { "type": "string", "example": "completed" }, "clip_count": { "type": "integer", "example": 3 }, "clips": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "example": "https://cdn.smartlyq.com/shorts/clip-1.mp4" }, "title": { "type": "string", "example": "The 3-second hook" }, "score": { "type": "number", "example": 0.92 }, "start": { "type": "number", "example": 12.4 }, "end": { "type": "number", "example": 41.0 } } }, "example": [ { "url": "https://cdn.smartlyq.com/shorts/clip-1.mp4", "title": "The 3-second hook", "score": 0.92, "start": 12.4, "end": 41.0 } ] }, "created_at": { "type": "string", "example": "2026-07-26T09:41:22Z" } } }, "example": [ { "job_uid": "shorts_8f21c04a", "status": "completed", "clip_count": 3, "clips": [ { "url": "https://cdn.smartlyq.com/shorts/clip-1.mp4", "title": "The 3-second hook", "score": 0.92, "start": 12.4, "end": 41.0 } ], "created_at": "2026-07-26T09:41:22Z" } ] } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "shorts": [ { "job_uid": "shorts_8f21c04a", "status": "completed", "clip_count": 3, "clips": [ { "url": "https://cdn.smartlyq.com/shorts/clip-1.mp4", "title": "The 3-second hook", "score": 0.92, "start": 12.4, "end": 41.0 } ], "created_at": "2026-07-26T09:41:22Z" } ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/shorts/{uid}": { "get": { "summary": "Get shorts job + clips", "description": "Gets a Magic Shorts job's status and its ranked clips (hooks, scores, clip URLs). Poll after `generateShorts` until `status` is `completed`.", "operationId": "getShorts", "tags": [ "Shorts" ], "parameters": [ { "name": "uid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The job_uid returned by shorts/generate." } ], "responses": { "200": { "description": "The shorts job and its clips.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "job_uid": { "type": "string", "example": "shorts_8f21c04a" }, "status": { "type": "string", "example": "completed" }, "clip_count": { "type": "integer", "example": 3 }, "clips": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "example": "https://cdn.smartlyq.com/shorts/clip-1.mp4" }, "title": { "type": "string", "example": "The 3-second hook" }, "score": { "type": "number", "example": 0.92 }, "start": { "type": "number", "example": 12.4 }, "end": { "type": "number", "example": 41.0 } } }, "example": [ { "url": "https://cdn.smartlyq.com/shorts/clip-1.mp4", "title": "The 3-second hook", "score": 0.92, "start": 12.4, "end": 41.0 } ] }, "created_at": { "type": "string", "example": "2026-07-26T09:41:22Z" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "job_uid": "shorts_8f21c04a", "status": "completed", "clip_count": 3, "clips": [ { "url": "https://cdn.smartlyq.com/shorts/clip-1.mp4", "title": "The 3-second hook", "score": 0.92, "start": 12.4, "end": 41.0 } ], "created_at": "2026-07-26T09:41:22Z" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/presentations/generate": { "post": { "summary": "Generate presentation", "description": "Generates a complete AI presentation (slide deck) from a single prompt. Returns `202 Accepted` immediately with a `job_id`; poll `GET /v1/jobs/{job_uid}` for status. Generation typically takes 60-120 seconds. When the job completes, its `result` contains the `presentation_id` and a `url` that opens the finished deck in the presentations editor.\n\n**Billing:** a flat charge per generated deck is deducted from your API wallet when the job is accepted. If generation fails the charge is automatically refunded.\n\nRequires the `presentations:write` scope.", "operationId": "generatePresentation", "tags": [ "Presentations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "prompt" ], "properties": { "prompt": { "type": "string", "description": "The topic or brief for the deck - what the presentation should cover, who it is for, and any angle to take." }, "n_slides": { "type": "integer", "minimum": 3, "maximum": 12, "default": 8, "description": "Number of slides to generate (3-12)." }, "language": { "type": "string", "default": "en-US", "description": "BCP-47 language tag for the deck copy (e.g. en-US, de-DE, el-GR)." }, "tone": { "type": "string", "maxLength": 40, "default": "professional", "description": "Overall tone for the deck copy, e.g. professional, casual, persuasive." } } }, "example": { "prompt": "A product launch deck for an AI scheduling assistant, aimed at small marketing agencies", "n_slides": 10, "language": "en-US" } } } }, "responses": { "202": { "description": "Accepted - poll GET /v1/jobs/{job_uid} for the finished deck", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoJobCreatedResponse" }, "example": { "success": true, "data": { "job_uid": "job_a1b2c3d4e5f6", "status": "queued" }, "usage": { "units": 1, "cost": "0.4000", "balance_remaining": "14.6000" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientBalance" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/contacts": { "post": { "summary": "Create or upsert a contact", "description": "Create a CRM contact. With no `id` and a matching `email`, the existing contact is updated instead of duplicated (upsert). Fires the contact_created / contact_updated automation events.", "operationId": "createContact", "tags": [ "CRM Contacts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "name": { "type": "string", "description": "Full name; derived from first/last when those are sent." }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "company": { "type": "string" }, "role": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "prospect", "inactive" ] }, "timezone": { "type": "string" }, "language": { "type": "string" }, "source": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "attributes": { "type": "object", "description": "Custom attribute values keyed by attribute key.", "additionalProperties": true } } } } } }, "responses": { "201": { "description": "Contact created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 8412 }, "name": { "type": "string", "example": "Ada Lovelace" }, "first_name": { "type": "string", "example": "Ada" }, "last_name": { "type": "string", "example": "Lovelace" }, "email": { "type": "string", "example": "ada@example.com" }, "phone": { "type": "string", "example": "+30 694 123 4567" }, "company": { "type": "string", "example": "Acme Corp" }, "role": { "type": "string", "example": "Head of Growth" }, "status": { "type": "string", "example": "customer" }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "vip", "newsletter" ] }, "attributes": { "type": "object", "example": { "lead_source": "webinar" } }, "source": { "type": "string", "example": "api" }, "created_at": { "type": "string", "example": "2026-07-01T10:15:00Z" }, "updated_at": { "type": "string", "example": "2026-07-26T09:41:22Z" } }, "description": "The created (or upserted) contact; matched_by is set when an existing contact was matched by email/phone." }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "id": 8412, "name": "Ada Lovelace", "first_name": "Ada", "last_name": "Lovelace", "email": "ada@example.com", "phone": "+30 694 123 4567", "company": "Acme Corp", "role": "Head of Growth", "status": "customer", "tags": [ "vip", "newsletter" ], "attributes": { "lead_source": "webinar" }, "source": "api", "created_at": "2026-07-01T10:15:00Z", "updated_at": "2026-07-26T09:41:22Z", "matched_by": null }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "200": { "description": "Existing contact updated (matched by email)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 8412 }, "name": { "type": "string", "example": "Ada Lovelace" }, "first_name": { "type": "string", "example": "Ada" }, "last_name": { "type": "string", "example": "Lovelace" }, "email": { "type": "string", "example": "ada@example.com" }, "phone": { "type": "string", "example": "+30 694 123 4567" }, "company": { "type": "string", "example": "Acme Corp" }, "role": { "type": "string", "example": "Head of Growth" }, "status": { "type": "string", "example": "customer" }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "vip", "newsletter" ] }, "attributes": { "type": "object", "example": { "lead_source": "webinar" } }, "source": { "type": "string", "example": "api" }, "created_at": { "type": "string", "example": "2026-07-01T10:15:00Z" }, "updated_at": { "type": "string", "example": "2026-07-26T09:41:22Z" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "id": 8412, "name": "Ada Lovelace", "first_name": "Ada", "last_name": "Lovelace", "email": "ada@example.com", "phone": "+30 694 123 4567", "company": "Acme Corp", "role": "Head of Growth", "status": "customer", "tags": [ "vip", "newsletter" ], "attributes": { "lead_source": "webinar" }, "source": "api", "created_at": "2026-07-01T10:15:00Z", "updated_at": "2026-07-26T09:41:22Z", "matched_by": "email" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "get": { "summary": "List contacts", "description": "List CRM contacts in the workspace. Supports `search`, `tag` and `status` filters plus pagination.", "operationId": "listContacts", "tags": [ "CRM Contacts" ], "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Match name, email, company or phone." }, { "name": "tag", "in": "query", "schema": { "type": "string" }, "description": "Only contacts carrying this tag." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "prospect", "inactive" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } } ], "responses": { "200": { "description": "Paginated contacts", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 8412 }, "name": { "type": "string", "example": "Ada Lovelace" }, "first_name": { "type": "string", "example": "Ada" }, "last_name": { "type": "string", "example": "Lovelace" }, "email": { "type": "string", "example": "ada@example.com" }, "phone": { "type": "string", "example": "+30 694 123 4567" }, "company": { "type": "string", "example": "Acme Corp" }, "role": { "type": "string", "example": "Head of Growth" }, "status": { "type": "string", "example": "customer" }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "vip", "newsletter" ] }, "attributes": { "type": "object", "example": { "lead_source": "webinar" } }, "source": { "type": "string", "example": "api" }, "created_at": { "type": "string", "example": "2026-07-01T10:15:00Z" }, "updated_at": { "type": "string", "example": "2026-07-26T09:41:22Z" } } } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": [ { "id": 8412, "name": "Ada Lovelace", "first_name": "Ada", "last_name": "Lovelace", "email": "ada@example.com", "phone": "+30 694 123 4567", "company": "Acme Corp", "role": "Head of Growth", "status": "customer", "tags": [ "vip", "newsletter" ], "attributes": { "lead_source": "webinar" }, "source": "api", "created_at": "2026-07-01T10:15:00Z", "updated_at": "2026-07-26T09:41:22Z" } ], "pagination": { "total": 42, "page": 1, "per_page": 20, "total_pages": 3 }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/contacts/{id}": { "get": { "summary": "Get a contact", "operationId": "getContact", "tags": [ "CRM Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Contact", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 8412 }, "name": { "type": "string", "example": "Ada Lovelace" }, "first_name": { "type": "string", "example": "Ada" }, "last_name": { "type": "string", "example": "Lovelace" }, "email": { "type": "string", "example": "ada@example.com" }, "phone": { "type": "string", "example": "+30 694 123 4567" }, "company": { "type": "string", "example": "Acme Corp" }, "role": { "type": "string", "example": "Head of Growth" }, "status": { "type": "string", "example": "customer" }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "vip", "newsletter" ] }, "attributes": { "type": "object", "example": { "lead_source": "webinar" } }, "source": { "type": "string", "example": "api" }, "created_at": { "type": "string", "example": "2026-07-01T10:15:00Z" }, "updated_at": { "type": "string", "example": "2026-07-26T09:41:22Z" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "id": 8412, "name": "Ada Lovelace", "first_name": "Ada", "last_name": "Lovelace", "email": "ada@example.com", "phone": "+30 694 123 4567", "company": "Acme Corp", "role": "Head of Growth", "status": "customer", "tags": [ "vip", "newsletter" ], "attributes": { "lead_source": "webinar" }, "source": "api", "created_at": "2026-07-01T10:15:00Z", "updated_at": "2026-07-26T09:41:22Z" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "summary": "Update a contact", "description": "Update a contact by id. Fires the contact_updated automation event (plus tag_added / tag_removed for tag changes).", "operationId": "updateContact", "tags": [ "CRM Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "company": { "type": "string" }, "role": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "prospect", "inactive" ] }, "timezone": { "type": "string" }, "language": { "type": "string" }, "source": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "attributes": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "Updated contact", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 8412 }, "name": { "type": "string", "example": "Ada Lovelace" }, "first_name": { "type": "string", "example": "Ada" }, "last_name": { "type": "string", "example": "Lovelace" }, "email": { "type": "string", "example": "ada@example.com" }, "phone": { "type": "string", "example": "+30 694 123 4567" }, "company": { "type": "string", "example": "Acme Corp" }, "role": { "type": "string", "example": "Head of Growth" }, "status": { "type": "string", "example": "customer" }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "vip", "newsletter" ] }, "attributes": { "type": "object", "example": { "lead_source": "webinar" } }, "source": { "type": "string", "example": "api" }, "created_at": { "type": "string", "example": "2026-07-01T10:15:00Z" }, "updated_at": { "type": "string", "example": "2026-07-26T09:41:22Z" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "id": 8412, "name": "Ada Lovelace", "first_name": "Ada", "last_name": "Lovelace", "email": "ada@example.com", "phone": "+30 694 123 4567", "company": "Acme Corp", "role": "Head of Growth", "status": "customer", "tags": [ "vip", "newsletter" ], "attributes": { "lead_source": "webinar" }, "source": "api", "created_at": "2026-07-01T10:15:00Z", "updated_at": "2026-07-26T09:41:22Z" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "summary": "Delete contact", "operationId": "deleteContact", "tags": [ "CRM" ], "description": "Soft-deletes the contact (recoverable from Deleted contacts in the app). Requires scope `contacts:write`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": {}, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/contacts/{id}/tags": { "post": { "summary": "Add tags to a contact", "description": "Add one or more tags (idempotent union). Each newly added tag fires the tag_added automation event.", "operationId": "addContactTags", "tags": [ "CRM Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "tags" ], "properties": { "tags": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "The contact's full tag list after adding", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "string" }, "description": "The contact's full tag list after the change.", "example": [ "vip", "newsletter", "webinar-2026" ] } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "tags": [ "vip", "newsletter", "webinar-2026" ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "summary": "Remove tags from a contact", "description": "Remove one or more tags. Each removed tag fires the tag_removed automation event.", "operationId": "removeContactTags", "tags": [ "CRM Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "tags" ], "properties": { "tags": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "The contact's remaining tag list", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "string" }, "example": [ "vip" ] } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "tags": [ "vip" ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/contacts/{id}/notes": { "get": { "summary": "List contact notes", "operationId": "listContactNotes", "tags": [ "CRM Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Notes for the contact, newest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 771 }, "body": { "type": "string", "example": "Asked for an annual quote - follow up Friday." }, "author_name": { "type": "string", "example": "API" }, "created_at": { "type": "string", "example": "2026-07-26T09:41:22Z" } } } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": [ { "id": 771, "body": "Asked for an annual quote - follow up Friday.", "author_name": "API", "created_at": "2026-07-26T09:41:22Z" } ], "pagination": { "total": 42, "page": 1, "per_page": 20, "total_pages": 3 }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } }, "post": { "summary": "Add a note to a contact", "operationId": "addContactNote", "tags": [ "CRM Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "body" ], "properties": { "body": { "type": "string" }, "author_name": { "type": "string" } } } } } }, "responses": { "201": { "description": "Note created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 771 }, "body": { "type": "string", "example": "Asked for an annual quote - follow up Friday." } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "id": 771, "body": "Asked for an annual quote - follow up Friday." }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/pipelines": { "get": { "summary": "List pipelines", "description": "List sales pipelines in the workspace, each with its ordered stages.", "operationId": "listPipelines", "tags": [ "CRM Opportunities" ], "responses": { "200": { "description": "Pipelines with stages", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 3121 }, "name": { "type": "string", "example": "Sales Pipeline" }, "is_default": { "type": "boolean", "example": true }, "stages": { "type": "array", "items": { "type": "object", "properties": { "stage_key": { "type": "string", "example": "lead" }, "label": { "type": "string", "example": "Lead" }, "sort_order": { "type": "integer", "example": 1 } } }, "example": [ { "stage_key": "lead", "label": "Lead", "sort_order": 1 }, { "stage_key": "proposal", "label": "Proposal Sent", "sort_order": 2 }, { "stage_key": "won", "label": "Won", "sort_order": 3 } ] } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": [ { "id": 3121, "name": "Sales Pipeline", "is_default": true, "stages": [ { "stage_key": "lead", "label": "Lead", "sort_order": 1 }, { "stage_key": "proposal", "label": "Proposal Sent", "sort_order": 2 }, { "stage_key": "won", "label": "Won", "sort_order": 3 } ] } ], "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } }, "post": { "summary": "Create a pipeline", "operationId": "createPipeline", "tags": [ "CRM Opportunities" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "seed_default_stages": { "type": "boolean", "default": true, "description": "Seed the default 7-stage template." } } } } } }, "responses": { "201": { "description": "Pipeline created (with stages)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 3121 }, "name": { "type": "string", "example": "Sales Pipeline" }, "is_default": { "type": "boolean", "example": true }, "stages": { "type": "array", "items": { "type": "object", "properties": { "stage_key": { "type": "string", "example": "lead" }, "label": { "type": "string", "example": "Lead" }, "sort_order": { "type": "integer", "example": 1 } } }, "example": [ { "stage_key": "lead", "label": "Lead", "sort_order": 1 }, { "stage_key": "proposal", "label": "Proposal Sent", "sort_order": 2 }, { "stage_key": "won", "label": "Won", "sort_order": 3 } ] } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "id": 3121, "name": "Sales Pipeline", "is_default": true, "stages": [ { "stage_key": "lead", "label": "Lead", "sort_order": 1 }, { "stage_key": "proposal", "label": "Proposal Sent", "sort_order": 2 }, { "stage_key": "won", "label": "Won", "sort_order": 3 } ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/opportunities": { "get": { "summary": "List opportunities", "description": "List deals/opportunities. Filter by `pipeline_id`, `status`, `stage` or `assigned_user_id`.", "operationId": "listOpportunities", "tags": [ "CRM Opportunities" ], "parameters": [ { "name": "pipeline_id", "in": "query", "schema": { "type": "integer" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "open", "won", "lost", "abandoned" ] } }, { "name": "stage", "in": "query", "schema": { "type": "string" } }, { "name": "assigned_user_id", "in": "query", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } } ], "responses": { "200": { "description": "Paginated opportunities", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 512034 }, "pipeline_id": { "type": "integer", "example": 3121 }, "name": { "type": "string", "example": "Acme annual plan" }, "contact_email": { "type": "string", "example": "ada@example.com" }, "company": { "type": "string", "example": "Acme Corp" }, "value": { "type": "number", "example": 2500.0 }, "stage": { "type": "string", "example": "proposal" }, "status": { "type": "string", "example": "open" }, "assigned_user_id": { "type": "integer", "nullable": true, "example": null }, "created_at": { "type": "string", "example": "2026-07-01T10:15:00Z" } } } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": [ { "id": 512034, "pipeline_id": 3121, "name": "Acme annual plan", "contact_email": "ada@example.com", "company": "Acme Corp", "value": 2500.0, "stage": "proposal", "status": "open", "assigned_user_id": null, "created_at": "2026-07-01T10:15:00Z" } ], "pagination": { "total": 42, "page": 1, "per_page": 20, "total_pages": 3 }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } }, "post": { "summary": "Create an opportunity", "description": "Create a deal/opportunity. Fires deal_created (and deal_won / deal_lost when created with a terminal status). Falls back to the default pipeline when `pipeline_id` is omitted.", "operationId": "createOpportunity", "tags": [ "CRM Opportunities" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Opportunity / deal name." }, "contact_email": { "type": "string", "format": "email" }, "company": { "type": "string" }, "value": { "type": "number", "description": "Monetary value." }, "pipeline_id": { "type": "integer" }, "stage": { "type": "string", "description": "Stage key within the pipeline." }, "status": { "type": "string", "enum": [ "open", "won", "lost", "abandoned" ], "default": "open" }, "assigned_user_id": { "type": "integer" }, "next_action_date": { "type": "string", "format": "date" }, "notes": { "type": "string" } } } } } }, "responses": { "201": { "description": "Opportunity created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 512034 }, "pipeline_id": { "type": "integer", "example": 3121 }, "name": { "type": "string", "example": "Acme annual plan" }, "contact_email": { "type": "string", "example": "ada@example.com" }, "company": { "type": "string", "example": "Acme Corp" }, "value": { "type": "number", "example": 2500.0 }, "stage": { "type": "string", "example": "proposal" }, "status": { "type": "string", "example": "open" }, "assigned_user_id": { "type": "integer", "nullable": true, "example": null }, "created_at": { "type": "string", "example": "2026-07-01T10:15:00Z" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "id": 512034, "pipeline_id": 3121, "name": "Acme annual plan", "contact_email": "ada@example.com", "company": "Acme Corp", "value": 2500.0, "stage": "proposal", "status": "open", "assigned_user_id": null, "created_at": "2026-07-01T10:15:00Z" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/opportunities/{id}": { "get": { "summary": "Get an opportunity", "operationId": "getOpportunity", "tags": [ "CRM Opportunities" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Opportunity", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 512034 }, "pipeline_id": { "type": "integer", "example": 3121 }, "name": { "type": "string", "example": "Acme annual plan" }, "contact_email": { "type": "string", "example": "ada@example.com" }, "company": { "type": "string", "example": "Acme Corp" }, "value": { "type": "number", "example": 2500.0 }, "stage": { "type": "string", "example": "proposal" }, "status": { "type": "string", "example": "open" }, "assigned_user_id": { "type": "integer", "nullable": true, "example": null }, "created_at": { "type": "string", "example": "2026-07-01T10:15:00Z" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "id": 512034, "pipeline_id": 3121, "name": "Acme annual plan", "contact_email": "ada@example.com", "company": "Acme Corp", "value": 2500.0, "stage": "proposal", "status": "open", "assigned_user_id": null, "created_at": "2026-07-01T10:15:00Z" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "summary": "Update an opportunity", "description": "Update a deal. Moving `stage` follows won/lost stage semantics into `status` unless `status` is set explicitly. Fires deal_stage_changed / deal_won / deal_lost as applicable.", "operationId": "updateOpportunity", "tags": [ "CRM Opportunities" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "contact_email": { "type": "string", "format": "email" }, "company": { "type": "string" }, "value": { "type": "number" }, "pipeline_id": { "type": "integer" }, "stage": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "won", "lost", "abandoned" ] }, "assigned_user_id": { "type": "integer" }, "next_action_date": { "type": "string", "format": "date" }, "notes": { "type": "string" } } } } } }, "responses": { "200": { "description": "Updated opportunity", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 512034 }, "pipeline_id": { "type": "integer", "example": 3121 }, "name": { "type": "string", "example": "Acme annual plan" }, "contact_email": { "type": "string", "example": "ada@example.com" }, "company": { "type": "string", "example": "Acme Corp" }, "value": { "type": "number", "example": 2500.0 }, "stage": { "type": "string", "example": "proposal" }, "status": { "type": "string", "example": "open" }, "assigned_user_id": { "type": "integer", "nullable": true, "example": null }, "created_at": { "type": "string", "example": "2026-07-01T10:15:00Z" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "id": 512034, "pipeline_id": 3121, "name": "Acme annual plan", "contact_email": "ada@example.com", "company": "Acme Corp", "value": 2500.0, "stage": "proposal", "status": "open", "assigned_user_id": null, "created_at": "2026-07-01T10:15:00Z" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "summary": "Delete an opportunity", "operationId": "deleteOpportunity", "tags": [ "CRM Opportunities" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": {}, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/opportunities/{id}/status": { "post": { "summary": "Update opportunity status", "description": "Set the opportunity outcome. Transitioning into won/lost fires deal_won / deal_lost.", "operationId": "updateOpportunityStatus", "tags": [ "CRM Opportunities" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "open", "won", "lost", "abandoned" ] } } } } } }, "responses": { "200": { "description": "Updated opportunity", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 512034 }, "pipeline_id": { "type": "integer", "example": 3121 }, "name": { "type": "string", "example": "Acme annual plan" }, "contact_email": { "type": "string", "example": "ada@example.com" }, "company": { "type": "string", "example": "Acme Corp" }, "value": { "type": "number", "example": 2500.0 }, "stage": { "type": "string", "example": "proposal" }, "status": { "type": "string", "example": "open" }, "assigned_user_id": { "type": "integer", "nullable": true, "example": null }, "created_at": { "type": "string", "example": "2026-07-01T10:15:00Z" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "id": 512034, "pipeline_id": 3121, "name": "Acme annual plan", "contact_email": "ada@example.com", "company": "Acme Corp", "value": 2500.0, "stage": "proposal", "status": "won", "assigned_user_id": null, "created_at": "2026-07-01T10:15:00Z" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/workspaces": { "post": { "summary": "Create a workspace (sub-account)", "description": "Create a sub-account workspace under the agency the API key belongs to. Requires the workspaces:write scope; plan workspace caps apply.", "operationId": "createWorkspace", "tags": [ "Workspaces" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 120 }, "account_type": { "type": "string", "enum": [ "client", "agency_internal" ], "default": "client" } } } } } }, "responses": { "201": { "description": "Workspace created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 421077 }, "name": { "type": "string", "example": "Client - Acme Corp" }, "hash_id": { "type": "string", "example": "ws_8f21c04ab3d1" }, "status": { "type": "string", "example": "active" }, "created_at": { "type": "string", "example": "2026-07-01T10:15:00Z" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "id": 421077, "name": "Client - Acme Corp", "hash_id": "ws_8f21c04ab3d1", "status": "active", "created_at": "2026-07-01T10:15:00Z" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "402": { "description": "Workspace limit reached for the plan" }, "409": { "description": "Key's workspace has no agency tenant" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "get": { "summary": "List workspaces (sub-accounts)", "description": "List the sub-account workspaces under the agency the API key belongs to, each with its billing state and sub-wallet balance. Requires the workspaces:read scope.", "operationId": "listWorkspaces", "tags": [ "Workspaces" ], "responses": { "200": { "description": "List of sub-accounts", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "workspaces": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 421077 }, "name": { "type": "string", "example": "Client - Acme Corp" }, "hash_id": { "type": "string", "example": "ws_8f21c04ab3d1" }, "status": { "type": "string", "example": "active" }, "created_at": { "type": "string", "example": "2026-07-01T10:15:00Z" } } }, "example": [ { "id": 421077, "name": "Client - Acme Corp", "hash_id": "ws_8f21c04ab3d1", "status": "active", "created_at": "2026-07-01T10:15:00Z" } ] } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "workspaces": [ { "id": 421077, "name": "Client - Acme Corp", "hash_id": "ws_8f21c04ab3d1", "status": "active", "created_at": "2026-07-01T10:15:00Z" } ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "409": { "description": "Key's workspace has no agency tenant" } } } }, "/workspaces/bulk": { "post": { "summary": "Bulk sub-account action", "description": "Apply one lifecycle action - pause, resume, or disable_saas - to many client sub-accounts in a single call. **Requires an active SaaS plan**: the agency must have a connected, charges-enabled Stripe account able to bill its clients; otherwise the call returns 403 SAAS_PLAN_REQUIRED. High-trust: requires the dedicated workspaces:bulk scope (separate from workspaces:write) because a mass action is high blast-radius. Applies per workspace and returns applied/failed counts plus a per-workspace results array; the id list is capped at 200. disable_saas cascades (cancels each subscription and refunds each sub-wallet to the agency) and is irreversible, so it also requires a typed confirmation.", "operationId": "bulkWorkspaceAction", "tags": [ "Workspaces" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "workspace_ids", "action" ], "properties": { "workspace_ids": { "type": "array", "items": { "type": "integer" }, "maxItems": 200, "description": "Client sub-account workspace ids." }, "action": { "type": "string", "enum": [ "pause", "resume", "disable_saas" ] }, "cancel_subscription": { "type": "boolean", "default": false, "description": "For disable_saas only: also cancel each client's Stripe subscription." }, "confirm": { "type": "string", "enum": [ "BULK" ], "description": "Required (\"BULK\") when action is disable_saas." } } } } } }, "responses": { "200": { "description": "Bulk action applied; body reports applied/failed and per-workspace results", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "workspace_id": { "type": "integer", "example": 421077 }, "ok": { "type": "boolean", "example": true } } }, "example": [ { "workspace_id": 421077, "ok": true }, { "workspace_id": 421078, "ok": true } ] } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "results": [ { "workspace_id": 421077, "ok": true }, { "workspace_id": 421078, "ok": true } ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "403": { "description": "Agency is not on an active SaaS plan (no connected, charges-enabled Stripe account)" }, "409": { "description": "Key's workspace has no agency tenant" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/workspaces/{id}": { "get": { "summary": "Get a workspace (sub-account)", "description": "Get one sub-account: name, account type, billing mode, rebilling state, and sub-wallet balance. Requires the workspaces:read scope.", "operationId": "getWorkspace", "tags": [ "Workspaces" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Workspace id." } ], "responses": { "200": { "description": "Sub-account detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 421077 }, "name": { "type": "string", "example": "Client - Acme Corp" }, "hash_id": { "type": "string", "example": "ws_8f21c04ab3d1" }, "status": { "type": "string", "example": "active" }, "created_at": { "type": "string", "example": "2026-07-01T10:15:00Z" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "id": 421077, "name": "Client - Acme Corp", "hash_id": "ws_8f21c04ab3d1", "status": "active", "created_at": "2026-07-01T10:15:00Z" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "404": { "description": "Workspace not found in your agency" } } }, "delete": { "summary": "Delete a workspace (sub-account)", "description": "Permanently delete a client sub-account. The workspace is scheduled for asynchronous teardown and disappears immediately; its data is purged within a few minutes. Blocked (409) while the sub-account is still in SaaS mode - disable SaaS first - and blocked (422) for the agency's own workspaces. Requires the workspaces:write scope and a typed confirmation.", "operationId": "deleteWorkspace", "tags": [ "Workspaces" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Workspace id (must be a client sub-account, not your own)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "confirm" ], "properties": { "confirm": { "type": "string", "enum": [ "DELETE" ], "description": "Must be the literal string DELETE to acknowledge this is permanent." } } } } } }, "responses": { "202": { "description": "Sub-account scheduled for deletion", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "workspace_id": { "type": "integer", "example": 421077 }, "scheduled": { "type": "boolean", "example": true } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "workspace_id": 421077, "scheduled": true }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "409": { "description": "SaaS mode is still active - disable it first" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/workspaces/{id}/disable-saas": { "post": { "summary": "Disable SaaS mode for a workspace", "description": "Disable SaaS mode for a sub-account: switch it back to agency billing, turn off rebilling, and refund any remaining sub-wallet balance to the agency wallet. Optionally cancels the client's subscription. Required before a SaaS sub-account can be deleted. Requires the workspaces:write scope. **SaaS-member only**: this is a SaaS-mode action, so your agency must be on an active SaaS plan; otherwise it returns 403 SAAS_PLAN_REQUIRED.", "operationId": "disableWorkspaceSaas", "tags": [ "Workspaces" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Workspace id." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "cancel_subscription": { "type": "boolean", "default": false, "description": "Also cancel the client's Stripe subscription." } } } } } }, "responses": { "200": { "description": "SaaS mode disabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "state": { "type": "string", "example": "internal" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "ok": true, "state": "internal" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "403": { "description": "Agency is not on an active SaaS plan" }, "404": { "description": "Workspace not found in your agency" } } } }, "/workspaces/{id}/pause": { "post": { "summary": "Pause (suspend) a workspace", "description": "Pause a client sub-account: block all access + operations for its users, but keep the data (reversible with resume). Cannot pause the agency's own workspaces. Requires the workspaces:write scope.", "operationId": "pauseWorkspace", "tags": [ "Workspaces" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Workspace id (must be a client sub-account, not your own)." } ], "responses": { "200": { "description": "Sub-account paused", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "paused": { "type": "boolean", "example": true }, "workspace_id": { "type": "integer", "example": 421077 } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "ok": true, "paused": true, "workspace_id": 421077 }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "422": { "description": "Cannot pause an agency-owned workspace" } } } }, "/workspaces/{id}/resume": { "post": { "summary": "Resume a paused workspace", "description": "Reactivate a paused sub-account: restore access + operations. Requires the workspaces:write scope.", "operationId": "resumeWorkspace", "tags": [ "Workspaces" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Workspace id." } ], "responses": { "200": { "description": "Sub-account resumed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "paused": { "type": "boolean", "example": false }, "workspace_id": { "type": "integer", "example": 421077 } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "ok": true, "paused": false, "workspace_id": 421077 }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "404": { "description": "Workspace not found in your agency" } } } }, "/workspaces/{id}/subscription": { "get": { "summary": "Get a sub-account's subscription", "description": "Read a sub-account's SaaS subscription + billing snapshot: billing_mode, rebilling state, plan_id, Stripe subscription_status, billing_cycle, and sub-wallet balance. Requires the workspaces:read scope.", "operationId": "getWorkspaceSubscription", "tags": [ "Workspaces" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Workspace id." } ], "responses": { "200": { "description": "Subscription + billing snapshot", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "workspace_id": { "type": "integer", "example": 421077 }, "tenant_id": { "type": "integer", "example": 7 }, "plan_id": { "type": "integer", "example": 3 }, "subscription_status": { "type": "string", "example": "active" }, "billing_cycle": { "type": "string", "example": "monthly" }, "billing_mode": { "type": "string", "example": "saas" }, "state": { "type": "string", "example": "active" }, "rebilling_enabled": { "type": "boolean", "example": true }, "balance_sqc": { "type": "number", "example": 1250.0 }, "sub_wallet_balance": { "type": "number", "example": 1250.0 } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "workspace_id": 421077, "tenant_id": 7, "plan_id": 3, "subscription_status": "active", "billing_cycle": "monthly", "billing_mode": "saas", "state": "active", "rebilling_enabled": true, "balance_sqc": 1250.0, "sub_wallet_balance": 1250.0 }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "404": { "description": "Workspace not found in your agency" } } } }, "/workspaces/{id}/wallet": { "get": { "summary": "Get a sub-account's wallet balance", "description": "Read a sub-account's wallet balance in SQC. Requires the workspaces:read scope.", "operationId": "getWorkspaceWallet", "tags": [ "Workspaces" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Workspace id." } ], "responses": { "200": { "description": "Wallet balance", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "workspace_id": { "type": "integer", "example": 421077 }, "status": { "type": "string", "example": "active" }, "state": { "type": "string", "example": "active" }, "billing_mode": { "type": "string", "example": "saas" }, "rebilling_enabled": { "type": "boolean", "example": true }, "balance_sqc": { "type": "number", "example": 1250.0 } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "ok": true, "workspace_id": 421077, "status": "active", "state": "active", "billing_mode": "saas", "rebilling_enabled": true, "balance_sqc": 1250.0 }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "404": { "description": "Workspace not found in your agency" } } } }, "/saas/plans": { "get": { "summary": "List SaaS plans", "description": "List the SaaS plans (client packages) configured for the agency the API key belongs to, with price, interval, setup fee, features and limits. Read-only. Requires the workspaces:read scope.", "operationId": "listSaasPlans", "tags": [ "Workspaces" ], "responses": { "200": { "description": "List of SaaS plans", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "plans": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 3 }, "tenant_id": { "type": "integer", "example": 7 }, "name": { "type": "string", "example": "Agency Pro" }, "description": { "type": "string", "example": "Full suite for client workspaces." }, "price": { "type": "number", "example": 97.0 }, "setup_fee": { "type": "number", "example": 0.0 }, "currency": { "type": "string", "example": "USD" }, "interval": { "type": "string", "example": "monthly" }, "credits_per_period": { "type": "number", "example": 5000.0 }, "workspaces_limit": { "type": "integer", "example": 10 }, "features": { "type": "array", "items": { "type": "string" }, "example": [ "social", "crm", "automations" ] } } }, "example": [ { "id": 3, "tenant_id": 7, "name": "Agency Pro", "description": "Full suite for client workspaces.", "price": 97.0, "setup_fee": 0.0, "currency": "USD", "interval": "monthly", "credits_per_period": 5000.0, "workspaces_limit": 10, "features": [ "social", "crm", "automations" ] } ] } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "plans": [ { "id": 3, "tenant_id": 7, "name": "Agency Pro", "description": "Full suite for client workspaces.", "price": 97.0, "setup_fee": 0.0, "currency": "USD", "interval": "monthly", "credits_per_period": 5000.0, "workspaces_limit": 10, "features": [ "social", "crm", "automations" ] } ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "409": { "description": "Key's workspace has no agency tenant" } } } }, "/saas/plans/{id}": { "get": { "summary": "Get a SaaS plan", "description": "Get one SaaS plan (client package) by id. Read-only. Requires the workspaces:read scope.", "operationId": "getSaasPlan", "tags": [ "Workspaces" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Plan (package) id." } ], "responses": { "200": { "description": "SaaS plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 3 }, "tenant_id": { "type": "integer", "example": 7 }, "name": { "type": "string", "example": "Agency Pro" }, "description": { "type": "string", "example": "Full suite for client workspaces." }, "price": { "type": "number", "example": 97.0 }, "setup_fee": { "type": "number", "example": 0.0 }, "currency": { "type": "string", "example": "USD" }, "interval": { "type": "string", "example": "monthly" }, "credits_per_period": { "type": "number", "example": 5000.0 }, "workspaces_limit": { "type": "integer", "example": 10 }, "features": { "type": "array", "items": { "type": "string" }, "example": [ "social", "crm", "automations" ] } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "id": 3, "tenant_id": 7, "name": "Agency Pro", "description": "Full suite for client workspaces.", "price": 97.0, "setup_fee": 0.0, "currency": "USD", "interval": "monthly", "credits_per_period": 5000.0, "workspaces_limit": 10, "features": [ "social", "crm", "automations" ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "404": { "description": "Plan not found in your agency" } } } }, "/contacts/{id}/enroll": { "post": { "summary": "Enroll a contact in an automation", "description": "Enrol a contact into an active automation. Queues a run for that automation carrying the contact's context.", "operationId": "enrollContact", "tags": [ "CRM Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "automation_id" ], "properties": { "automation_id": { "type": "integer", "description": "Active automation id." } } } } } }, "responses": { "202": { "description": "Contact enrolled (run queued)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "enrolled": { "type": "boolean", "example": true }, "contact_id": { "type": "integer", "example": 8412 }, "automation_id": { "type": "integer", "example": 91 } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "enrolled": true, "contact_id": 8412, "automation_id": 91 }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Automation is not active" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/contacts/{id}/messages": { "post": { "summary": "Log a message on a contact's timeline", "description": "Record an inbound/outbound message in the contact's conversation timeline (feeds the Inbox). Does NOT deliver email/SMS — channel delivery goes through automations/campaigns, which carry billing + compliance.", "operationId": "addContactMessage", "tags": [ "CRM Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "body_text" ], "properties": { "body_text": { "type": "string" }, "direction": { "type": "string", "enum": [ "in", "out" ], "default": "out" }, "channel": { "type": "string", "description": "e.g. email, sms, note (default note)." }, "subject": { "type": "string" } } } } } }, "responses": { "201": { "description": "Message logged", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 5523 }, "direction": { "type": "string", "example": "outbound" }, "channel": { "type": "string", "example": "email" }, "body_text": { "type": "string", "example": "Your invoice is attached." } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "id": 5523, "direction": "outbound", "channel": "email", "body_text": "Your invoice is attached." }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/custom-fields": { "get": { "summary": "List custom fields", "description": "List CRM custom field (custom attribute) definitions — the schema behind {{attributes.}}.", "operationId": "listCustomFields", "tags": [ "CRM Custom Fields" ], "responses": { "200": { "description": "Custom field definitions", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 44 }, "attr_key": { "type": "string", "example": "lead_source" }, "label": { "type": "string", "example": "Lead source" }, "created_at": { "type": "string", "example": "2026-07-01T10:15:00Z" } } } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": [ { "id": 44, "attr_key": "lead_source", "label": "Lead source", "created_at": "2026-07-01T10:15:00Z" } ], "pagination": { "total": 42, "page": 1, "per_page": 20, "total_pages": 3 }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } }, "post": { "summary": "Create a custom field", "description": "Define a new CRM custom field. Its attr_key is derived from the label and is used to set values via the contact's `attributes` object.", "operationId": "createCustomField", "tags": [ "CRM Custom Fields" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "label" ], "properties": { "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "textarea", "number", "date", "dropdown", "multiselect", "checkbox", "phone", "email", "url" ], "default": "text" }, "options": { "type": "array", "items": { "type": "string" }, "description": "Choices for dropdown/multiselect." }, "default_value": { "type": "string" }, "group_name": { "type": "string" } } } } } }, "responses": { "201": { "description": "Custom field created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 44 }, "attr_key": { "type": "string", "example": "lead_source" }, "label": { "type": "string", "example": "Lead source" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "id": 44, "attr_key": "lead_source", "label": "Lead source" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "409": { "description": "A field with this key already exists" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/custom-fields/{id}": { "delete": { "summary": "Delete a custom field", "operationId": "deleteCustomField", "tags": [ "CRM Custom Fields" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": {}, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "summary": "Update custom field", "operationId": "updateCustomField", "tags": [ "CRM" ], "description": "Updates the definition (label, type, options, default, group, sort order). attr_key is immutable - it names the values already stored on contacts. Requires scope `contacts:write`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 120 }, "type": { "type": "string" }, "options": { "type": "array", "items": { "type": "string" } }, "default_value": { "type": "string" }, "group_name": { "type": "string" }, "sort_order": { "type": "integer" } } }, "example": { "label": "Lead source", "options": [ "Webinar", "Ad", "Referral" ] } } } }, "responses": { "200": { "description": "Updated field", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "id": 44, "attr_key": "lead_source", "label": "Lead source", "type": "dropdown", "options": [ "Webinar", "Ad", "Referral" ], "default_value": "", "group_name": "Marketing", "sort_order": 1 }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/presentations": { "get": { "summary": "List presentations", "operationId": "listPresentations", "tags": [ "Presentations" ], "description": "Lists the authenticated user's presentations, newest first. Requires the `presentations:read` scope. Read-only - consumes no credits.", "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PerPageParam" } ], "responses": { "200": { "description": "Paginated list of presentations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresentationListResponse" }, "example": { "success": true, "data": [ { "id": "cm9x1a2b3c4d5e6f7g8h9", "title": "Q3 Performance Review", "slides_count": 8, "is_public": false, "theme": "mystique", "total_views": 12, "created_at": "2026-07-26T09:41:22Z", "updated_at": "2026-07-26T09:41:22Z" } ], "pagination": { "page": 1, "per_page": 1, "total": 42, "pages": 1 }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/presentations/{presentation_id}": { "get": { "summary": "Get presentation", "operationId": "getPresentation", "tags": [ "Presentations" ], "description": "Returns a presentation's details including its editor URL and, when public, its share URL. Requires the `presentations:read` scope. Read-only - consumes no credits.", "parameters": [ { "name": "presentation_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Presentation id returned by generate or list." } ], "responses": { "200": { "description": "Presentation details", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/PresentationDetail" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "id": "cm9x1a2b3c4d5e6f7g8h9", "title": "Q3 Performance Review", "slides_count": 8, "is_public": false, "theme": "mystique", "total_views": 12, "created_at": "2026-07-26T09:41:22Z", "updated_at": "2026-07-26T09:41:22Z", "edit_url": "https://presentations.smartlyq.com/presentation/cm9x1a2b3c4d5e6f7g8h9", "share_url": null }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "summary": "Delete presentation", "operationId": "deletePresentation", "tags": [ "Presentations" ], "description": "Permanently deletes a presentation and removes it from the media library. Requires the `presentations:write` scope.", "parameters": [ { "name": "presentation_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Presentation id returned by generate or list." } ], "responses": { "200": { "description": "Presentation deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "deleted": true }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/profiles": { "post": { "summary": "Create a profile", "description": "Create a profile - a managed sub-account for one end-customer of your product. Connected accounts inside profiles are billed monthly per account from your API wallet (no plan caps). Requires the profiles:write scope.", "operationId": "createProfile", "tags": [ "Profiles" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 120 }, "external_id": { "type": "string", "maxLength": 128, "description": "Your own customer id, for correlation" } } } } } }, "responses": { "201": { "description": "Profile created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" }, "example": { "id": 128, "workspace_id": 128, "name": "Acme Corp", "external_id": "client-042", "status": "active", "paused_for_billing": true, "created_at": "2026-07-26T09:41:22Z" } } } }, "402": { "description": "Profile limit reached" }, "404": { "description": "Profiles are not enabled for this account" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "get": { "summary": "List profiles", "description": "List your profiles (newest first). Requires the profiles:read scope.", "operationId": "listProfiles", "tags": [ "Profiles" ], "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PerPageParam" } ], "responses": { "200": { "description": "Profiles", "content": { "application/json": { "schema": { "type": "object", "properties": { "profiles": { "type": "array", "items": { "$ref": "#/components/schemas/Profile" } } } }, "example": { "profiles": [ { "id": 128, "workspace_id": 128, "name": "Acme Corp", "external_id": "client-042", "status": "active", "paused_for_billing": true, "created_at": "2026-07-26T09:41:22Z" } ] } } } } } } }, "/profiles/{id}": { "get": { "summary": "Get a profile", "operationId": "getProfile", "tags": [ "Profiles" ], "parameters": [ { "$ref": "#/components/parameters/ProfileIdParam" } ], "responses": { "200": { "description": "Profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" }, "example": { "id": 128, "workspace_id": 128, "name": "Acme Corp", "external_id": "client-042", "status": "active", "paused_for_billing": true, "created_at": "2026-07-26T09:41:22Z" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "summary": "Delete a profile", "description": "Soft-deletes the profile and schedules async teardown of its workspace and connected accounts. Send {\"confirm\": \"DELETE\"} in the body. Requires the profiles:write scope.", "operationId": "deleteProfile", "tags": [ "Profiles" ], "parameters": [ { "$ref": "#/components/parameters/ProfileIdParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "confirm" ], "properties": { "confirm": { "type": "string", "enum": [ "DELETE" ] } } } } } }, "responses": { "202": { "description": "Deletion scheduled", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "profile_id": { "type": "integer", "example": 2044 }, "scheduled": { "type": "boolean", "example": true } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "profile_id": 2044, "scheduled": true }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "patch": { "summary": "Update a profile", "operationId": "updateProfile", "description": "Rename a profile and/or change its external_id. Only the fields you send are modified; renaming also renames the profile's backing workspace so the two never drift. Requires `profiles:write`.", "tags": [ "Profiles" ], "parameters": [ { "$ref": "#/components/parameters/ProfileIdParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 120, "description": "New display name (1-120 chars)." }, "external_id": { "type": "string", "maxLength": 128, "nullable": true, "description": "Your own identifier for this profile; send null to clear it." } } }, "example": { "name": "Acme Corp (EU)", "external_id": "client-042-eu" } } } }, "responses": { "200": { "description": "Updated profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" }, "example": { "id": 128, "workspace_id": 128, "name": "Acme Corp (EU)", "external_id": "client-042-eu", "status": "active", "paused_for_billing": false, "created_at": "2026-07-26T09:41:22Z" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/profiles/{id}/accounts": { "get": { "summary": "List a profile's connected accounts", "description": "The social accounts the end-customer has connected to this profile. Requires the profiles:read scope.", "operationId": "listProfileAccounts", "tags": [ "Profiles" ], "parameters": [ { "$ref": "#/components/parameters/ProfileIdParam" } ], "responses": { "200": { "description": "Connected accounts", "content": { "application/json": { "schema": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "platform": { "type": "string" }, "account_id": { "type": "string" }, "account_name": { "type": "string" }, "account_username": { "type": "string" }, "connected_at": { "type": "string" } } } } } }, "example": { "accounts": [ { "id": 128, "platform": "twitter", "account_id": "ext_7f2c91", "account_name": "Acme Corp Main", "account_username": "example-account-username", "connected_at": "2026-07-26T09:41:22Z" } ] } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/profiles/{id}/pause": { "post": { "summary": "Pause a profile", "description": "Pause a profile: its workspace is suspended, delegated calls return 409, and its accounts stop counting toward monthly account billing. Requires the profiles:write scope.", "operationId": "pauseProfile", "tags": [ "Profiles" ], "parameters": [ { "$ref": "#/components/parameters/ProfileIdParam" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "status": { "type": "string", "example": "paused" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "ok": true, "status": "paused" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/profiles/{id}/resume": { "post": { "summary": "Resume a profile", "description": "Resume a paused profile. Requires the profiles:write scope.", "operationId": "resumeProfile", "tags": [ "Profiles" ], "parameters": [ { "$ref": "#/components/parameters/ProfileIdParam" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "status": { "type": "string", "example": "active" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "ok": true, "status": "active" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/profiles/{id}/connect-link": { "post": { "summary": "Create a hosted connect link", "description": "Mints a signed, single-use hosted page URL you forward to your end-customer. They open it with no login, pick platforms, and approve access; connected accounts land in this profile. The link dies for other browsers once opened. Requires the profiles:write scope.", "operationId": "createProfileConnectLink", "tags": [ "Profiles" ], "parameters": [ { "$ref": "#/components/parameters/ProfileIdParam" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "platforms": { "type": "array", "items": { "type": "string" }, "description": "Subset of platforms to offer (default: all 13)" }, "return_url": { "type": "string", "description": "Where the customer lands after each connect (default: back on the hosted page)" }, "ttl": { "type": "integer", "minimum": 300, "maximum": 604800, "description": "Link lifetime in seconds (default 86400)" } } } } } }, "responses": { "201": { "description": "Connect link", "content": { "application/json": { "schema": { "type": "object", "properties": { "connect_url": { "type": "string" }, "expires_at": { "type": "string" }, "platforms": { "type": "array", "items": { "type": "string" } } } }, "example": { "connect_url": "https://cdn.example.com/launch.jpg", "expires_at": "2026-07-26T09:41:22Z", "platforms": [ "twitter" ] } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Profile is paused" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/profiles/{id}/connect/{platform}": { "post": { "summary": "Get a raw connect URL for one platform", "description": "Per-platform OAuth connect URL targeting this profile, for developers building their own connect UI. Same mechanics as POST /social/connect/{platform}. Requires the profiles:write scope.", "operationId": "createProfileConnectUrl", "tags": [ "Profiles" ], "parameters": [ { "$ref": "#/components/parameters/ProfileIdParam" }, { "name": "platform", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Platform key (facebook, instagram, twitter, linkedin, youtube, tiktok, threads, bluesky, pinterest, reddit, snapchat, tumblr, gmb)" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "return_url": { "type": "string" } } } } } }, "responses": { "201": { "description": "Connect URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "type": "string" }, "connect_url": { "type": "string" }, "expires_at": { "type": "string" } } }, "example": { "platform": "twitter", "connect_url": "https://cdn.example.com/launch.jpg", "expires_at": "2026-07-26T09:41:22Z" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Profile is paused" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/me/account-billing": { "get": { "summary": "Account billing summary", "description": "Live count of billable connected accounts across your profiles, the price bands, the estimated next monthly charge, and recent billing history. Accounts are billed per calendar month from your API wallet: \\$6 each for accounts 1-10, \\$3 for 11-100, \\$1 from 101 up, snapshotted on the 1st (UTC). Requires the profiles:read scope.", "operationId": "getAccountBilling", "tags": [ "Profiles" ], "responses": { "200": { "description": "Billing summary", "content": { "application/json": { "schema": { "type": "object", "properties": { "active_accounts": { "type": "integer" }, "currency": { "type": "string" }, "bands": { "type": "array", "items": { "type": "object", "properties": { "up_to": { "type": "integer", "nullable": true }, "price": { "type": "number" } } } }, "estimated_next_charge": { "type": "number", "nullable": true }, "next_billing_date": { "type": "string" }, "history": { "type": "array", "items": { "type": "object", "properties": { "period": { "type": "string" }, "accounts": { "type": "integer" }, "amount": { "type": "number" }, "status": { "type": "string" }, "charged_at": { "type": "string", "nullable": true } } } } } }, "example": { "active_accounts": 1, "currency": "USD", "bands": [ { "up_to": 1, "price": 0.005 } ], "estimated_next_charge": 1.5, "next_billing_date": "2026-07-26", "history": [ { "period": "example-period", "accounts": 1, "amount": 1.5, "status": "published", "charged_at": "2026-07-26T09:41:22Z" } ] } } } } } } }, "/webhooks/logs": { "get": { "summary": "List webhook delivery logs", "operationId": "listWebhookLogs", "tags": [ "Webhooks" ], "description": "Paginated log of webhook delivery attempts across your endpoints, newest first (90-day retention). Each row carries the full delivery envelope, the destination's response code and a response-body excerpt, the attempt count, and the next retry time when pending. Requires scope `webhooks:read`. Not available under X-Profile-Id delegation - webhooks live on your developer workspace and receive profile events automatically (with profile_id attached).", "parameters": [ { "name": "webhook_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filter to one webhook." }, { "name": "event", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by event name (e.g. post.published)." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "delivered", "dead_letter" ] }, "description": "Filter by delivery status." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100 } } ], "responses": { "200": { "description": "Delivery log", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "deliveries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "webhook_id": { "type": "integer" }, "event": { "type": "string" }, "event_id": { "type": "string", "description": "The envelope's stable evt_ id (matches X-SmartlyQ-Event-Id)." }, "status": { "type": "string", "enum": [ "pending", "delivered", "dead_letter" ] }, "attempt": { "type": "integer" }, "response_code": { "type": "integer", "nullable": true }, "response_body": { "type": "string", "nullable": true, "description": "First 500 chars of the destination's response." }, "payload": { "type": "object", "nullable": true, "description": "The delivered envelope {id, event, created_at, data}." }, "created_at": { "type": "string", "format": "date-time" }, "delivered_at": { "type": "string", "format": "date-time", "nullable": true }, "next_retry_at": { "type": "string", "format": "date-time", "nullable": true } } } }, "pagination": { "type": "object", "properties": { "total": { "type": "integer" }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total_pages": { "type": "integer" } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "deliveries": [ { "id": 128, "webhook_id": 128, "event": "post.published", "event_id": "ext_7f2c91", "status": "pending", "attempt": 1, "response_code": 1, "response_body": "example-response-body", "payload": {}, "created_at": "2026-07-26T09:41:22Z", "delivered_at": "2026-07-26T09:41:22Z", "next_retry_at": "2026-07-26T09:41:22Z" } ], "pagination": { "total": 42, "page": 1, "per_page": 1, "total_pages": 3 } }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/webhooks/{id}/test": { "post": { "summary": "Send test webhook", "operationId": "testWebhook", "tags": [ "Webhooks" ], "description": "Synchronously sends a `webhook.test` delivery to the endpoint through the real signing pipeline (same headers and HMAC signature as production events) and returns the outcome. Works even when the endpoint is paused or failing. Test deliveries are never retried by the worker. Requires scope `webhooks:write`. Not available under X-Profile-Id delegation - webhooks live on your developer workspace and receive profile events automatically (with profile_id attached).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Webhook id." } ], "responses": { "200": { "description": "Test result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "delivered": { "type": "boolean", "description": "True when the endpoint answered 2xx." }, "event_id": { "type": "string" }, "delivery_id": { "type": "integer" }, "response_code": { "type": "integer", "nullable": true }, "response_body": { "type": "string", "nullable": true } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "delivered": true, "event_id": "evt_1a2b3c", "delivery_id": 9812, "response_code": 200, "response_body": "ok" }, "meta": { "request_id": "req_abc123" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/social/queues": { "get": { "summary": "List queues", "operationId": "listQueues", "tags": [ "Social" ], "description": "List the workspace's posting queues (recurring weekly slot schedules). Requires scope `social:read`.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "queues": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slots": { "type": "object", "description": "Weekly slot map: keys Mon..Sun, values arrays of 24h \"HH:MM\" strings, e.g. {\"Mon\": [\"09:00\", \"15:00\"], \"Thu\": [\"10:30\"]}. Max 50 slots per queue.", "propertyNames": { "enum": [ "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun" ] }, "additionalProperties": { "type": "array", "items": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" } } }, "timezone": { "type": "string", "description": "IANA timezone the slots are interpreted in (default UTC)." }, "is_active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "queues": [ { "id": 128, "name": "Acme Corp", "slots": {}, "timezone": "Europe/Athens", "is_active": true, "created_at": "2026-07-26T09:41:22Z", "updated_at": "2026-07-26T09:41:22Z" } ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "summary": "Create queue", "operationId": "createQueue", "tags": [ "Social" ], "description": "Create a posting queue. Posts join it via `POST /social/posts/schedule` with `queue_id`; each post takes the next open slot (FIFO). Max 20 queues per workspace. Requires scope `social:write`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "slots" ], "properties": { "name": { "type": "string", "maxLength": 100 }, "slots": { "type": "object", "description": "Weekly slot map: keys Mon..Sun, values arrays of 24h \"HH:MM\" strings, e.g. {\"Mon\": [\"09:00\", \"15:00\"], \"Thu\": [\"10:30\"]}. Max 50 slots per queue.", "propertyNames": { "enum": [ "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun" ] }, "additionalProperties": { "type": "array", "items": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" } } }, "timezone": { "type": "string", "description": "IANA timezone for the slots (default UTC)." }, "is_active": { "type": "boolean", "default": true } } }, "example": { "name": "Weekday mornings", "slots": { "Mon": [ "09:00" ], "Wed": [ "09:00" ], "Fri": [ "09:00", "15:00" ] }, "timezone": "Europe/Madrid" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slots": { "type": "object", "description": "Weekly slot map: keys Mon..Sun, values arrays of 24h \"HH:MM\" strings, e.g. {\"Mon\": [\"09:00\", \"15:00\"], \"Thu\": [\"10:30\"]}. Max 50 slots per queue.", "propertyNames": { "enum": [ "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun" ] }, "additionalProperties": { "type": "array", "items": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" } } }, "timezone": { "type": "string", "description": "IANA timezone the slots are interpreted in (default UTC)." }, "is_active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "id": 128, "name": "Acme Corp", "slots": {}, "timezone": "Europe/Athens", "is_active": true, "created_at": "2026-07-26T09:41:22Z", "updated_at": "2026-07-26T09:41:22Z" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/social/queues/{queue_id}": { "get": { "summary": "Get queue", "operationId": "getQueue", "tags": [ "Social" ], "description": "Fetch one queue, including its next open slot. Requires scope `social:read`.", "parameters": [ { "name": "queue_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Queue id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "allOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slots": { "type": "object", "description": "Weekly slot map: keys Mon..Sun, values arrays of 24h \"HH:MM\" strings, e.g. {\"Mon\": [\"09:00\", \"15:00\"], \"Thu\": [\"10:30\"]}. Max 50 slots per queue.", "propertyNames": { "enum": [ "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun" ] }, "additionalProperties": { "type": "array", "items": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" } } }, "timezone": { "type": "string", "description": "IANA timezone the slots are interpreted in (default UTC)." }, "is_active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, { "type": "object", "properties": { "next_slot": { "type": "string", "nullable": true, "description": "Next open slot, UTC 'Y-m-d H:i:s', or null when the queue has no open slots in the next 60 days." } } } ] }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "id": 128, "name": "Acme Corp", "slots": {}, "timezone": "Europe/Athens", "is_active": true, "created_at": "2026-07-26T09:41:22Z", "updated_at": "2026-07-26T09:41:22Z", "next_slot": "example-next-slot" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "summary": "Update queue", "operationId": "updateQueue", "tags": [ "Social" ], "description": "Update name, slots, timezone, or active state. Only supplied fields change; already-queued posts keep their resolved times. Requires scope `social:write`.", "parameters": [ { "name": "queue_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Queue id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Provide at least one field.", "properties": { "name": { "type": "string", "maxLength": 100 }, "slots": { "type": "object", "description": "Weekly slot map: keys Mon..Sun, values arrays of 24h \"HH:MM\" strings, e.g. {\"Mon\": [\"09:00\", \"15:00\"], \"Thu\": [\"10:30\"]}. Max 50 slots per queue.", "propertyNames": { "enum": [ "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun" ] }, "additionalProperties": { "type": "array", "items": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" } } }, "timezone": { "type": "string" }, "is_active": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slots": { "type": "object", "description": "Weekly slot map: keys Mon..Sun, values arrays of 24h \"HH:MM\" strings, e.g. {\"Mon\": [\"09:00\", \"15:00\"], \"Thu\": [\"10:30\"]}. Max 50 slots per queue.", "propertyNames": { "enum": [ "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun" ] }, "additionalProperties": { "type": "array", "items": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" } } }, "timezone": { "type": "string", "description": "IANA timezone the slots are interpreted in (default UTC)." }, "is_active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "id": 128, "name": "Acme Corp", "slots": {}, "timezone": "Europe/Athens", "is_active": true, "created_at": "2026-07-26T09:41:22Z", "updated_at": "2026-07-26T09:41:22Z" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "summary": "Delete queue", "operationId": "deleteQueue", "tags": [ "Social" ], "description": "Delete a queue. Posts already scheduled through it keep their resolved times. Requires scope `social:write`.", "parameters": [ { "name": "queue_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Queue id." } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "null" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": "example-data", "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/social/queues/{queue_id}/next-slot": { "get": { "summary": "Get next open slot", "operationId": "getQueueNextSlot", "tags": [ "Social" ], "description": "The next unoccupied slot in the queue (UTC). For preview only - to actually schedule into the queue, pass `queue_id` to `POST /social/posts/schedule` (that call resolves and occupies the slot atomically). Requires scope `social:read`.", "parameters": [ { "name": "queue_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Queue id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "queue_id": { "type": "integer" }, "next_slot": { "type": "string", "nullable": true, "description": "UTC 'Y-m-d H:i:s', or null when full for the next 60 days." }, "timezone": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "queue_id": 128, "next_slot": "example-next-slot", "timezone": "Europe/Athens" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/social/queues/{queue_id}/preview": { "get": { "summary": "Preview upcoming slots", "operationId": "previewQueueSlots", "tags": [ "Social" ], "description": "The next N open slots (default 10, max 50), continuing the same walk `next-slot` uses. Requires scope `social:read`.", "parameters": [ { "name": "queue_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Queue id." }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer", "default": 10, "maximum": 50 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "queue_id": { "type": "integer" }, "count": { "type": "integer" }, "slots": { "type": "array", "items": { "type": "string" }, "description": "UTC 'Y-m-d H:i:s' values, ascending." }, "timezone": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "queue_id": 128, "count": 1, "slots": [ "example-slot" ], "timezone": "Europe/Athens" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/social/posts/{post_id}/unpublish": { "post": { "summary": "Unpublish post", "operationId": "unpublishPost", "tags": [ "Social" ], "description": "Delete a PUBLISHED post from its native platforms while keeping the SmartlyQ record - its status flips to `unpublished`. Optional `platforms` restricts which networks are removed. Supported for deletion: Threads, Facebook, LinkedIn, YouTube, X/Twitter, Pinterest, Tumblr, Bluesky, Google Business (Instagram, TikTok and Snapchat expose no delete API - those targets are reported as skipped). If any attempted native delete fails, nothing changes on our side and per-platform errors are returned so you can retry. Drafts and scheduled posts should use `DELETE /social/posts/{post_id}` instead. Requires scope `social:write`.", "parameters": [ { "name": "post_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Post id." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "platforms": { "type": "array", "items": { "type": "string" }, "description": "Restrict native deletion to these platforms. Omit to remove from every platform the post published to." } } } } } }, "responses": { "200": { "description": "Unpublished", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "post_id": { "type": "integer" }, "status": { "type": "string", "enum": [ "unpublished" ] }, "platforms": { "type": "object", "additionalProperties": true, "description": "Per-platform deletion results." } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "post_id": 128, "status": "unpublished", "platforms": {} }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "One or more native deletes failed; the post is unchanged. The error details carry per-platform results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_DELETE_FAILED" ] }, "message": { "type": "string" }, "details": { "type": "object" } } } } } } } } } } }, "/social/validate/post": { "post": { "summary": "Validate post content", "operationId": "validatePost", "tags": [ "Social" ], "description": "Dry-run the same declarative checks the create path uses, WITHOUT creating anything: per-platform caption limits (each limit grounded in the platform handler or the platform's documented maximum), required-media rules (e.g. Instagram), and media extension screening. Free and unbilled. Platforms with no honestly-documented ceiling (Snapchat stories carry no caption; Tumblr documents no body cap) report limit: null. Requires scope `social:read`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "platforms" ], "properties": { "content": { "type": "string", "description": "Post text to check." }, "platforms": { "type": "array", "items": { "type": "string" }, "description": "Target platforms, e.g. [\"twitter\", \"instagram\"]." }, "media_urls": { "type": "array", "items": { "type": "string" }, "description": "Media URLs the post would carry (used for required-media and extension checks)." } } }, "example": { "content": "Launching today! 🚀", "platforms": [ "twitter", "instagram", "linkedin" ], "media_urls": [ "https://cdn.example.com/launch.jpg" ] } } } }, "responses": { "200": { "description": "Validation report", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Human-readable, actionable problems (empty when valid)." }, "platforms": { "type": "object", "additionalProperties": { "type": "object", "properties": { "characters": { "type": "integer" }, "limit": { "type": "integer", "nullable": true, "description": "Caption limit, or null when the platform has no documented ceiling." }, "within_limit": { "type": "boolean" }, "requires_media": { "type": "boolean" }, "media_ok": { "type": "boolean" } } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "valid": true, "errors": [ "example-error" ], "platforms": {} }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/social/validate/media": { "post": { "summary": "Validate media URL", "operationId": "validateMedia", "tags": [ "Social" ], "description": "Checks that a media URL is publicly reachable and reports its content type, byte size, and detected kind (image/video). SSRF-guarded: private and internal hosts are rejected. Uses a HEAD request with a 1-byte ranged-GET fallback for CDNs that refuse HEAD. Free and unbilled. Requires scope `social:read`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Public http(s) media URL." } } }, "example": { "url": "https://cdn.example.com/launch.jpg" } } } }, "responses": { "200": { "description": "Media check", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "url": { "type": "string" }, "reachable": { "type": "boolean" }, "http_code": { "type": "integer" }, "content_type": { "type": "string", "nullable": true }, "size_bytes": { "type": "integer", "nullable": true }, "type": { "type": "string", "enum": [ "image", "video", "unknown" ] } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "url": "https://example.com/launch", "reachable": true, "http_code": 200, "content_type": "example-content-type", "size_bytes": 482113, "type": "image" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/social/posts/{post_id}/recycle": { "delete": { "summary": "Stop recycling", "operationId": "stopPostRecycle", "tags": [ "Social" ], "description": "Stops an evergreen recycling chain: clears the recycle config on every post in the chain and cancels any not-yet-published auto-spawned occurrences back to draft. Works on any post in the chain (original or an occurrence). Unbilled. Requires scope `social:write`.", "parameters": [ { "name": "post_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Any post id in the recycling chain." } ], "responses": { "200": { "description": "Chain stopped", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "stopped": { "type": "boolean" }, "cancelled_occurrences": { "type": "integer", "description": "Scheduled future occurrences moved back to draft." } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "stopped": true, "cancelled_occurrences": 1 }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Post is not part of a recycling chain", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "NOT_RECYCLING" ] }, "message": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } } } } } }, "/social/posts/bulk": { "post": { "summary": "Bulk schedule posts", "operationId": "bulkSchedulePosts", "tags": [ "Social" ], "description": "Schedule up to 50 posts in one call, from a JSON `posts` array or an inline `csv` string. Billed one post unit per row x platform. Any structural problem (missing fields, bad dates, in-batch duplicate rows) rejects the WHOLE batch with 422 before anything is created - and the charge is refunded. After that gate, row-level failures (e.g. a disconnected account, a 24h duplicate) are reported per row in the 201 response. Run the free dry-run first: POST /social/posts/bulk/validate. Requires scope `social:write`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "posts": { "type": "array", "maxItems": 50, "description": "Up to 50 posts. Each row needs content, platforms, account_ids and scheduled_time.", "items": { "type": "object", "required": [ "content", "platforms", "account_ids", "scheduled_time" ], "properties": { "content": { "type": "string" }, "platforms": { "type": "array", "items": { "type": "string" } }, "account_ids": { "type": "array", "items": { "type": "integer" } }, "scheduled_time": { "type": "string", "description": "When to publish (interpreted in `timezone`, default UTC)." }, "timezone": { "type": "string", "description": "Optional per-row IANA timezone override." }, "media_urls": { "type": "array", "items": { "type": "string" } }, "link": { "type": "string" }, "platform_options": { "type": "object", "description": "Per-platform composer options - the same payload the web composer stores; publish handlers read it as-is (unknown keys are ignored, max 20KB). Keyed by platform, e.g. {\"tiktok\": {\"privacy_level\": \"SELF_ONLY\"}, \"instagram\": {\"content\": \"IG-specific caption\"}, \"_thumbnail\": {\"timestamp_ms\": 3000}}. Common keys: per-platform `content` override; tiktok privacy/duet/stitch options; `_thumbnail` custom video cover.", "example": { "tiktok": { "privacy_level": "PUBLIC_TO_EVERYONE" }, "instagram": { "content": "IG-flavored caption ✨" } } } } } }, "csv": { "type": "string", "description": "Alternative to posts: inline CSV with a header line. Columns: content, platforms, account_ids, scheduled_time, media_urls, link (list cells split on | or ,). Provide posts OR csv, not both." }, "timezone": { "type": "string", "description": "Default timezone for rows without their own (IANA name, default UTC)." }, "allow_duplicates": { "type": "boolean", "description": "Skip the 24h duplicate-content guard for this batch." } } }, "example": { "posts": [ { "content": "Big news Monday!", "platforms": [ "twitter", "linkedin" ], "account_ids": [ 12, 15 ], "scheduled_time": "2026-08-03 09:00:00" }, { "content": "Behind the scenes 🎬", "platforms": [ "instagram" ], "account_ids": [ 18 ], "scheduled_time": "2026-08-04 17:30:00", "media_urls": [ "https://cdn.example.com/bts.jpg" ] } ], "timezone": "Europe/Athens" } } } }, "responses": { "201": { "description": "Batch processed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "created": { "type": "integer" }, "failed": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "row": { "type": "integer" }, "post_id": { "type": "integer", "description": "Present on success." }, "status": { "type": "string" }, "scheduled_time": { "type": "string" }, "error": { "type": "string", "description": "Present on row failure (e.g. DUPLICATE_CONTENT)." }, "message": { "type": "string" } } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "created": 8, "failed": 0, "results": [ { "row": 1, "post_id": 128, "status": "published", "scheduled_time": "2026-08-03 09:00:00", "error": "example-error", "message": "Done." } ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientBalance" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/social/posts/bulk/validate": { "post": { "summary": "Validate a bulk batch", "operationId": "validateBulkBatch", "tags": [ "Social" ], "description": "Free dry-run of the same batch body as POST /social/posts/bulk: per-row structural checks, per-platform caption/media limits, and the 24h duplicate-content check. Nothing is created or billed. Requires scope `social:read`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "posts": { "type": "array", "maxItems": 50, "description": "Up to 50 posts. Each row needs content, platforms, account_ids and scheduled_time.", "items": { "type": "object", "required": [ "content", "platforms", "account_ids", "scheduled_time" ], "properties": { "content": { "type": "string" }, "platforms": { "type": "array", "items": { "type": "string" } }, "account_ids": { "type": "array", "items": { "type": "integer" } }, "scheduled_time": { "type": "string", "description": "When to publish (interpreted in `timezone`, default UTC)." }, "timezone": { "type": "string", "description": "Optional per-row IANA timezone override." }, "media_urls": { "type": "array", "items": { "type": "string" } }, "link": { "type": "string" }, "platform_options": { "type": "object", "description": "Per-platform composer options - the same payload the web composer stores; publish handlers read it as-is (unknown keys are ignored, max 20KB). Keyed by platform, e.g. {\"tiktok\": {\"privacy_level\": \"SELF_ONLY\"}, \"instagram\": {\"content\": \"IG-specific caption\"}, \"_thumbnail\": {\"timestamp_ms\": 3000}}. Common keys: per-platform `content` override; tiktok privacy/duet/stitch options; `_thumbnail` custom video cover.", "example": { "tiktok": { "privacy_level": "PUBLIC_TO_EVERYONE" }, "instagram": { "content": "IG-flavored caption ✨" } } } } } }, "csv": { "type": "string", "description": "Alternative to posts: inline CSV with a header line. Columns: content, platforms, account_ids, scheduled_time, media_urls, link (list cells split on | or ,). Provide posts OR csv, not both." }, "timezone": { "type": "string", "description": "Default timezone for rows without their own (IANA name, default UTC)." }, "allow_duplicates": { "type": "boolean", "description": "Skip the 24h duplicate-content guard for this batch." } } } } } }, "responses": { "200": { "description": "Batch report", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "valid": { "type": "boolean" }, "rows": { "type": "integer" }, "report": { "type": "array", "items": { "type": "object", "properties": { "row": { "type": "integer" }, "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string" } } } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "valid": true, "rows": 1, "report": [ { "row": 1, "valid": true, "errors": [ "example-error" ] } ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/social/accounts/health": { "get": { "summary": "Bulk account health", "operationId": "bulkAccountHealth", "tags": [ "Social" ], "description": "Health of every connected account in one call: healthy / expiring (token within 7 days) / expired / paused tallies plus per-account status. Same fields as the per-account health endpoint. Requires scope `social:read`.", "responses": { "200": { "description": "Health summary", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "healthy": { "type": "integer" }, "expiring": { "type": "integer" }, "expired": { "type": "integer" }, "paused": { "type": "integer" }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "platform": { "type": "string" }, "account_name": { "type": "string" }, "is_active": { "type": "boolean" }, "status": { "type": "string" }, "token_expired": { "type": "boolean" }, "validity_days": { "type": "integer" } } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "healthy": 1, "expiring": 1, "expired": 1, "paused": 1, "accounts": [ { "id": 128, "platform": "twitter", "account_name": "Acme Corp Main", "is_active": true, "status": "published", "token_expired": true, "validity_days": 30 } ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/social/accounts/follower-stats": { "get": { "summary": "Follower stats", "operationId": "accountFollowerStats", "tags": [ "Social" ], "description": "Daily follower history and growth per account, from the analytics snapshots the platform collects. Requires scope `social:read`.", "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "default": 30, "minimum": 1, "maximum": 365 }, "description": "History window." }, { "name": "account_id", "in": "query", "schema": { "type": "integer" }, "description": "Limit to one account." } ], "responses": { "200": { "description": "Follower stats", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "days": { "type": "integer" }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "type": "integer" }, "platform": { "type": "string" }, "account_name": { "type": "string" }, "followers": { "type": "integer", "description": "Latest snapshot." }, "growth": { "type": "integer", "description": "Delta over the window." }, "growth_pct": { "type": "number", "nullable": true }, "history": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "followers": { "type": "integer" }, "new_followers": { "type": "integer" } } } } } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "days": 30, "accounts": [ { "account_id": 128, "platform": "twitter", "account_name": "Acme Corp Main", "followers": 10432, "growth": 236, "growth_pct": 12.5, "history": [ { "date": "2026-07-26", "followers": 10432, "new_followers": 10432 } ] } ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/social/accounts/{account_id}/tiktok/creator-info": { "get": { "summary": "TikTok creator info", "operationId": "tiktokCreatorInfo", "tags": [ "Social" ], "description": "Live TikTok creator settings for a connected TikTok account: available privacy levels, whether comments/duet/stitch are disabled, and the account's maximum video duration. TikTok requires surfacing these before showing post options. Requires scope `social:read`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Creator info", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "account_id": { "type": "integer" }, "creator_username": { "type": "string" }, "creator_nickname": { "type": "string" }, "privacy_level_options": { "type": "array", "items": { "type": "string" } }, "comment_disabled": { "type": "boolean" }, "duet_disabled": { "type": "boolean" }, "stitch_disabled": { "type": "boolean" }, "max_video_post_duration_sec": { "type": "integer" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "account_id": 128, "creator_username": "example-creator-username", "creator_nickname": "example-creator-nickname", "privacy_level_options": [ "example-privacy-level-option" ], "comment_disabled": true, "duet_disabled": true, "stitch_disabled": true, "max_video_post_duration_sec": 1 }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "TikTok rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } } } } } }, "/social/accounts/{account_id}/move": { "post": { "summary": "Move account to profile", "operationId": "moveSocialAccount", "tags": [ "Social" ], "description": "Move a connected account between your developer workspace and one of your profiles (or profile to profile). Pass profile_id 0 to move it back to the developer workspace. Must be called WITHOUT X-Profile-Id; requires scopes `social:write` AND `profiles:manage`. Rejected with 409 while the account has scheduled or in-flight posts.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "profile_id" ], "properties": { "profile_id": { "type": "integer", "description": "Target profile id; 0 = developer workspace." } } } } } }, "responses": { "200": { "description": "Moved", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "platform": { "type": "string" }, "account_name": { "type": "string" }, "profile_id": { "type": "integer" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "id": 128, "platform": "twitter", "account_name": "Acme Corp Main", "profile_id": 128 }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/social/account-groups": { "get": { "summary": "List account groups", "operationId": "listAccountGroups", "tags": [ "Social" ], "description": "Named sets of connected accounts, so integrations can address a whole client or brand with one id. Requires scope `social:read`.", "responses": { "200": { "description": "Groups", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "account_ids": { "type": "array", "items": { "type": "integer" } }, "created_at": { "type": "string" }, "updated_at": { "type": "string", "nullable": true } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": [ { "id": 128, "name": "Acme Corp", "account_ids": [ 128 ], "created_at": "2026-07-26T09:41:22Z", "updated_at": "2026-07-26T09:41:22Z" } ], "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "summary": "Create account group", "operationId": "createAccountGroup", "tags": [ "Social" ], "description": "Create a group (max 50 per workspace, 100 accounts per group). Every account id must be a connected account of this workspace. Requires scope `social:write`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 120 }, "account_ids": { "type": "array", "maxItems": 100, "items": { "type": "integer" }, "description": "Connected account ids of this workspace (validated on every write)." } }, "required": [ "name", "account_ids" ] }, "example": { "name": "Acme Corp accounts", "account_ids": [ 12, 15, 18 ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "account_ids": { "type": "array", "items": { "type": "integer" } }, "created_at": { "type": "string" }, "updated_at": { "type": "string", "nullable": true } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "id": 128, "name": "Acme Corp", "account_ids": [ 128 ], "created_at": "2026-07-26T09:41:22Z", "updated_at": "2026-07-26T09:41:22Z" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/social/account-groups/{group_id}": { "get": { "summary": "Get account group", "operationId": "getAccountGroup", "tags": [ "Social" ], "parameters": [ { "name": "group_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Group", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "account_ids": { "type": "array", "items": { "type": "integer" } }, "created_at": { "type": "string" }, "updated_at": { "type": "string", "nullable": true } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "id": 128, "name": "Acme Corp", "account_ids": [ 128 ], "created_at": "2026-07-26T09:41:22Z", "updated_at": "2026-07-26T09:41:22Z" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "summary": "Update account group", "operationId": "updateAccountGroup", "tags": [ "Social" ], "description": "Update the name and/or replace the member list. Requires scope `social:write`.", "parameters": [ { "name": "group_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 120 }, "account_ids": { "type": "array", "maxItems": 100, "items": { "type": "integer" }, "description": "Connected account ids of this workspace (validated on every write)." } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "account_ids": { "type": "array", "items": { "type": "integer" } }, "created_at": { "type": "string" }, "updated_at": { "type": "string", "nullable": true } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "id": 128, "name": "Acme Corp", "account_ids": [ 128 ], "created_at": "2026-07-26T09:41:22Z", "updated_at": "2026-07-26T09:41:22Z" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "summary": "Delete account group", "operationId": "deleteAccountGroup", "tags": [ "Social" ], "description": "Deletes the group only - the accounts stay connected. Requires scope `social:write`.", "parameters": [ { "name": "group_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": {}, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/analytics/daily-metrics": { "get": { "summary": "Daily metrics", "operationId": "analyticsDailyMetrics", "tags": [ "Analytics" ], "description": "Per-day aggregates across all accounts (impressions, reach, engagements, follower deltas, posts published) plus a per-platform breakdown. Computed from stored snapshots - fast and unbilled. Requires scope `analytics:read`.", "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "default": 30, "minimum": 1, "maximum": 365 }, "description": "Window in days." } ], "responses": { "200": { "description": "Daily metrics", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "days": { "type": "integer" }, "daily": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "impressions": { "type": "integer" }, "reach": { "type": "integer" }, "engagements": { "type": "integer" }, "new_followers": { "type": "integer" }, "followers": { "type": "integer" }, "posts": { "type": "integer" } } } }, "platforms": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "impressions": { "type": "integer" }, "reach": { "type": "integer" }, "engagements": { "type": "integer" }, "new_followers": { "type": "integer" } } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "days": 30, "daily": [ { "date": "2026-07-26", "impressions": 1, "reach": 1, "engagements": 1, "new_followers": 10432, "followers": 10432, "posts": 1 } ], "platforms": [ { "platform": "twitter", "impressions": 1, "reach": 1, "engagements": 1, "new_followers": 10432 } ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/analytics/best-time": { "get": { "summary": "Best time to post", "operationId": "analyticsBestTime", "tags": [ "Analytics" ], "description": "When your audience actually engages: a 7x24 heatmap of average engagement per published post by weekday and hour (in your timezone), plus the top 5 slots. Requires scope `analytics:read`.", "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "default": 90, "minimum": 7, "maximum": 365 }, "description": "Window in days." }, { "name": "timezone", "in": "query", "schema": { "type": "string", "default": "UTC" }, "description": "IANA timezone for the buckets." } ], "responses": { "200": { "description": "Best-time report", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "days": { "type": "integer" }, "timezone": { "type": "string" }, "sample": { "type": "integer", "description": "Posts in the sample." }, "best_slots": { "type": "array", "items": { "type": "object", "properties": { "weekday": { "type": "string" }, "hour": { "type": "integer" }, "avg_engagements": { "type": "number" }, "posts": { "type": "integer" } } } }, "heatmap": { "type": "object", "description": "weekday -> hour -> {avg_engagements, posts}" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "days": 30, "timezone": "Europe/Athens", "sample": 64, "best_slots": [ { "weekday": "example-weekday", "hour": 9, "avg_engagements": 1.5, "posts": 1 } ], "heatmap": {} }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/analytics/content-decay": { "get": { "summary": "Content decay", "operationId": "analyticsContentDecay", "tags": [ "Analytics" ], "description": "How long a post keeps working: the average share of a post's final engagement reached by each age-day (0-13), across posts published in the window. Requires scope `analytics:read`.", "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "default": 90, "minimum": 14, "maximum": 365 }, "description": "Window in days." } ], "responses": { "200": { "description": "Decay curve", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "days": { "type": "integer" }, "posts": { "type": "integer" }, "curve": { "type": "array", "items": { "type": "object", "properties": { "age_days": { "type": "integer" }, "avg_share_of_final": { "type": "number", "nullable": true }, "sample": { "type": "integer" } } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "days": 30, "posts": 1, "curve": [ { "age_days": 30, "avg_share_of_final": 12.5, "sample": 64 } ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/analytics/posting-frequency": { "get": { "summary": "Posting frequency vs engagement", "operationId": "analyticsPostingFrequency", "tags": [ "Analytics" ], "description": "Per ISO week: how many posts you published and what they averaged in engagement - the data behind 'are we posting too much or too little'. Requires scope `analytics:read`.", "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "default": 90, "minimum": 7, "maximum": 365 }, "description": "Window in days." } ], "responses": { "200": { "description": "Frequency report", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "days": { "type": "integer" }, "weeks": { "type": "array", "items": { "type": "object", "properties": { "week": { "type": "string", "example": "2026-W29" }, "posts": { "type": "integer" }, "total_engagements": { "type": "integer" }, "avg_engagements_per_post": { "type": "number" } } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/analytics/posts/{post_id}/timeline": { "get": { "summary": "Post metric timeline", "operationId": "analyticsPostTimeline", "tags": [ "Analytics" ], "description": "Every metric snapshot collected for one post, per platform, oldest first - impressions, reach, engagements, likes, comments, shares, saves, clicks, video views over time. Requires scope `analytics:read`.", "parameters": [ { "name": "post_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Timeline", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "post_id": { "type": "integer" }, "status": { "type": "string" }, "published_at": { "type": "string", "nullable": true }, "platforms": { "type": "object", "description": "platform -> array of snapshots" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "post_id": 128, "status": "published", "published_at": "2026-07-26T09:41:22Z", "platforms": {} }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/analytics/inbox/volume": { "get": { "summary": "Inbox volume", "operationId": "inboxVolume", "tags": [ "Analytics" ], "description": "Daily incoming/outgoing message counts plus new conversations started, across the social inbox. Requires scope `analytics:read`.", "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "default": 30, "minimum": 1, "maximum": 365 }, "description": "Window in days." } ], "responses": { "200": { "description": "Volume", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "days": { "type": "integer" }, "daily": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "incoming": { "type": "integer" }, "outgoing": { "type": "integer" }, "new_conversations": { "type": "integer" } } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "days": 30, "daily": [ { "date": "2026-07-26", "incoming": 34, "outgoing": 29, "new_conversations": 1 } ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/analytics/inbox/heatmap": { "get": { "summary": "Inbox heatmap", "operationId": "inboxHeatmap", "tags": [ "Analytics" ], "description": "Incoming messages bucketed by weekday and hour (in your timezone) - when your audience actually writes to you. Requires scope `analytics:read`.", "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "default": 30, "minimum": 1, "maximum": 365 }, "description": "Window in days." }, { "name": "timezone", "in": "query", "schema": { "type": "string", "default": "UTC" } } ], "responses": { "200": { "description": "Heatmap", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "days": { "type": "integer" }, "timezone": { "type": "string" }, "sample": { "type": "integer" }, "heatmap": { "type": "object", "description": "weekday -> array of 24 hourly counts" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "days": 30, "timezone": "Europe/Athens", "sample": 64, "heatmap": {} }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/analytics/inbox/source-breakdown": { "get": { "summary": "Inbox source breakdown", "operationId": "inboxSourceBreakdown", "tags": [ "Analytics" ], "description": "Active conversations and message volume per platform. Requires scope `analytics:read`.", "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "default": 30, "minimum": 1, "maximum": 365 }, "description": "Window in days." } ], "responses": { "200": { "description": "Breakdown", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "days": { "type": "integer" }, "platforms": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "conversations": { "type": "integer" }, "incoming": { "type": "integer" }, "outgoing": { "type": "integer" } } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "days": 30, "platforms": [ { "platform": "twitter", "conversations": 1, "incoming": 34, "outgoing": 29 } ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/analytics/inbox/response-time": { "get": { "summary": "Inbox response time", "operationId": "inboxResponseTime", "tags": [ "Analytics" ], "description": "How fast you answer: for every incoming message answered by a later reply in the same conversation, the wait - average, median, and a histogram (under_15m, 15m_1h, 1h_4h, 4h_24h, over_24h). Requires scope `analytics:read`.", "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "default": 30, "minimum": 1, "maximum": 365 }, "description": "Window in days." } ], "responses": { "200": { "description": "Response times", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "days": { "type": "integer" }, "answered": { "type": "integer" }, "avg_response_seconds": { "type": "integer", "nullable": true }, "median_response_seconds": { "type": "integer", "nullable": true }, "histogram": { "type": "object", "properties": { "under_15m": { "type": "integer" }, "15m_1h": { "type": "integer" }, "1h_4h": { "type": "integer" }, "4h_24h": { "type": "integer" }, "over_24h": { "type": "integer" } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "days": 30, "answered": 57, "avg_response_seconds": 780, "median_response_seconds": 540, "histogram": { "under_15m": 1, "15m_1h": 1, "1h_4h": 1, "4h_24h": 1, "over_24h": 1 } }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/analytics/inbox/top-accounts": { "get": { "summary": "Inbox top accounts", "operationId": "inboxTopAccounts", "tags": [ "Analytics" ], "description": "Your busiest connected accounts by incoming messages. Requires scope `analytics:read`.", "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "default": 30, "minimum": 1, "maximum": 365 }, "description": "Window in days." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10, "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "Top accounts", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "days": { "type": "integer" }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "type": "integer" }, "platform": { "type": "string" }, "account_name": { "type": "string", "nullable": true }, "conversations": { "type": "integer" }, "incoming": { "type": "integer" } } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "days": 30, "accounts": [ { "account_id": 128, "platform": "twitter", "account_name": "Acme Corp Main", "conversations": 1, "incoming": 34 } ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/reviews": { "get": { "summary": "List reviews", "operationId": "listReviews", "tags": [ "Reviews" ], "description": "Google Business reviews synced into SmartlyQ's Reputation Management, newest first. Filter by rating, reply status, or account. Requires scope `social:read`.", "parameters": [ { "name": "account_id", "in": "query", "schema": { "type": "integer" }, "description": "Limit to one connected Google Business account." }, { "name": "rating", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 5 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "replied" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } } ], "responses": { "200": { "description": "Reviews", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "account_id": { "type": "integer" }, "author_name": { "type": "string" }, "author_photo": { "type": "string", "nullable": true }, "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "comment": { "type": "string", "nullable": true }, "created_at": { "type": "string", "nullable": true }, "reply_comment": { "type": "string", "nullable": true }, "reply_at": { "type": "string", "nullable": true }, "reply_source": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "pending", "replied" ] } } } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": [ { "id": 128, "account_id": 128, "author_name": "Jane Cooper", "author_photo": "example-author-photo", "rating": 5, "comment": "Great service, highly recommend!", "created_at": "2026-07-26T09:41:22Z", "reply_comment": "Thank you for the kind words!", "reply_at": "2026-07-26T09:41:22Z", "reply_source": "manual", "status": "pending" } ], "pagination": { "page": 1, "per_page": 1, "total": 42, "pages": 1 }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/reviews/{review_id}/reply": { "post": { "summary": "Reply to review", "operationId": "replyToReview", "tags": [ "Reviews" ], "description": "Publishes a reply to the review on Google Business. Requires scope `social:write`.", "parameters": [ { "name": "review_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "comment" ], "properties": { "comment": { "type": "string", "maxLength": 4000 } } }, "example": { "comment": "Thank you for the kind words! We look forward to seeing you again." } } } }, "responses": { "200": { "description": "Replied", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "replied": { "type": "boolean" }, "review_id": { "type": "integer" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "replied": true, "review_id": 128 }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Google rejected the reply", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } } } } }, "delete": { "summary": "Delete review reply", "operationId": "deleteReviewReply", "tags": [ "Reviews" ], "description": "Removes the business reply from the review on Google Business and clears it in SmartlyQ (status returns to pending). Requires scope `social:write`.", "parameters": [ { "name": "review_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Reply deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": {}, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "502": { "description": "Platform rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": false, "error": { "code": "PLATFORM_ERROR", "message": "The platform rejected the request." }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } } }, "/reviews/sync": { "post": { "summary": "Sync reviews", "operationId": "syncReviews", "tags": [ "Reviews" ], "description": "Pulls fresh reviews from Google Business on demand - one account (account_id) or every connected GBP account in the workspace. Requires scope `social:write`.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "account_id": { "type": "integer", "description": "Optional: sync only this connected account." } } } } } }, "responses": { "200": { "description": "Synced", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "synced": { "type": "integer", "description": "Reviews inserted or updated." } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "synced": 1 }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/social/conversations/{conversation_id}": { "get": { "summary": "Get conversation", "operationId": "getConversation", "tags": [ "Social" ], "description": "Conversation detail plus incoming/outgoing message counts. Requires scope `social:read`.", "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Conversation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "platform": { "type": "string" }, "account_id": { "type": "integer" }, "participant_name": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "open", "archived" ] }, "unread_count": { "type": "integer" }, "snippet": { "type": "string", "nullable": true }, "incoming": { "type": "integer" }, "outgoing": { "type": "integer" }, "created_at": { "type": "string", "nullable": true }, "last_message_at": { "type": "string", "nullable": true } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "id": 128, "platform": "twitter", "account_id": 128, "participant_name": "Jane Cooper", "status": "open", "unread_count": 2, "snippet": "Thanks, that fixed it!", "incoming": 34, "outgoing": 29, "created_at": "2026-07-26T09:41:22Z", "last_message_at": "2026-07-26T09:41:22Z" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "summary": "Archive / reopen conversation", "operationId": "updateConversation", "tags": [ "Social" ], "description": "Set the conversation status to archived or open. Requires scope `social:write`.", "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "open", "archived" ] } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "id": 128, "status": "published" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/social/conversations/search": { "get": { "summary": "Search conversations", "operationId": "searchConversations", "tags": [ "Social" ], "description": "Full-inbox search across participant names and message content; each hit includes the latest matching message. Requires scope `social:read`.", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 50 } } ], "responses": { "200": { "description": "Matches", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "platform": { "type": "string" }, "account_id": { "type": "integer" }, "participant_name": { "type": "string", "nullable": true }, "status": { "type": "string" }, "snippet": { "type": "string", "nullable": true }, "matched_message": { "type": "string", "nullable": true }, "last_message_at": { "type": "string", "nullable": true } } } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": [ { "id": 128, "platform": "twitter", "account_id": 128, "participant_name": "Jane Cooper", "status": "published", "snippet": "Thanks, that fixed it!", "matched_message": "Can you send the invoice again?", "last_message_at": "2026-07-26T09:41:22Z" } ], "pagination": { "page": 1, "per_page": 1, "total": 42, "pages": 1 }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/analytics/inbox/conversations": { "get": { "summary": "Inbox conversation stats", "operationId": "inboxConversations", "tags": [ "Analytics" ], "description": "Per-conversation message volume for the window, busiest first. Requires scope `analytics:read`.", "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "default": 30, "minimum": 1, "maximum": 365 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 50 } } ], "responses": { "200": { "description": "Stats", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "days": { "type": "integer" }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "conversations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "platform": { "type": "string" }, "account_id": { "type": "integer" }, "participant_name": { "type": "string", "nullable": true }, "status": { "type": "string" }, "incoming": { "type": "integer" }, "outgoing": { "type": "integer" }, "created_at": { "type": "string", "nullable": true }, "last_message_at": { "type": "string", "nullable": true } } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "days": 30, "page": 1, "per_page": 1, "conversations": [ { "id": 128, "platform": "twitter", "account_id": 128, "participant_name": "Jane Cooper", "status": "published", "incoming": 34, "outgoing": 29, "created_at": "2026-07-26T09:41:22Z", "last_message_at": "2026-07-26T09:41:22Z" } ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/analytics/inbox/conversations/{conversation_id}": { "get": { "summary": "Conversation analytics", "operationId": "inboxConversationDetail", "tags": [ "Analytics" ], "description": "One conversation's full stats: message counts and response times (average, median). Requires scope `analytics:read`.", "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Conversation analytics", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "platform": { "type": "string" }, "account_id": { "type": "integer" }, "participant_name": { "type": "string", "nullable": true }, "status": { "type": "string" }, "incoming": { "type": "integer" }, "outgoing": { "type": "integer" }, "answered": { "type": "integer" }, "avg_response_seconds": { "type": "integer", "nullable": true }, "median_response_seconds": { "type": "integer", "nullable": true }, "created_at": { "type": "string", "nullable": true }, "last_message_at": { "type": "string", "nullable": true } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "id": 128, "platform": "twitter", "account_id": 128, "participant_name": "Jane Cooper", "status": "published", "incoming": 34, "outgoing": 29, "answered": 57, "avg_response_seconds": 780, "median_response_seconds": 540, "created_at": "2026-07-26T09:41:22Z", "last_message_at": "2026-07-26T09:41:22Z" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/automations": { "get": { "summary": "List automations", "operationId": "listAutomations", "tags": [ "Automations" ], "description": "The workspace's automations (built in the visual builder), with run/error counts. Requires scope `contacts:read`.", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ] } } ], "responses": { "200": { "description": "Automations", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "trigger_type": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ] }, "last_run_at": { "type": "string", "nullable": true }, "run_count": { "type": "integer" }, "error_count": { "type": "integer" }, "created": { "type": "string" }, "updated": { "type": "string" } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": [ { "id": 128, "name": "Acme Corp", "description": "Everything you need to know about the launch.", "trigger_type": "webhook", "status": "draft", "last_run_at": "2026-07-26T09:41:22Z", "run_count": 17, "error_count": 0, "created": "example-created", "updated": "example-updated" } ], "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/automations/{automation_id}": { "get": { "summary": "Get automation", "operationId": "getAutomation", "tags": [ "Automations" ], "description": "Full automation detail including the node graph. Requires scope `contacts:read`.", "parameters": [ { "name": "automation_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Automation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "trigger_type": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ] }, "last_run_at": { "type": "string", "nullable": true }, "run_count": { "type": "integer" }, "error_count": { "type": "integer" }, "created": { "type": "string" }, "updated": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "id": 128, "name": "Acme Corp", "description": "Everything you need to know about the launch.", "trigger_type": "webhook", "status": "draft", "last_run_at": "2026-07-26T09:41:22Z", "run_count": 17, "error_count": 0, "created": "example-created", "updated": "example-updated" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/automations/{automation_id}/activate": { "post": { "summary": "Activate automation", "operationId": "activateAutomation", "tags": [ "Automations" ], "description": "Turns the automation on (validates the graph has a trigger and at least one action; webhook triggers get their URL provisioned). Requires scope `contacts:write`.", "parameters": [ { "name": "automation_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Activated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "trigger_type": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ] }, "last_run_at": { "type": "string", "nullable": true }, "run_count": { "type": "integer" }, "error_count": { "type": "integer" }, "created": { "type": "string" }, "updated": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "id": 128, "name": "Acme Corp", "description": "Everything you need to know about the launch.", "trigger_type": "webhook", "status": "draft", "last_run_at": "2026-07-26T09:41:22Z", "run_count": 17, "error_count": 0, "created": "example-created", "updated": "example-updated" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/automations/{automation_id}/deactivate": { "post": { "summary": "Pause automation", "operationId": "deactivateAutomation", "tags": [ "Automations" ], "description": "Pauses the automation and its triggers. Requires scope `contacts:write`.", "parameters": [ { "name": "automation_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Paused", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "trigger_type": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ] }, "last_run_at": { "type": "string", "nullable": true }, "run_count": { "type": "integer" }, "error_count": { "type": "integer" }, "created": { "type": "string" }, "updated": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "id": 128, "name": "Acme Corp", "description": "Everything you need to know about the launch.", "trigger_type": "webhook", "status": "draft", "last_run_at": "2026-07-26T09:41:22Z", "run_count": 17, "error_count": 0, "created": "example-created", "updated": "example-updated" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/automations/{automation_id}/trigger": { "post": { "summary": "Trigger automation", "operationId": "triggerAutomation", "tags": [ "Automations" ], "description": "Queues a manual run with an optional payload (available to the automation's steps as the trigger payload). The automation must be active. Requires scope `contacts:write`.", "parameters": [ { "name": "automation_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "payload": { "type": "object", "description": "Arbitrary JSON passed to the run." } } } } } }, "responses": { "202": { "description": "Run queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "queued": { "type": "boolean" }, "automation_id": { "type": "integer" }, "run_id": { "type": "integer" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "queued": true, "automation_id": 128, "run_id": 128 }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/automations/{automation_id}/duplicate": { "post": { "summary": "Duplicate an automation", "operationId": "duplicateAutomation", "tags": [ "Automations" ], "description": "Copies the automation's graph and trigger config into a new automation, named \" (copy)\". Always starts as `draft`, regardless of the source's status, so a duplicate never silently begins running triggers. A webhook-triggered source gets a fresh webhook token on the copy, not a shared one. Requires scope `contacts:write`.", "parameters": [ { "name": "automation_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "trigger_type": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ] }, "last_run_at": { "type": "string", "nullable": true }, "run_count": { "type": "integer" }, "error_count": { "type": "integer" }, "created": { "type": "string" }, "updated": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/automations/{automation_id}/versions": { "get": { "summary": "List automation versions", "operationId": "listAutomationVersions", "tags": [ "Automations" ], "description": "A snapshot of the graph is taken automatically every time it's edited - BEFORE the edit is applied - so version N is what the graph looked like immediately before edit N. Newest first, capped at the most recent 20. Requires scope `contacts:read`.", "parameters": [ { "name": "automation_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "integer", "description": "Per-automation version number (1, 2, 3...), not a global id." }, "name": { "type": "string", "description": "The automation's name at the time of this snapshot." }, "created_by": { "type": "integer", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": [ { "version": 3, "name": "Welcome sequence", "created_by": 12, "created_at": "2026-08-03T10:15:00Z" }, { "version": 2, "name": "Welcome sequence", "created_by": 12, "created_at": "2026-08-01T09:02:00Z" } ], "meta": { "request_id": "req_abc123", "timestamp": "2026-08-04T16:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/automations/{automation_id}/versions/{version}": { "get": { "summary": "Get one automation version", "operationId": "getAutomationVersion", "tags": [ "Automations" ], "description": "One snapshot, including its full graph. Requires scope `contacts:read`.", "parameters": [ { "name": "automation_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Version number from GET /automations/{automation_id}/versions." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "version": { "type": "integer" }, "name": { "type": "string" }, "graph": { "type": "object", "description": "The @xyflow/react node + edge graph as it stood at this version." }, "created_by": { "type": "integer", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/automations/{automation_id}/versions/{version}/restore": { "post": { "summary": "Restore an automation version", "operationId": "restoreAutomationVersion", "tags": [ "Automations" ], "description": "Puts that version's graph back onto the live automation. The current graph is snapshotted first (the same hook every edit goes through), so a restore is itself just another edit - always undoable, never destructive. Requires scope `contacts:write`.", "parameters": [ { "name": "automation_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "trigger_type": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ] }, "last_run_at": { "type": "string", "nullable": true }, "run_count": { "type": "integer" }, "error_count": { "type": "integer" }, "created": { "type": "string" }, "updated": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/automations/{automation_id}/runs": { "get": { "summary": "List runs", "operationId": "listAutomationRuns", "tags": [ "Automations" ], "description": "Run history, newest first. Requires scope `contacts:read`.", "parameters": [ { "name": "automation_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "maximum": 500 } } ], "responses": { "200": { "description": "Runs", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "automation_id": { "type": "integer" }, "trigger_kind": { "type": "string" }, "status": { "type": "string" }, "attempts": { "type": "integer" }, "queued_at": { "type": "string" }, "started_at": { "type": "string", "nullable": true }, "finished_at": { "type": "string", "nullable": true }, "error": { "type": "string", "nullable": true } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": [ { "id": 128, "automation_id": 128, "trigger_kind": "api", "status": "published", "attempts": 1, "queued_at": "2026-07-26T09:41:22Z", "started_at": "2026-07-26T09:41:22Z", "finished_at": "2026-07-26T09:41:22Z", "error": "example-error" } ], "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/automations/{automation_id}/runs/{run_id}": { "get": { "summary": "Get run", "operationId": "getAutomationRun", "tags": [ "Automations" ], "description": "One run with its trigger payload and per-step execution logs. Requires scope `contacts:read`.", "parameters": [ { "name": "automation_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Run", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "automation_id": { "type": "integer" }, "trigger_kind": { "type": "string" }, "status": { "type": "string" }, "attempts": { "type": "integer" }, "queued_at": { "type": "string" }, "started_at": { "type": "string", "nullable": true }, "finished_at": { "type": "string", "nullable": true }, "error": { "type": "string", "nullable": true } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "id": 128, "automation_id": 128, "trigger_kind": "api", "status": "published", "attempts": 1, "queued_at": "2026-07-26T09:41:22Z", "started_at": "2026-07-26T09:41:22Z", "finished_at": "2026-07-26T09:41:22Z", "error": "example-error" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/contacts/bulk": { "post": { "summary": "Bulk import contacts", "operationId": "bulkImportContacts", "tags": [ "CRM" ], "description": "Import up to 100 contacts in one call. Each row goes through the same email/phone upsert as POST /contacts, so re-importing the same file is idempotent. Per-row results report created / updated / failed. Requires scope `contacts:write`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "contacts" ], "properties": { "contacts": { "type": "array", "maxItems": 100, "items": { "type": "object", "description": "Same fields as POST /contacts (name, email, phone, company, tags, attributes...)." } } } }, "example": { "contacts": [ { "name": "Ada Lovelace", "email": "ada@example.com", "tags": [ "vip" ] }, { "name": "Alan Turing", "email": "alan@example.com" } ] } } } }, "responses": { "201": { "description": "Import results", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "created": { "type": "integer" }, "updated": { "type": "integer" }, "failed": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "row": { "type": "integer" }, "id": { "type": "integer" }, "created": { "type": "boolean" }, "matched_by": { "type": "string", "nullable": true }, "error": { "type": "string" } } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "created": 8, "updated": 2, "failed": 0, "results": [ { "row": 1, "id": 128, "created": true, "matched_by": "example-matched-by", "error": "example-error" } ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/social/accounts/{account_id}/pinterest/boards": { "get": { "summary": "Pinterest boards", "operationId": "pinterestBoards", "tags": [ "Social" ], "description": "The account's Pinterest boards (id, name, privacy) - required to target a board when pinning. Requires scope `social:read`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Connected account id." } ], "responses": { "200": { "description": "Pinterest boards", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "boards": { "type": "array", "items": { "type": "object" } }, "sandbox": { "type": "boolean" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "boards": [ {} ], "sandbox": true }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Platform rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } } } } }, "post": { "summary": "Create a Pinterest board", "operationId": "createPinterestBoard", "tags": [ "Social" ], "description": "Create a board to pin into. Listing the existing boards is the GET on this same path.\n\nRequires scope `social:write`. If the account was connected before SmartlyQ requested the permission this call needs, it answers `403 CONNECTION_SCOPE_MISSING` with `reconnect_required: true` - reconnect the account to fix it.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Connected social account id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "privacy": { "type": "string", "enum": [ "PUBLIC", "PROTECTED", "SECRET" ], "default": "PUBLIC" } } } } } }, "responses": { "201": { "description": "Board created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "board": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "privacy": { "type": "string" } } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "$ref": "#/components/responses/BadRequest" } } } }, "/social/accounts/{account_id}/youtube/playlists": { "get": { "summary": "YouTube playlists", "operationId": "youtubePlaylists", "tags": [ "Social" ], "description": "The channel's playlists (title, privacy, item count) - target one when uploading. Requires scope `social:read`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Connected account id." } ], "responses": { "200": { "description": "YouTube playlists", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "playlists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "privacy": { "type": "string" }, "item_count": { "type": "integer" } } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "playlists": [ { "id": "example-id", "title": "Product launch announcement", "description": "Everything you need to know about the launch.", "privacy": "public", "item_count": 24 } ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Platform rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } } } } } }, "/social/accounts/{account_id}/instagram/publishing-limit": { "get": { "summary": "Instagram publishing limit", "operationId": "instagramPublishingLimit", "tags": [ "Social" ], "description": "Instagram's daily content-publishing quota for this account: total, remaining, and whether a publish would be allowed right now. Requires scope `social:read`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Connected account id." } ], "responses": { "200": { "description": "Instagram publishing limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "account_id": { "type": "integer" }, "quota_total": { "type": "integer" }, "quota_remaining": { "type": "integer" }, "can_publish": { "type": "boolean" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "account_id": 128, "quota_total": 42, "quota_remaining": 93, "can_publish": true }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Platform rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } } } } } }, "/social/accounts/{account_id}/gmb/performance": { "get": { "summary": "Google Business performance", "operationId": "gmbPerformance", "tags": [ "Social" ], "description": "Business Profile performance for the window: impressions by surface (Search/Maps, mobile/desktop) with deltas vs the previous window, plus a daily series. Data lags ~1 day (Google). Requires scope `social:read`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Connected account id." }, { "name": "days", "in": "query", "schema": { "type": "integer", "default": 28, "minimum": 7, "maximum": 90 } } ], "responses": { "200": { "description": "Google Business performance", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "description": "account_id, days + the performance report (impressions, sources, daily series, deltas)." }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": {}, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Platform rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } } } } } }, "/social/accounts/{account_id}/gmb/search-keywords": { "get": { "summary": "Google Business search keywords", "operationId": "gmbSearchKeywords", "tags": [ "Social" ], "description": "The search terms people used on Google before seeing this Business Profile, with monthly impression counts. Requires scope `social:read`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Connected account id." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 12, "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "Google Business search keywords", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "account_id": { "type": "integer" }, "keywords": { "type": "array", "items": { "type": "object" } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "account_id": 128, "keywords": [ {} ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Platform rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } } } } } }, "/social/accounts/{account_id}/reddit/search": { "get": { "summary": "Reddit search", "operationId": "redditSearch", "tags": [ "Social" ], "description": "Search Reddit (optionally restricted to one subreddit) with the account's own credentials - find where a topic is being discussed before posting. Requires scope `social:read`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Connected account id." }, { "name": "q", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "subreddit", "in": "query", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "relevance", "hot", "top", "new", "comments" ], "default": "relevance" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 25, "maximum": 100 } } ], "responses": { "200": { "description": "Reddit search", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "subreddit": { "type": "string" }, "author": { "type": "string" }, "score": { "type": "integer" }, "num_comments": { "type": "integer" }, "created_utc": { "type": "integer" }, "over_18": { "type": "boolean" }, "url": { "type": "string" } } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "results": [ { "id": "example-id", "title": "Product launch announcement", "subreddit": "marketing", "author": "u/janecooper", "score": 512, "num_comments": 18, "created_utc": 1753517000, "over_18": true, "url": "https://example.com/launch" } ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Platform rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } } } } } }, "/social/accounts/{account_id}/reddit/feed": { "get": { "summary": "Reddit feed", "operationId": "redditFeed", "tags": [ "Social" ], "description": "The account's home feed or one subreddit's feed (hot / new / top / rising). Requires scope `social:read`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Connected account id." }, { "name": "subreddit", "in": "query", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "hot", "new", "top", "rising" ], "default": "hot" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 25, "maximum": 100 } } ], "responses": { "200": { "description": "Reddit feed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "subreddit": { "type": "string" }, "author": { "type": "string" }, "score": { "type": "integer" }, "num_comments": { "type": "integer" }, "created_utc": { "type": "integer" }, "over_18": { "type": "boolean" }, "url": { "type": "string" } } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "posts": [ { "id": "example-id", "title": "Product launch announcement", "subreddit": "marketing", "author": "u/janecooper", "score": 512, "num_comments": 18, "created_utc": 1753517000, "over_18": true, "url": "https://example.com/launch" } ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Platform rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } } } } } }, "/social/accounts/{account_id}/reddit/subreddits": { "get": { "summary": "Subscribed subreddits", "operationId": "redditSubreddits", "tags": [ "Social" ], "description": "Subreddits the connected account subscribes to (name, title, subscriber count). Requires scope `social:read`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Connected account id." } ], "responses": { "200": { "description": "Subscribed subreddits", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "subreddits": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "title": { "type": "string" }, "subscribers": { "type": "integer" }, "over_18": { "type": "boolean" }, "url": { "type": "string" } } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "subreddits": [ { "name": "Acme Corp", "title": "Product launch announcement", "subscribers": 88210, "over_18": true, "url": "https://example.com/launch" } ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Platform rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } } } } } }, "/social/accounts/{account_id}/reddit/subreddits/{subreddit}/rules": { "get": { "summary": "Subreddit rules", "operationId": "redditSubredditRules", "tags": [ "Social" ], "description": "A subreddit's posting rules - check them BEFORE submitting so the post doesn't get removed. Requires scope `social:read`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Connected account id." }, { "name": "subreddit", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Rules", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "subreddit": { "type": "string" }, "rules": { "type": "array", "items": { "type": "object", "properties": { "short_name": { "type": "string" }, "description": { "type": "string" }, "kind": { "type": "string" } } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "subreddit": "marketing", "rules": [ { "short_name": "No self-promotion", "description": "Everything you need to know about the launch.", "kind": "text" } ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Platform rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } } } } } }, "/social/accounts/{account_id}/instagram/stories": { "get": { "summary": "Instagram stories", "operationId": "instagramStories", "tags": [ "Social" ], "description": "The account's currently live stories (id, media type, URL, permalink, timestamp). Requires scope `social:read`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Connected account id." } ], "responses": { "200": { "description": "Instagram stories", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "stories": { "type": "array", "items": { "type": "object" } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "stories": [ {} ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Platform rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } } } } } }, "/social/accounts/{account_id}/facebook/post-reactions": { "get": { "summary": "Facebook post reactions", "operationId": "facebookPostReactions", "tags": [ "Social" ], "description": "Reaction-type breakdown (like, love, wow, haha, sad, angry, care) for a published Facebook post. Pass remote_post_id, or post_id of a SmartlyQ post published to this account. Requires scope `social:read`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Connected account id." }, { "name": "post_id", "in": "query", "schema": { "type": "integer" }, "description": "SmartlyQ post id." }, { "name": "remote_post_id", "in": "query", "schema": { "type": "string" }, "description": "Raw Facebook post id." } ], "responses": { "200": { "description": "Facebook post reactions", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "remote_post_id": { "type": "string" }, "total": { "type": "integer" }, "reactions": { "type": "object", "properties": { "like": { "type": "integer" }, "love": { "type": "integer" }, "wow": { "type": "integer" }, "haha": { "type": "integer" }, "sad": { "type": "integer" }, "angry": { "type": "integer" }, "care": { "type": "integer" } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "remote_post_id": "ext_7f2c91", "total": 42, "reactions": { "like": 1, "love": 1, "wow": 1, "haha": 1, "sad": 1, "angry": 1, "care": 1 } }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Platform rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } } } } } } } }, "/social/accounts/{account_id}/instagram/stories/{story_id}/insights": { "get": { "summary": "Instagram story insights", "operationId": "instagramStoryInsights", "tags": [ "Social" ], "description": "Insights for one story. Defaults to views and replies; pass ?metrics= (comma-separated) to request other metrics - Instagram validates them, so newly released metrics work without waiting for us. Requires scope `analytics:read`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "story_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "metrics", "in": "query", "schema": { "type": "string", "default": "views,replies" } } ], "responses": { "200": { "description": "Story insights", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "story_id": { "type": "string", "example": "17912345678901234" }, "insights": { "type": "object", "example": { "views": 812, "replies": 14 } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "story_id": "17912345678901234", "insights": { "views": 812, "replies": 14 } }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Platform rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": false, "error": { "code": "PLATFORM_ERROR", "message": "The platform rejected the request." }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } } }, "/social/accounts/{account_id}/x/retweets": { "post": { "summary": "Retweet on X", "operationId": "xRetweet", "tags": [ "Social" ], "description": "Retweets a post with the connected X account. Covered by the tweet.write permission your connection already has. Requires scope `social:write`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "tweet_id" ], "properties": { "tweet_id": { "type": "string", "example": "1815349823401570000" } } }, "example": { "tweet_id": "1815349823401570000" } } } }, "responses": { "200": { "description": "Retweeted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "tweet_id": { "type": "string", "example": "1815349823401570000" }, "retweeted": { "type": "boolean", "example": true } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "tweet_id": "1815349823401570000", "retweeted": true }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Platform rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": false, "error": { "code": "PLATFORM_ERROR", "message": "The platform rejected the request." }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } } }, "/social/accounts/{account_id}/x/retweets/{tweet_id}": { "delete": { "summary": "Undo retweet", "operationId": "xUnretweet", "tags": [ "Social" ], "description": "Removes the account's retweet of a post. Requires scope `social:write`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "tweet_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Retweet removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "tweet_id": { "type": "string", "example": "1815349823401570000" }, "retweeted": { "type": "boolean", "example": false } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "tweet_id": "1815349823401570000", "retweeted": false }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Platform rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": false, "error": { "code": "PLATFORM_ERROR", "message": "The platform rejected the request." }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } } }, "/social/posts/{post_id}/edit": { "post": { "summary": "Edit published post", "operationId": "editPublishedPost", "tags": [ "Social" ], "description": "Edits a post that has ALREADY been published, natively on the platform. Honest per-platform support: Facebook page posts work today; X's edit API is paid-tier-only and Reddit's needs a re-auth scope - those report unsupported per platform instead of failing the call. The SmartlyQ record keeps its original text for multi-platform posts. Requires scope `social:write`.", "parameters": [ { "name": "post_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string", "description": "Replacement text." }, "platforms": { "type": "array", "items": { "type": "string" }, "description": "Restrict to these platforms (default: all the post published to)." } } }, "example": { "content": "UPDATE: doors open at 7pm, not 6pm!", "platforms": [ "facebook" ] } } } }, "responses": { "200": { "description": "Edit results", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "remote_post_id": { "type": "string" }, "edited": { "type": "boolean" }, "error": { "type": "string" } } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "results": [ { "platform": "facebook", "remote_post_id": "1234567890_987654", "edited": true } ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Platform rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": false, "error": { "code": "PLATFORM_ERROR", "message": "The platform rejected the request." }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } } }, "/social/posts/{post_id}/update-metadata": { "post": { "summary": "Update YouTube metadata", "operationId": "updatePostMetadata", "tags": [ "Social" ], "description": "Post-publish updates for the post's YouTube leg: title, description, tags (snippet is fetched and merged so nothing else changes), add to a playlist, and/or set a custom thumbnail from a public URL (max 2MB). Requires scope `social:write`.", "parameters": [ { "name": "post_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 5000 }, "tags": { "type": "array", "items": { "type": "string" }, "maxItems": 60 }, "playlist_id": { "type": "string" }, "thumbnail_url": { "type": "string", "format": "uri" } } }, "example": { "title": "The launch, one week later", "playlist_id": "PL9tY0BWXOZFvE", "thumbnail_url": "https://cdn.example.com/thumb.png" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "video_id": { "type": "string", "example": "dQw4w9WgXcQ" }, "updated": { "type": "array", "items": { "type": "string", "enum": [ "snippet", "playlist", "thumbnail" ] } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "video_id": "dQw4w9WgXcQ", "updated": [ "snippet", "playlist" ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Platform rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": false, "error": { "code": "PLATFORM_ERROR", "message": "The platform rejected the request." }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } } }, "/social/posts/sync-external": { "post": { "summary": "Sync external posts", "operationId": "syncExternalPosts", "tags": [ "Social" ], "description": "On-demand import of posts published natively on the platform (outside SmartlyQ) for one account - facebook, instagram, threads, youtube or tiktok. Imported posts appear in GET /social/posts with status 'external', with analytics snapshots. Discovery is a per-account opt-in: pass enable: true the first time, or the call returns 409. Requires scope `social:write`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "account_id" ], "properties": { "account_id": { "type": "integer" }, "limit": { "type": "integer", "default": 50, "maximum": 100 }, "enable": { "type": "boolean", "description": "Opt the account into external-post discovery." } } }, "example": { "account_id": 128, "enable": true } } } }, "responses": { "200": { "description": "Synced", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "posts_synced": { "type": "integer", "example": 12 }, "enabled": { "type": "boolean", "example": true } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "posts_synced": 12, "enabled": true }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Platform rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": false, "error": { "code": "PLATFORM_ERROR", "message": "The platform rejected the request." }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } } }, "/social/accounts/{account_id}/insights": { "get": { "summary": "Live account insights", "operationId": "accountInsights", "tags": [ "Social" ], "description": "LIVE account metrics straight from the platform (followers, following, posts, profile views, impressions, reach, engagements, new followers - whatever the platform exposes), via the same per-platform providers the daily analytics sync uses. Works for every connected platform with an analytics provider. Requires scope `analytics:read`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Live metrics", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "account_id": { "type": "integer", "example": 128 }, "platform": { "type": "string", "example": "instagram" }, "metrics": { "type": "object", "example": { "followers": 10432, "following": 512, "posts_count": 284, "impressions": 48210, "reach": 30125, "engagements": 2411, "new_followers": 96 } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "account_id": 128, "platform": "instagram", "metrics": { "followers": 10432, "following": 512, "posts_count": 284, "impressions": 48210, "reach": 30125, "engagements": 2411, "new_followers": 96 } }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Platform rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": false, "error": { "code": "PLATFORM_ERROR", "message": "The platform rejected the request." }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } } }, "/social/accounts/{account_id}/gmb/locations": { "get": { "summary": "List Google locations", "operationId": "gmbLocations", "tags": [ "Social" ], "description": "Every location under the connected profile's parent Google account (multi-location businesses). Override fields with ?read_mask=. Requires a connected Google Business account; bodies/responses are honest passthroughs of Google's resource shapes, so every Google field works. Requires scope `social:read`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Connected Google Business account id." }, { "name": "read_mask", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated Google Location field paths." } ], "responses": { "200": { "description": "List Google locations", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "locations": { "type": "array", "items": { "type": "object" } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "locations": [ { "name": "locations/123456789", "title": "Acme Coffee Roasters", "websiteUri": "https://acme.coffee" } ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Google rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" }, "details": { "type": "object", "properties": { "google_status": { "type": "string", "nullable": true } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": false, "error": { "code": "PLATFORM_ERROR", "message": "Google Business rejected the request: Invalid attribute mask.", "details": { "google_status": "INVALID_ARGUMENT" } }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } } }, "/social/accounts/{account_id}/gmb/location": { "get": { "summary": "Get business info", "operationId": "gmbLocation", "tags": [ "Social" ], "description": "The location's full business information: hours, phone numbers, categories, service area, profile description, service items and more. Override fields with ?read_mask=. Requires a connected Google Business account; bodies/responses are honest passthroughs of Google's resource shapes, so every Google field works. Requires scope `social:read`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Connected Google Business account id." }, { "name": "read_mask", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get business info", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "description": "Google Location resource." }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "name": "locations/123456789", "title": "Acme Coffee Roasters", "phoneNumbers": { "primaryPhone": "+30 210 123 4567" }, "regularHours": { "periods": [ { "openDay": "MONDAY", "openTime": { "hours": 8 }, "closeDay": "MONDAY", "closeTime": { "hours": 17 } } ] } }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Google rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" }, "details": { "type": "object", "properties": { "google_status": { "type": "string", "nullable": true } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": false, "error": { "code": "PLATFORM_ERROR", "message": "Google Business rejected the request: Invalid attribute mask.", "details": { "google_status": "INVALID_ARGUMENT" } }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } }, "patch": { "summary": "Update business info", "operationId": "gmbUpdateLocation", "tags": [ "Social" ], "description": "Updates any Google Location fields named in update_mask - hours, phone, website, description, categories, service items. Requires a connected Google Business account; bodies/responses are honest passthroughs of Google's resource shapes, so every Google field works. Requires scope `social:write`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Connected Google Business account id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "location", "update_mask" ], "properties": { "location": { "type": "object", "description": "Google Location fields to write." }, "update_mask": { "type": "string", "description": "Comma-separated field paths, e.g. regularHours,phoneNumbers." } } }, "example": { "location": { "websiteUri": "https://acme.coffee/menu" }, "update_mask": "websiteUri" } } } }, "responses": { "200": { "description": "Update business info", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "description": "The updated Google Location resource." }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "name": "locations/123456789", "title": "Acme Coffee Roasters", "websiteUri": "https://acme.coffee" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Google rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" }, "details": { "type": "object", "properties": { "google_status": { "type": "string", "nullable": true } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": false, "error": { "code": "PLATFORM_ERROR", "message": "Google Business rejected the request: Invalid attribute mask.", "details": { "google_status": "INVALID_ARGUMENT" } }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } } }, "/social/accounts/{account_id}/gmb/attributes": { "get": { "summary": "Get attributes", "operationId": "gmbAttributes", "tags": [ "Social" ], "description": "The attributes currently set on the location (Wi-Fi, outdoor seating, wheelchair access, ...). Requires a connected Google Business account; bodies/responses are honest passthroughs of Google's resource shapes, so every Google field works. Requires scope `social:read`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Connected Google Business account id." } ], "responses": { "200": { "description": "Get attributes", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "description": "Google Attributes resource." }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "name": "locations/123456789/attributes", "attributes": [ { "name": "attributes/has_wifi_free", "valueType": "BOOL", "values": [ true ] } ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Google rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" }, "details": { "type": "object", "properties": { "google_status": { "type": "string", "nullable": true } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": false, "error": { "code": "PLATFORM_ERROR", "message": "Google Business rejected the request: Invalid attribute mask.", "details": { "google_status": "INVALID_ARGUMENT" } }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } }, "put": { "summary": "Update attributes", "operationId": "gmbUpdateAttributes", "tags": [ "Social" ], "description": "Sets/updates the attributes named in attribute_mask. Discover what this location supports with GET .../attributes/metadata. Requires a connected Google Business account; bodies/responses are honest passthroughs of Google's resource shapes, so every Google field works. Requires scope `social:write`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Connected Google Business account id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "attributes", "attribute_mask" ], "properties": { "attributes": { "type": "array", "items": { "type": "object" }, "description": "Google Attribute objects." }, "attribute_mask": { "type": "string", "description": "Comma-separated attribute names, e.g. attributes/has_wifi_free." } } }, "example": { "attributes": [ { "name": "attributes/has_wifi_free", "valueType": "BOOL", "values": [ true ] } ], "attribute_mask": "attributes/has_wifi_free" } } } }, "responses": { "200": { "description": "Update attributes", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "description": "The updated Attributes resource." }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "name": "locations/123456789/attributes", "attributes": [ { "name": "attributes/has_wifi_free", "values": [ true ] } ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Google rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" }, "details": { "type": "object", "properties": { "google_status": { "type": "string", "nullable": true } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": false, "error": { "code": "PLATFORM_ERROR", "message": "Google Business rejected the request: Invalid attribute mask.", "details": { "google_status": "INVALID_ARGUMENT" } }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } } }, "/social/accounts/{account_id}/gmb/attributes/metadata": { "get": { "summary": "Available attributes", "operationId": "gmbAttributeMetadata", "tags": [ "Social" ], "description": "Which attributes Google allows for THIS location's category, with display names and value types - fetch before updating attributes. Requires a connected Google Business account; bodies/responses are honest passthroughs of Google's resource shapes, so every Google field works. Requires scope `social:read`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Connected Google Business account id." } ], "responses": { "200": { "description": "Available attributes", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "attributes": { "type": "array", "items": { "type": "object" } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "attributes": [ { "parent": "attributes/has_wifi_free", "attributeId": "has_wifi_free", "valueType": "BOOL", "displayName": "Free Wi-Fi" } ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Google rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" }, "details": { "type": "object", "properties": { "google_status": { "type": "string", "nullable": true } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": false, "error": { "code": "PLATFORM_ERROR", "message": "Google Business rejected the request: Invalid attribute mask.", "details": { "google_status": "INVALID_ARGUMENT" } }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } } }, "/social/accounts/{account_id}/gmb/media": { "get": { "summary": "List media", "operationId": "gmbMedia", "tags": [ "Social" ], "description": "Photos/videos on the Business Profile with view counts and Google-hosted URLs. Requires a connected Google Business account; bodies/responses are honest passthroughs of Google's resource shapes, so every Google field works. Requires scope `social:read`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Connected Google Business account id." } ], "responses": { "200": { "description": "List media", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "media": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "media": [ { "name": "accounts/1/locations/2/media/3", "mediaFormat": "PHOTO", "googleUrl": "https://lh3.googleusercontent.com/..." } ], "total": 24 }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Google rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" }, "details": { "type": "object", "properties": { "google_status": { "type": "string", "nullable": true } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": false, "error": { "code": "PLATFORM_ERROR", "message": "Google Business rejected the request: Invalid attribute mask.", "details": { "google_status": "INVALID_ARGUMENT" } }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } }, "post": { "summary": "Add photo", "operationId": "gmbCreateMedia", "tags": [ "Social" ], "description": "Publishes a photo to the Business Profile from a public URL. Requires a connected Google Business account; bodies/responses are honest passthroughs of Google's resource shapes, so every Google field works. Requires scope `social:write`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Connected Google Business account id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "source_url" ], "properties": { "source_url": { "type": "string", "format": "uri" }, "category": { "type": "string", "default": "ADDITIONAL", "description": "COVER, PROFILE, LOGO, EXTERIOR, INTERIOR, PRODUCT, MENU, TEAMS, ADDITIONAL..." } } }, "example": { "source_url": "https://cdn.example.com/storefront.jpg", "category": "EXTERIOR" } } } }, "responses": { "201": { "description": "Add photo", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "description": "The created Google MediaItem." }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "name": "accounts/1/locations/2/media/9", "mediaFormat": "PHOTO" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Google rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" }, "details": { "type": "object", "properties": { "google_status": { "type": "string", "nullable": true } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": false, "error": { "code": "PLATFORM_ERROR", "message": "Google Business rejected the request: Invalid attribute mask.", "details": { "google_status": "INVALID_ARGUMENT" } }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } }, "delete": { "summary": "Delete media", "operationId": "gmbDeleteMedia", "tags": [ "Social" ], "description": "Removes a media item; name must be a media resource of this location. Requires a connected Google Business account; bodies/responses are honest passthroughs of Google's resource shapes, so every Google field works. Requires scope `social:write`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Connected Google Business account id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Full media resource name (accounts/.../locations/.../media/...)." } } }, "example": { "name": "accounts/1/locations/2/media/9" } } } }, "responses": { "200": { "description": "Delete media", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": {}, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Google rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" }, "details": { "type": "object", "properties": { "google_status": { "type": "string", "nullable": true } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": false, "error": { "code": "PLATFORM_ERROR", "message": "Google Business rejected the request: Invalid attribute mask.", "details": { "google_status": "INVALID_ARGUMENT" } }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } } }, "/social/accounts/{account_id}/gmb/food-menus": { "get": { "summary": "Get food menus", "operationId": "gmbFoodMenus", "tags": [ "Social" ], "description": "The location's structured food menus (sections, items, prices). ONLY available for food-serving business categories (restaurants, cafes, bakeries...) - Google returns a precondition error for other business types, which we pass through as a clear 502. Requires a connected Google Business account; bodies/responses are honest passthroughs of Google's resource shapes, so every Google field works. Requires scope `social:read`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Connected Google Business account id." } ], "responses": { "200": { "description": "Get food menus", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "description": "Google FoodMenus resource." }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "name": "accounts/1/locations/2/foodMenus", "menus": [ { "labels": [ { "displayName": "Lunch" } ] } ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Google rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" }, "details": { "type": "object", "properties": { "google_status": { "type": "string", "nullable": true } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": false, "error": { "code": "PLATFORM_ERROR", "message": "Google Business rejected the request: Invalid attribute mask.", "details": { "google_status": "INVALID_ARGUMENT" } }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } }, "put": { "summary": "Update food menus", "operationId": "gmbUpdateFoodMenus", "tags": [ "Social" ], "description": "Replaces the structured menus with the given Google FoodMenu objects. ONLY available for food-serving business categories - other business types get Google's precondition error passed through. Requires a connected Google Business account; bodies/responses are honest passthroughs of Google's resource shapes, so every Google field works. Requires scope `social:write`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Connected Google Business account id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "menus" ], "properties": { "menus": { "type": "array", "items": { "type": "object" } } } }, "example": { "menus": [ { "labels": [ { "displayName": "Lunch" } ], "sections": [] } ] } } } }, "responses": { "200": { "description": "Update food menus", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "description": "The updated FoodMenus resource." }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "name": "accounts/1/locations/2/foodMenus" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Google rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" }, "details": { "type": "object", "properties": { "google_status": { "type": "string", "nullable": true } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": false, "error": { "code": "PLATFORM_ERROR", "message": "Google Business rejected the request: Invalid attribute mask.", "details": { "google_status": "INVALID_ARGUMENT" } }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } } }, "/social/accounts/{account_id}/gmb/place-actions": { "get": { "summary": "List place-action links", "operationId": "gmbPlaceActions", "tags": [ "Social" ], "description": "The location's action links shown on Google (order, reserve, appointment, menu...). Requires a connected Google Business account; bodies/responses are honest passthroughs of Google's resource shapes, so every Google field works. Requires scope `social:read`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Connected Google Business account id." } ], "responses": { "200": { "description": "List place-action links", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "place_action_links": { "type": "array", "items": { "type": "object" } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "place_action_links": [ { "name": "locations/2/placeActionLinks/5", "uri": "https://acme.coffee/order", "placeActionType": "ORDER" } ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Google rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" }, "details": { "type": "object", "properties": { "google_status": { "type": "string", "nullable": true } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": false, "error": { "code": "PLATFORM_ERROR", "message": "Google Business rejected the request: Invalid attribute mask.", "details": { "google_status": "INVALID_ARGUMENT" } }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } }, "post": { "summary": "Create place-action link", "operationId": "gmbCreatePlaceAction", "tags": [ "Social" ], "description": "Adds an action link (APPOINTMENT, ORDER, RESERVATION, MENU, BOOK_ONLINE...). Requires a connected Google Business account; bodies/responses are honest passthroughs of Google's resource shapes, so every Google field works. Requires scope `social:write`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Connected Google Business account id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "uri", "place_action_type" ], "properties": { "uri": { "type": "string", "format": "uri" }, "place_action_type": { "type": "string", "example": "ORDER" } } }, "example": { "uri": "https://acme.coffee/order", "place_action_type": "ORDER" } } } }, "responses": { "201": { "description": "Create place-action link", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "description": "The created PlaceActionLink." }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "name": "locations/2/placeActionLinks/5", "uri": "https://acme.coffee/order", "placeActionType": "ORDER" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Google rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" }, "details": { "type": "object", "properties": { "google_status": { "type": "string", "nullable": true } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": false, "error": { "code": "PLATFORM_ERROR", "message": "Google Business rejected the request: Invalid attribute mask.", "details": { "google_status": "INVALID_ARGUMENT" } }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } }, "delete": { "summary": "Delete place-action link", "operationId": "gmbDeletePlaceAction", "tags": [ "Social" ], "description": "Removes an action link; name must belong to this location. Requires a connected Google Business account; bodies/responses are honest passthroughs of Google's resource shapes, so every Google field works. Requires scope `social:write`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Connected Google Business account id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } }, "example": { "name": "locations/2/placeActionLinks/5" } } } }, "responses": { "200": { "description": "Delete place-action link", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": {}, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Google rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" }, "details": { "type": "object", "properties": { "google_status": { "type": "string", "nullable": true } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": false, "error": { "code": "PLATFORM_ERROR", "message": "Google Business rejected the request: Invalid attribute mask.", "details": { "google_status": "INVALID_ARGUMENT" } }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } }, "patch": { "summary": "Update place-action link", "operationId": "gmbUpdatePlaceAction", "tags": [ "Social" ], "description": "Updates an action link's URI in place. name must belong to this location. Requires scope `social:write`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "uri" ], "properties": { "name": { "type": "string" }, "uri": { "type": "string", "format": "uri" } } }, "example": { "name": "locations/2/placeActionLinks/5", "uri": "https://acme.coffee/order-v2" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "description": "The updated PlaceActionLink." }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "name": "locations/2/placeActionLinks/5", "uri": "https://acme.coffee/order-v2", "placeActionType": "ORDER" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Platform rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": false, "error": { "code": "PLATFORM_ERROR", "message": "The platform rejected the request." }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } } }, "/social/accounts/{account_id}/gmb/verifications": { "get": { "summary": "List verifications", "operationId": "gmbVerifications", "tags": [ "Social" ], "description": "Past and pending verification attempts for the location. Requires a connected Google Business account; bodies/responses are honest passthroughs of Google's resource shapes, so every Google field works. Requires scope `social:read`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Connected Google Business account id." } ], "responses": { "200": { "description": "List verifications", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "verifications": { "type": "array", "items": { "type": "object" } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "verifications": [ { "name": "locations/2/verifications/7", "method": "AUTO", "state": "COMPLETED" } ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Google rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" }, "details": { "type": "object", "properties": { "google_status": { "type": "string", "nullable": true } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": false, "error": { "code": "PLATFORM_ERROR", "message": "Google Business rejected the request: Invalid attribute mask.", "details": { "google_status": "INVALID_ARGUMENT" } }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } } }, "/social/accounts/{account_id}/gmb/verifications/options": { "post": { "summary": "Verification options", "operationId": "gmbVerificationOptions", "tags": [ "Social" ], "description": "Which verification methods Google offers this location (postcard, phone, email, auto). Requires a connected Google Business account; bodies/responses are honest passthroughs of Google's resource shapes, so every Google field works. Requires scope `social:read`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Connected Google Business account id." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "language_code": { "type": "string", "default": "en" } } } } } }, "responses": { "200": { "description": "Verification options", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "options": { "type": "array", "items": { "type": "object" } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "options": [ { "verificationMethod": "PHONE_CALL", "phoneNumber": "+30 210 *** **67" } ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Google rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" }, "details": { "type": "object", "properties": { "google_status": { "type": "string", "nullable": true } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": false, "error": { "code": "PLATFORM_ERROR", "message": "Google Business rejected the request: Invalid attribute mask.", "details": { "google_status": "INVALID_ARGUMENT" } }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } } }, "/social/accounts/{account_id}/reddit/subreddits/{subreddit}": { "get": { "summary": "Subreddit info + eligibility", "operationId": "redditSubredditInfo", "tags": [ "Social" ], "description": "Subreddit details plus a posting-eligibility check for THIS connected account: does it exist, what submission kinds it accepts, is the account banned, and a computed can_post verdict. Check before submitting. Requires scope `social:read`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "subreddit", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Subreddit info", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "name": { "type": "string", "example": "marketing" }, "title": { "type": "string", "example": "Marketing" }, "subscribers": { "type": "integer", "example": 512034 }, "over_18": { "type": "boolean", "example": false }, "subreddit_type": { "type": "string", "example": "public" }, "submission_type": { "type": "string", "example": "any" }, "user_is_banned": { "type": "boolean", "example": false }, "user_is_subscriber": { "type": "boolean", "example": true }, "can_post": { "type": "boolean", "example": true }, "url": { "type": "string", "example": "https://www.reddit.com/r/marketing/" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "name": "marketing", "title": "Marketing", "subscribers": 512034, "over_18": false, "subreddit_type": "public", "submission_type": "any", "user_is_banned": false, "user_is_subscriber": true, "can_post": true, "url": "https://www.reddit.com/r/marketing/" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Platform rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": false, "error": { "code": "PLATFORM_ERROR", "message": "The platform rejected the request." }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } } }, "/social/accounts/{account_id}/x/mentions": { "get": { "summary": "X mentions", "operationId": "xMentions", "tags": [ "Social" ], "description": "Recent posts mentioning the connected X account, with engagement metrics. Requires scope `social:read`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 25, "minimum": 5, "maximum": 100 } } ], "responses": { "200": { "description": "Mentions", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "mentions": { "type": "array", "items": { "type": "object" } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "mentions": [ { "tweet_id": "1815349823401570000", "text": "@acme your scheduler is great!", "author_id": "44196397", "conversation_id": "1815349823401570000", "created_at": "2026-07-26T08:12:00.000Z", "likes": 12, "replies": 2, "retweets": 1, "url": "https://x.com/i/status/1815349823401570000" } ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Platform rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": false, "error": { "code": "PLATFORM_ERROR", "message": "The platform rejected the request." }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } } }, "/contacts/{id}/channels": { "get": { "summary": "Contact channels", "operationId": "contactChannels", "tags": [ "CRM" ], "description": "The channels this contact has actually communicated on (from the conversation timeline), with per-channel volume and last activity - pick the right channel before reaching out. Requires scope `contacts:read`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Channels", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "channels": { "type": "array", "items": { "type": "object", "properties": { "channel": { "type": "string" }, "incoming": { "type": "integer" }, "outgoing": { "type": "integer" }, "last_message_at": { "type": "string", "nullable": true } } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "channels": [ { "channel": "email", "incoming": 6, "outgoing": 9, "last_message_at": "2026-07-25T16:03:00Z" }, { "channel": "instagram", "incoming": 2, "outgoing": 2, "last_message_at": "2026-07-20T11:40:00Z" } ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/social/conversations/{conversation_id}/typing": { "post": { "summary": "Typing indicator", "operationId": "sendTypingIndicator", "tags": [ "Social" ], "description": "Shows the typing indicator to the other side of a Facebook or Instagram conversation (Meta sender_action). Other platforms return 422. Requires scope `social:write`.", "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Indicator sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "typing": { "type": "boolean", "example": true } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "typing": true }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Platform rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": false, "error": { "code": "PLATFORM_ERROR", "message": "The platform rejected the request." }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } } }, "/social/comments/{comment_id}/private-reply": { "post": { "summary": "Private reply (comment-to-DM)", "operationId": "commentPrivateReply", "tags": [ "Social" ], "description": "Sends a DIRECT MESSAGE to the author of a Facebook or Instagram comment via Meta's private-reply mechanism. Meta allows one private reply per comment, within 7 days - violations are surfaced verbatim. Also available as the automation action `action.private_reply` paired with the `comment_created` trigger. Requires scope `social:write`.", "parameters": [ { "name": "comment_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "SmartlyQ comment id (from GET /social/comments)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "maxLength": 2000 } } }, "example": { "message": "Thanks for asking! Sending you the details here 👇" } } } }, "responses": { "200": { "description": "Reply sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "sent": { "type": "boolean", "example": true }, "remote_message_id": { "type": "string", "example": "mid.1815349823401570000" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "sent": true, "remote_message_id": "mid.1815349823401570000" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Platform rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": false, "error": { "code": "PLATFORM_ERROR", "message": "The platform rejected the request." }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } } }, "/social/accounts/{account_id}/messenger/menu": { "get": { "summary": "Get Messenger menu", "operationId": "getMessengerMenu", "tags": [ "Social" ], "description": "The Facebook page's persistent menu (Meta messenger_profile shape). Requires scope `social:read`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Menu", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "persistent_menu": { "type": "array", "items": { "type": "object" } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "persistent_menu": [ { "locale": "default", "call_to_actions": [ { "type": "web_url", "title": "Shop now", "url": "https://acme.shop" } ] } ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Platform rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": false, "error": { "code": "PLATFORM_ERROR", "message": "The platform rejected the request." }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } }, "put": { "summary": "Set Messenger menu", "operationId": "setMessengerMenu", "tags": [ "Social" ], "description": "Replaces the page's persistent menu (Meta menu objects, passthrough). Requires scope `social:write`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "persistent_menu" ], "properties": { "persistent_menu": { "type": "array", "items": { "type": "object" } } } }, "example": { "persistent_menu": [ { "locale": "default", "call_to_actions": [ { "type": "web_url", "title": "Shop now", "url": "https://acme.shop" } ] } ] } } } }, "responses": { "200": { "description": "Menu set", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "persistent_menu": [ { "locale": "default", "call_to_actions": [ { "type": "web_url", "title": "Shop now", "url": "https://acme.shop" } ] } ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Platform rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": false, "error": { "code": "PLATFORM_ERROR", "message": "The platform rejected the request." }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } }, "delete": { "summary": "Delete Messenger menu", "operationId": "deleteMessengerMenu", "tags": [ "Social" ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Menu removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": {}, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Platform rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": false, "error": { "code": "PLATFORM_ERROR", "message": "The platform rejected the request." }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } } }, "/social/accounts/{account_id}/instagram/ice-breakers": { "get": { "summary": "Get ice breakers", "operationId": "getIceBreakers", "tags": [ "Social" ], "description": "The Instagram account's DM ice breakers (the FAQ chips new visitors see). Requires scope `social:read`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Ice breakers", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "ice_breakers": { "type": "array", "items": { "type": "object" } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "ice_breakers": [ { "call_to_actions": [ { "question": "What are your opening hours?", "payload": "HOURS" } ], "locale": "default" } ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Platform rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": false, "error": { "code": "PLATFORM_ERROR", "message": "The platform rejected the request." }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } }, "put": { "summary": "Set ice breakers", "operationId": "setIceBreakers", "tags": [ "Social" ], "description": "Replaces the ice breakers (1-4 Meta ice-breaker objects, passthrough). Requires scope `social:write`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ice_breakers" ], "properties": { "ice_breakers": { "type": "array", "maxItems": 4, "items": { "type": "object" } } } }, "example": { "ice_breakers": [ { "call_to_actions": [ { "question": "What are your opening hours?", "payload": "HOURS" } ], "locale": "default" } ] } } } }, "responses": { "200": { "description": "Ice breakers set", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "ice_breakers": [ { "call_to_actions": [ { "question": "What are your opening hours?", "payload": "HOURS" } ], "locale": "default" } ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Platform rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": false, "error": { "code": "PLATFORM_ERROR", "message": "The platform rejected the request." }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } }, "delete": { "summary": "Delete ice breakers", "operationId": "deleteIceBreakers", "tags": [ "Social" ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Ice breakers removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": {}, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Platform rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": false, "error": { "code": "PLATFORM_ERROR", "message": "The platform rejected the request." }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } } }, "/social/accounts/{account_id}/facebook/page-insights": { "get": { "summary": "Facebook page insights", "operationId": "facebookPageInsights", "tags": [ "Social" ], "description": "Metric passthrough to Meta's Page Insights: request any page metric by name (Meta validates, so new metrics work without waiting for us). Defaults to impressions, engagements and fans. Requires scope `analytics:read`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "metrics", "in": "query", "schema": { "type": "string", "default": "page_impressions,page_post_engagements,page_fans" } }, { "name": "period", "in": "query", "schema": { "type": "string", "enum": [ "day", "week", "days_28" ], "default": "day" } } ], "responses": { "200": { "description": "Page insights", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "account_id": { "type": "integer", "example": 128 }, "period": { "type": "string", "example": "day" }, "insights": { "type": "object", "example": { "page_impressions": { "period": "day", "values": [ { "value": 4821, "end_time": "2026-07-26T07:00:00+0000" } ] } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "account_id": 128, "period": "day", "insights": { "page_impressions": { "period": "day", "values": [ { "value": 4821, "end_time": "2026-07-26T07:00:00+0000" } ] } } }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Platform rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": false, "error": { "code": "PLATFORM_ERROR", "message": "The platform rejected the request." }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } } }, "/social/accounts/{account_id}/instagram/audience": { "get": { "summary": "Instagram audience demographics", "operationId": "instagramAudience", "tags": [ "Social" ], "description": "Follower demographics by city, country, age or gender (IG follower_demographics insights). Instagram requires 100+ followers and hides small buckets - its errors are surfaced verbatim. Requires scope `analytics:read`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "breakdown", "in": "query", "schema": { "type": "string", "enum": [ "city", "country", "age", "gender" ], "default": "country" } } ], "responses": { "200": { "description": "Audience", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "account_id": { "type": "integer", "example": 128 }, "breakdown": { "type": "string", "example": "country" }, "audience": { "type": "object", "example": { "GR": 4210, "US": 2107, "DE": 950 } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "account_id": 128, "breakdown": "country", "audience": { "GR": 4210, "US": 2107, "DE": 950 } }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Platform rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": false, "error": { "code": "PLATFORM_ERROR", "message": "The platform rejected the request." }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } } }, "/social/accounts/{account_id}/connect-options": { "get": { "summary": "Connection target options", "operationId": "connectOptions", "tags": [ "Social" ], "description": "Which entity this connection is bound to and, where the stored token allows, the alternatives it could be re-pointed at. Google Business tokens are user-level, so every location under the parent account is selectable; platforms with entity-bound tokens (e.g. Facebook page tokens) report supported: false with the reason - switching those requires reconnecting. Requires scope `social:read`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Options", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "platform": { "type": "string" }, "current": { "type": "string" }, "supported": { "type": "boolean" }, "reason": { "type": "string" }, "options": { "type": "array", "items": { "type": "object" } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "platform": "gmb", "current": "locations/3028801774268379521", "supported": true, "options": [ { "target_id": "locations/3028801774268379521", "title": "Acme Coffee - Downtown", "store_code": null, "current": true }, { "target_id": "locations/8412073399121", "title": "Acme Coffee - Airport", "store_code": "APT-2", "current": false } ] }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Platform rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": false, "error": { "code": "PLATFORM_ERROR", "message": "The platform rejected the request." }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } } }, "/social/accounts/{account_id}/connect-select": { "post": { "summary": "Select connection target", "operationId": "connectSelect", "tags": [ "Social" ], "description": "Re-points a Google Business connection at another location of the same parent account (the assign-location operation). The target is verified against Google's live location list - never trusted from input. Requires scope `social:write`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "target_id" ], "properties": { "target_id": { "type": "string", "pattern": "^locations/[0-9]+$" } } }, "example": { "target_id": "locations/8412073399121" } } } }, "responses": { "200": { "description": "Re-pointed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "account_id": { "type": "integer", "example": 128 }, "target_id": { "type": "string", "example": "locations/8412073399121" }, "title": { "type": "string", "example": "Acme Coffee - Airport" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "account_id": 128, "target_id": "locations/8412073399121", "title": "Acme Coffee - Airport" }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Platform rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLATFORM_ERROR" ] }, "message": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": false, "error": { "code": "PLATFORM_ERROR", "message": "The platform rejected the request." }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } } } }, "/media/upload-direct": { "post": { "summary": "Upload a file directly", "operationId": "uploadMediaDirect", "description": "Upload a file in one multipart/form-data request - no presign step. The file is stored and recorded in your media library, and the response is the same shape as GET /media/{id}. The file type is detected from the bytes (not the declared Content-Type); max 200MB (upload larger media by URL). Requires `media:write`.", "tags": [ "Media" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "The media file (image/video/audio/pdf)." } } } } } }, "responses": { "201": { "description": "Stored media record", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "data": { "id": "a1b2c3d4e5f60718293a4b5c6d7e8f90", "url": "https://cdn.smartlyq.com/uploads/12/2026/07/launch.mp4", "filename": "launch.mp4", "extension": "mp4", "content_type": "video/mp4", "type": "video", "size": 48213004, "created_at": "2026-07-27T10:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/social/comments/{post_id}": { "get": { "summary": "Get one post's comments (threaded)", "operationId": "getPostComments", "description": "Returns a single post's comments as a nested reply tree, with post metadata. A by-id convenience over GET /social/comments (which already threads replies). Reply nesting is populated for every platform except Pinterest (whose comments are flat). Requires social:read.", "tags": [ "Comments" ], "parameters": [ { "name": "post_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The SmartlyQ post id." } ], "responses": { "200": { "description": "Post with threaded comments", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "data": { "id": 8841, "post_id": 8841, "remote_post_id": "178...", "platform": "twitter", "content": "Launch day!", "permalink": "https://x.com/acme/status/178...", "comment_count": 3, "comments": [ { "id": 51, "author_name": "Jamie", "content": "Congrats!", "is_reply": 0, "replies": [ { "id": 52, "author_name": "Acme", "content": "Thanks!", "is_reply": 1, "replies": [] } ] } ] } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/contacts/{id}/fields/{slug}": { "put": { "summary": "Set one custom field", "operationId": "setContactField", "description": "Set a single custom field on a contact by its slug (the field's key). The slug must be a defined custom field in this workspace (create one with POST /custom-fields). Merges into the contact's attributes without touching other fields. Requires contacts:write.", "tags": [ "CRM Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The custom field's key/slug." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "value" ], "properties": { "value": { "description": "The value to store (string, number, boolean or null)." } } }, "example": { "value": "enterprise" } } } }, "responses": { "200": { "description": "Updated attributes", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "data": { "attributes": { "plan_tier": "enterprise" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "summary": "Clear one custom field", "operationId": "clearContactField", "description": "Remove a single custom field from a contact by slug. Succeeds (200) even if the field was not set. Requires contacts:write.", "tags": [ "CRM Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The custom field's key/slug." } ], "responses": { "200": { "description": "Remaining attributes", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "data": { "attributes": {} } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/me/billing": { "get": { "summary": "Billing overview", "operationId": "getBilling", "description": "A read-only superset of GET /me/balance: the wallet balance breakdown, the monthly cycle reset, auto-recharge configuration, and whether a card is on file. Use payment.status to know if the next billable call is at risk.", "tags": [ "Account" ], "responses": { "200": { "description": "Billing overview", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "data": { "currency": "USD", "balance": { "total": "42.5000", "purchased": "40.0000", "monthly": "2.5000" }, "cycle": { "monthly_reset_at": "2026-08-01T00:00:00Z" }, "auto_recharge": { "enabled": true, "below": "5.0000", "amount": "25.0000", "active": true }, "payment": { "card_on_file": true, "status": "ok" } } } } } } } } }, "/whatsapp/messages": { "post": { "summary": "Send a WhatsApp message", "operationId": "sendWhatsAppMessage", "description": "Send a message from a connected WhatsApp number. `text`, `media`, `interactive_buttons`, `interactive_list`, `location`, `contacts`, and `flow` are SESSION messages - deliverable only inside the 24-hour customer window (i.e. after the user messaged you). Outside it, only `template` (an approved HSM) is deliverable. `context_message_id` (any type except `contacts`) threads the message as a reply under a prior WhatsApp message id, rendering as a quoted reply in the customer's app. `type=flow` requires the flow to be PUBLISHED first (see the WhatsApp Flows endpoints) - a DRAFT flow can only be tested via its preview URL. Requires social:write.\n\n**Pricing.** Billed per message from your API wallet, on top of your plan's monthly WhatsApp send limit. The price depends on the destination country and the message category, mirroring how WhatsApp itself prices, so a utility message to one market and a marketing message to another cost different amounts. Free-form replies are billed as `service`, priced at the destination market's utility rate. The response carries a `pricing` block showing which rate was applied, and the `usage` block reports cost and remaining balance. You are charged only for a message accepted for delivery - a rejected send is refunded automatically.", "tags": [ "WhatsApp" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "account_id", "to" ], "properties": { "account_id": { "type": "integer", "description": "A connected WhatsApp number (social account id)." }, "to": { "type": "string", "description": "Recipient phone in E.164 (e.g. +14155551234)." }, "type": { "type": "string", "enum": [ "text", "media", "template", "interactive_buttons", "interactive_list", "location", "contacts", "reaction", "flow" ], "default": "text" }, "context_message_id": { "type": "string", "description": "A prior WhatsApp message id (wamid) to thread this message as a reply under, or (for type=reaction) the message being reacted to. Renders as a quoted reply in the customer's app." }, "footer_text": { "type": "string", "description": "For type=flow. Optional footer line below the body, max 60 characters." }, "text": { "type": "string", "description": "Body for type=text, or the prompt text for type=interactive_buttons/interactive_list." }, "media": { "type": "object", "description": "For type=media.", "properties": { "kind": { "type": "string", "enum": [ "image", "video", "document", "audio" ] }, "link": { "type": "string" }, "caption": { "type": "string" } } }, "template": { "type": "object", "description": "For type=template.", "properties": { "name": { "type": "string" }, "language": { "type": "string", "default": "en_US" }, "components": { "type": "array", "items": { "type": "object" } } } }, "buttons": { "type": "array", "description": "For type=interactive_buttons. Up to 3 reply buttons; the customer's tap arrives as an inbound message you already receive on your webhook.", "maxItems": 3, "items": { "type": "object", "required": [ "id", "title" ], "properties": { "id": { "type": "string", "description": "Opaque id returned in the customer's tap event." }, "title": { "type": "string", "description": "Button label, max 20 characters." } } } }, "button_text": { "type": "string", "description": "For type=interactive_list. Label on the button that opens the list, max 20 characters." }, "sections": { "type": "array", "description": "For type=interactive_list. Up to 10 rows total across all sections.", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Optional section heading, max 24 characters." }, "rows": { "type": "array", "items": { "type": "object", "required": [ "id", "title" ], "properties": { "id": { "type": "string" }, "title": { "type": "string", "description": "Max 24 characters." }, "description": { "type": "string", "description": "Max 72 characters." } } } } } } }, "location": { "type": "object", "description": "For type=location.", "required": [ "latitude", "longitude" ], "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" }, "name": { "type": "string" }, "address": { "type": "string" } } }, "contacts": { "type": "array", "description": "For type=contacts. WhatsApp's raw contact-card array - see Meta's WhatsApp Cloud API `contacts` message reference for the full object shape (name, phones, emails, etc.).", "items": { "type": "object" } }, "emoji": { "type": "string", "description": "For type=reaction. The emoji to react with, or an empty string to remove a previously-sent reaction. Requires context_message_id." }, "flow": { "type": "object", "description": "For type=flow.", "required": [ "id", "cta" ], "properties": { "id": { "type": "string", "description": "A PUBLISHED flow's id." }, "cta": { "type": "string", "description": "Text on the button that opens the flow, max 20 characters." }, "token": { "type": "string", "description": "Opaque token you supply to correlate this send with the flow's response/completion webhook. Auto-generated if omitted." }, "action": { "type": "string", "enum": [ "navigate", "data_exchange" ], "default": "navigate", "description": "navigate opens a specific screen directly; data_exchange hands the first screen to your flow endpoint to decide." }, "action_payload": { "type": "object", "description": "Required when action=navigate.", "properties": { "screen": { "type": "string", "description": "The screen id to open." }, "data": { "type": "object", "description": "Fields to pre-populate on that screen." } } }, "mode": { "type": "string", "enum": [ "draft", "published" ], "description": "Defaults to published. Use draft only while testing an unpublished flow with your own test numbers." } } }, "category": { "type": "string", "enum": [ "marketing", "utility", "authentication", "service" ], "description": "Pricing category for a template send. Optional - if omitted we read it from the template itself. Free-form sends are always billed as `service`." } } }, "examples": { "text": { "summary": "Text (session)", "value": { "account_id": 42, "to": "+14155551234", "type": "text", "text": "Thanks for reaching out!" } }, "threaded_reply": { "summary": "Text, threaded as a reply", "value": { "account_id": 42, "to": "+14155551234", "type": "text", "text": "Yes, that ships tomorrow.", "context_message_id": "wamid.HBgLMTU1NTU1NTU1NTUVAgARGBI5QTM2RUQ4RkQ2QjM4RjQ4QjQA" } }, "interactive_buttons": { "summary": "Interactive buttons", "value": { "account_id": 42, "to": "+14155551234", "type": "interactive_buttons", "text": "Your order #A1234 is ready. What would you like to do?", "buttons": [ { "id": "confirm", "title": "Confirm" }, { "id": "reschedule", "title": "Reschedule" }, { "id": "cancel", "title": "Cancel" } ] } }, "interactive_list": { "summary": "Interactive list", "value": { "account_id": 42, "to": "+14155551234", "type": "interactive_list", "text": "Pick a time slot for your appointment.", "button_text": "View slots", "sections": [ { "title": "Tomorrow", "rows": [ { "id": "slot_10", "title": "10:00 AM", "description": "45 min available" }, { "id": "slot_14", "title": "2:00 PM", "description": "45 min available" } ] } ] } }, "location": { "summary": "Location pin", "value": { "account_id": 42, "to": "+14155551234", "type": "location", "location": { "latitude": 37.7749, "longitude": -122.4194, "name": "Store pickup counter", "address": "123 Market St, San Francisco, CA" } } }, "contacts": { "summary": "Contact card", "value": { "account_id": 42, "to": "+14155551234", "type": "contacts", "contacts": [ { "name": { "formatted_name": "Support Team", "first_name": "Support" }, "phones": [ { "phone": "+14155550188", "type": "WORK" } ] } ] } }, "reaction": { "summary": "React to a message", "value": { "account_id": 42, "to": "+14155551234", "type": "reaction", "context_message_id": "wamid.HBgLMTU1NTU1NTU1NTUVAgARGBI5QTM2RUQ4RkQ2QjM4RjQ4QjQA", "emoji": "👍" } }, "flow": { "summary": "Open a Flow", "value": { "account_id": 42, "to": "+14155551234", "type": "flow", "text": "Book your appointment in a few taps.", "flow": { "id": "1234567890123456", "cta": "Book now", "action": "navigate", "action_payload": { "screen": "APPOINTMENT", "data": {} } } } } } } } }, "responses": { "201": { "description": "Sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "message_id": { "type": "string", "nullable": true }, "status": { "type": "string" }, "pricing": { "type": "object", "description": "What this send was priced at.", "properties": { "category": { "type": "string", "description": "Category actually billed." }, "market": { "type": "string", "description": "Market the destination resolved to." }, "calling_code": { "type": "string", "description": "Country calling code matched." }, "rate": { "type": "string", "description": "USD charged for this message." } } } } }, "usage": { "type": "object" } } }, "example": { "success": true, "data": { "message_id": "wamid.HBg...", "status": "sent", "pricing": { "category": "utility", "market": "United States", "calling_code": "1", "rate": "0.003600" } }, "usage": { "units": 1, "cost": "0.0036", "balance_remaining": "24.9964" } } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "404": { "$ref": "#/components/responses/NotFound" }, "502": { "description": "WhatsApp rejected the message (e.g. outside the 24h window with no template)." } } } }, "/whatsapp/templates": { "get": { "summary": "List message templates", "operationId": "listWhatsAppTemplates", "description": "List the WhatsApp Business Account's message templates. Requires social:read.", "tags": [ "WhatsApp" ], "parameters": [ { "name": "account_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "A connected WhatsApp number (social account id)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50 } } ], "responses": { "200": { "description": "Templates", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Create a message template", "operationId": "createWhatsAppTemplate", "description": "Submit a message template to Meta for approval. Requires social:write.", "tags": [ "WhatsApp" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "account_id", "name", "category", "language", "components" ], "properties": { "account_id": { "type": "integer" }, "name": { "type": "string" }, "category": { "type": "string", "enum": [ "MARKETING", "UTILITY", "AUTHENTICATION" ] }, "language": { "type": "string", "example": "en_US" }, "components": { "type": "array", "items": { "type": "object" }, "description": "Header/body/footer/buttons per the WhatsApp template schema." } } } } } }, "responses": { "201": { "description": "Submitted for approval", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/whatsapp/business-profile": { "get": { "summary": "Get business profile", "operationId": "getWhatsAppBusinessProfile", "description": "Read the number's WhatsApp business profile. Requires social:read.", "tags": [ "WhatsApp" ], "parameters": [ { "name": "account_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "A connected WhatsApp number (social account id)." } ], "responses": { "200": { "description": "Profile", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "summary": "Update business profile", "operationId": "updateWhatsAppBusinessProfile", "description": "Update about/address/email/description/vertical/websites on the number's profile. Requires social:write.", "tags": [ "WhatsApp" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "account_id" ], "properties": { "account_id": { "type": "integer" }, "about": { "type": "string" }, "address": { "type": "string" }, "email": { "type": "string" }, "description": { "type": "string" }, "vertical": { "type": "string" }, "websites": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Updated" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/whatsapp/phone-numbers": { "get": { "summary": "List phone numbers", "operationId": "listWhatsAppPhoneNumbers", "description": "List the phone numbers on this connection's WhatsApp Business Account. Requires social:read.", "tags": [ "WhatsApp" ], "parameters": [ { "name": "account_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "A connected WhatsApp number (social account id)." } ], "responses": { "200": { "description": "Numbers", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/whatsapp/flows": { "get": { "summary": "List flows", "operationId": "listWhatsAppFlows", "description": "List the WhatsApp Flows on this connection's WhatsApp Business Account. Requires social:read.", "tags": [ "WhatsApp" ], "parameters": [ { "name": "account_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "A connected WhatsApp number (social account id)." } ], "responses": { "200": { "description": "Flows", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "flows": { "type": "array", "items": { "$ref": "#/components/schemas/WhatsAppFlow" } } } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Create a flow", "operationId": "createWhatsAppFlow", "description": "Create a new WhatsApp Flow in DRAFT status. Optionally clone an existing flow with clone_flow_id. A freshly created flow has no screens - upload a Flow JSON definition next (PUT /whatsapp/flows/{flow_id}/json), then publish it. Requires social:write.", "tags": [ "WhatsApp" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "account_id", "name", "categories" ], "properties": { "account_id": { "type": "integer", "description": "A connected WhatsApp number (social account id)." }, "name": { "type": "string" }, "categories": { "type": "array", "description": "At least one, e.g. SIGN_UP, APPOINTMENT_BOOKING, SURVEY, LEAD_GENERATION, CONTACT_US, CUSTOMER_SUPPORT, OTHER.", "items": { "type": "string" } }, "clone_flow_id": { "type": "string", "description": "An existing flow id to clone instead of starting blank." } } }, "example": { "account_id": 42, "name": "Book an appointment", "categories": [ "APPOINTMENT_BOOKING" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "validation_errors": { "type": "array", "items": { "type": "object" } } } } } } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/whatsapp/flows/{flow_id}": { "get": { "summary": "Get flow", "operationId": "getWhatsAppFlow", "description": "Get a flow's details: status, categories, validation errors, and the endpoint URI (for data_exchange flows). Requires social:read.", "tags": [ "WhatsApp" ], "parameters": [ { "name": "flow_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "A connected WhatsApp number (social account id)." } ], "responses": { "200": { "description": "Flow", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "flow": { "$ref": "#/components/schemas/WhatsAppFlow" } } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "summary": "Update flow", "operationId": "updateWhatsAppFlow", "description": "Update a DRAFT flow's name, categories, or endpoint_uri. Published flows are immutable - create a new flow to change one. Requires social:write.", "tags": [ "WhatsApp" ], "parameters": [ { "name": "flow_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "account_id" ], "properties": { "account_id": { "type": "integer" }, "name": { "type": "string" }, "categories": { "type": "array", "items": { "type": "string" } }, "endpoint_uri": { "type": "string" } } } } } }, "responses": { "200": { "description": "Updated" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "summary": "Delete flow", "operationId": "deleteWhatsAppFlow", "description": "Delete a DRAFT flow. Irreversible. Published flows can't be deleted, only deprecated. Requires social:write.", "tags": [ "WhatsApp" ], "parameters": [ { "name": "flow_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "A connected WhatsApp number (social account id)." } ], "responses": { "200": { "description": "Deleted" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/whatsapp/flows/{flow_id}/json": { "put": { "summary": "Upload flow JSON", "operationId": "uploadWhatsAppFlowJson", "description": "Upload or replace a DRAFT flow's Flow JSON - the screens, components, and navigation that define the form. Meta validates on upload; the response's validation_errors comes back either way, so a successful upload doesn't guarantee the flow is publishable yet. Requires social:write.", "tags": [ "WhatsApp" ], "parameters": [ { "name": "flow_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "account_id", "flow_json" ], "properties": { "account_id": { "type": "integer" }, "flow_json": { "type": "object", "description": "The Flow JSON document. See Meta's WhatsApp Flows JSON reference for the schema of screens/components/actions." } } }, "example": { "account_id": 42, "flow_json": { "version": "6.0", "screens": [ { "id": "APPOINTMENT", "title": "Book appointment", "terminal": true, "layout": { "type": "SingleColumnLayout", "children": [] } } ] } } } } }, "responses": { "200": { "description": "Uploaded", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "uploaded": { "type": "boolean" }, "validation_errors": { "type": "array", "items": { "type": "object" } } } } } } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "WhatsApp rejected the upload." } } }, "get": { "summary": "Get flow JSON asset", "operationId": "getWhatsAppFlowJson", "description": "Get the uploaded Flow JSON asset's metadata, including a temporary download URL. Requires social:read.", "tags": [ "WhatsApp" ], "parameters": [ { "name": "flow_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "A connected WhatsApp number (social account id)." } ], "responses": { "200": { "description": "Assets", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/whatsapp/flows/{flow_id}/preview": { "get": { "summary": "Get flow preview URL", "operationId": "getWhatsAppFlowPreview", "description": "Get Meta's web-preview URL for the flow (draft or published), embeddable as an iframe. The URL is reused across calls (valid roughly 30 days) unless invalidate=true mints a fresh one. Requires social:read.", "tags": [ "WhatsApp" ], "parameters": [ { "name": "flow_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "A connected WhatsApp number (social account id)." }, { "name": "invalidate", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Mint a fresh preview URL instead of reusing the existing one." } ], "responses": { "200": { "description": "Preview URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "preview_url": { "type": "string", "nullable": true }, "expires_at": { "type": "string", "nullable": true } } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/whatsapp/flows/{flow_id}/publish": { "post": { "summary": "Publish flow", "operationId": "publishWhatsAppFlow", "description": "Publish a DRAFT flow, making it sendable via POST /whatsapp/messages with type=flow. Irreversible - published flows are immutable; to change one, create a new flow. Requires social:write.", "tags": [ "WhatsApp" ], "parameters": [ { "name": "flow_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "account_id" ], "properties": { "account_id": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Published" }, "502": { "description": "The flow failed Meta's publish validation." } } } }, "/whatsapp/flows/{flow_id}/deprecate": { "post": { "summary": "Deprecate flow", "operationId": "deprecateWhatsAppFlow", "description": "Deprecate a published flow, stopping it from being sendable while keeping its submission history and results. Requires social:write.", "tags": [ "WhatsApp" ], "parameters": [ { "name": "flow_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "account_id" ], "properties": { "account_id": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Deprecated" } } } }, "/whatsapp/block-users": { "get": { "summary": "List blocked users", "operationId": "getWhatsAppBlockedUsers", "description": "List the WhatsApp users blocked on this number. Cursor-paginated; the blocklist holds up to 64,000 users. Requires social:read.", "tags": [ "WhatsApp" ], "parameters": [ { "name": "account_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "A connected WhatsApp number (social account id)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50 } }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pagination cursor from the previous page's paging.cursors.after." } ], "responses": { "200": { "description": "Blocked users", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Block users", "operationId": "blockWhatsAppUsers", "description": "Block one or more WhatsApp users on this number. Blocked users can't message your number or see your online status, and your sends to them fail. Meta only allows blocking a user who has messaged your business within the last 24 hours - other targets come back in `failed` without failing the rest of the batch. Up to 1,000 users per request. Requires social:write.", "tags": [ "WhatsApp" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "account_id", "users" ], "properties": { "account_id": { "type": "integer" }, "users": { "type": "array", "description": "Phone numbers in E.164 form.", "items": { "type": "string" } } } }, "example": { "account_id": 42, "users": [ "+14155551234" ] } } } }, "responses": { "200": { "description": "Blocked", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "WhatsApp rejected the request." } } }, "delete": { "summary": "Unblock users", "operationId": "unblockWhatsAppUsers", "description": "Unblock one or more previously blocked WhatsApp users on this number. Up to 1,000 users per request; per-user failures are reported in `failed` without failing the rest of the batch. Requires social:write.", "tags": [ "WhatsApp" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "account_id", "users" ], "properties": { "account_id": { "type": "integer" }, "users": { "type": "array", "description": "Phone numbers in E.164 form.", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Unblocked", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/whatsapp/sandbox/sessions": { "get": { "summary": "List your sandbox sessions", "operationId": "listWhatsAppSandboxSessions", "description": "Returns your non-expired sandbox sessions (there is at most one, since it's one phone per user) plus the shared sandbox number in E.164. `503 SANDBOX_UNAVAILABLE` if the platform hasn't configured a sandbox number yet. Requires social:read.", "tags": [ "WhatsApp" ], "responses": { "200": { "description": "Sessions", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/WhatsAppSandboxSession" } }, "sandbox_number": { "type": "string", "nullable": true } } } } } } } }, "503": { "description": "The sandbox is not configured on this platform." } } }, "post": { "summary": "Start a sandbox activation", "operationId": "createWhatsAppSandboxSession", "description": "Creates (or refreshes) a pending sandbox session for `phone` and immediately fires the locked sandbox template from the shared number to it. The session activates when the phone owner replies to that WhatsApp message - the reply itself proves ownership. Once active, use POST .../sessions/{session_id}/send to re-fire the template and see it land. Limits: 50 sends/24h per user, one phone per user at a time (revoke the existing session before activating a different phone). Requires social:write.", "tags": [ "WhatsApp" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phone" ], "properties": { "phone": { "type": "string", "description": "Phone in E.164 to activate against the sandbox." } } }, "example": { "phone": "+14155551234" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "session": { "$ref": "#/components/schemas/WhatsAppSandboxSession" }, "sandbox_number": { "type": "string" } } } } } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "503": { "description": "The sandbox is not configured on this platform." } } } }, "/whatsapp/sandbox/sessions/{session_id}": { "delete": { "summary": "Revoke a sandbox session", "operationId": "deleteWhatsAppSandboxSession", "description": "Hard-deletes the session. You lose the ability to send to that phone via the sandbox until you activate it again. Requires social:write.", "tags": [ "WhatsApp" ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Revoked" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/whatsapp/sandbox/sessions/{session_id}/send": { "post": { "summary": "Send the sandbox template", "operationId": "sendWhatsAppSandboxMessage", "description": "Re-fires the locked sandbox template at an ACTIVE session's phone - the only message the sandbox can send, since the template is the only thing pre-approved on the shared number. 422 if the session is still pending (the phone hasn't replied yet) or the daily limit (50/24h) is reached. Requires social:write.", "tags": [ "WhatsApp" ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "201": { "description": "Sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "message_id": { "type": "string", "nullable": true }, "status": { "type": "string" } } } } } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/whatsapp/numbers/{sender_id}/bridge": { "post": { "summary": "Bridge an owned number onto WhatsApp", "operationId": "startWhatsAppNumberBridge", "description": "Adds an already-owned phone number (bought via POST /phone-numbers/purchase) to your connected WhatsApp Business Account. Requires an existing WhatsApp connection (Settings > WhatsApp) - this adds a number to it, it does not create one - and SMS or voice capability on the number to receive Meta's verification code. Next: POST .../bridge/request-code. Requires social:write.", "tags": [ "WhatsApp" ], "parameters": [ { "name": "sender_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The id returned by POST /phone-numbers/purchase." } ], "responses": { "201": { "description": "Bridge started", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "phone_number_id": { "type": "string" }, "bridge_status": { "type": "string", "enum": [ "pending_code" ] } } } } } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "get": { "summary": "Bridge status", "operationId": "getWhatsAppNumberBridgeStatus", "description": "Where the bridge is in Meta's add -> request_code -> verify_code -> register sequence. Requires social:read.", "tags": [ "WhatsApp" ], "parameters": [ { "name": "sender_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Status", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "bridge_status": { "type": "string", "enum": [ "none", "pending_code", "pending_register", "linked" ] }, "phone_number_id": { "type": "string", "nullable": true } } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/whatsapp/numbers/{sender_id}/bridge/request-code": { "post": { "summary": "Request a verification code", "operationId": "requestWhatsAppNumberBridgeCode", "description": "Meta sends a code to the number ITSELF, by SMS or a voice call - not to you. Check the number's inbound SMS/call log in SmartlyQ to read it. Requires social:write.", "tags": [ "WhatsApp" ], "parameters": [ { "name": "sender_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "sms", "voice" ], "default": "sms" } } } } } }, "responses": { "200": { "description": "Requested" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/whatsapp/numbers/{sender_id}/bridge/verify": { "post": { "summary": "Submit the verification code", "operationId": "verifyWhatsAppNumberBridge", "description": "Submits the code, completes Cloud API registration, and connects the number - after this succeeds it behaves like any other connected WhatsApp number (POST /whatsapp/messages with its account_id, etc). Requires social:write.", "tags": [ "WhatsApp" ], "parameters": [ { "name": "sender_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" } } } } } }, "responses": { "200": { "description": "Linked", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "linked": { "type": "boolean" }, "account": { "type": "object" } } } } } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/logs": { "get": { "summary": "List developer logs", "operationId": "listLogs", "tags": [ "Logs" ], "description": "Your workspace's own request history: API calls and webhook delivery attempts merged into one time-ordered feed, newest first, with 90-day retention. `source` tells the two apart and decides which fields are populated - API rows carry method/endpoint/timing/cost, webhook rows carry event/attempt/status.\n\nRequest and response bodies are omitted unless you pass `include_payloads=true`: they contain whatever was sent, so they are opt-in rather than returned in every page.\n\nRequires scope `logs:read`.", "parameters": [ { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "api", "webhook" ] }, "description": "Limit to one stream." }, { "name": "endpoint", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Substring match on the endpoint path (API rows) or event name (webhook rows)." }, { "name": "status_code", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Exact HTTP status. Pins results to API rows." }, { "name": "result", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "errors", "success" ] }, "description": "Only failures, or only successes." }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Activity type filter, e.g. social, images, videos." }, { "name": "platform", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated platform filter, e.g. facebook,instagram." }, { "name": "api_key_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Limit to one API key. Pins results to API rows." }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Start of the window (YYYY-MM-DD or a date-time)." }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string" }, "description": "End of the window (YYYY-MM-DD or a date-time)." }, { "name": "include_payloads", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Include request/response bodies. Off by default." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 }, "description": "" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100 }, "description": "" } ], "responses": { "200": { "description": "Log feed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "source": { "type": "string", "enum": [ "api", "webhook" ], "description": "Which stream the row came from." }, "created_at": { "type": "string", "format": "date-time" }, "activity_type": { "type": "string", "nullable": true }, "platform": { "type": "string", "nullable": true }, "account_ref": { "type": "string", "nullable": true }, "status_code": { "type": "integer", "nullable": true }, "method": { "type": "string", "nullable": true, "description": "API rows only." }, "endpoint": { "type": "string", "nullable": true, "description": "API rows only." }, "response_time": { "type": "integer", "nullable": true, "description": "Milliseconds. API rows only." }, "units_used": { "type": "integer", "nullable": true, "description": "API rows only." }, "cost": { "type": "string", "nullable": true, "description": "USD charged. API rows only." }, "api_key_id": { "type": "integer", "nullable": true, "description": "API rows only." }, "request_id": { "type": "string", "nullable": true, "description": "API rows only." }, "ip_address": { "type": "string", "nullable": true, "description": "API rows only." }, "user_agent": { "type": "string", "nullable": true, "description": "API rows only." }, "is_test": { "type": "boolean", "description": "API rows only." }, "event": { "type": "string", "nullable": true, "description": "Webhook rows only, e.g. post.published." }, "attempt": { "type": "integer", "nullable": true, "description": "Webhook rows only." }, "status": { "type": "string", "nullable": true, "description": "Webhook rows only: pending, delivered or dead_letter." }, "next_retry_at": { "type": "string", "nullable": true, "description": "Webhook rows only." }, "request_payload": { "description": "Only when include_payloads=true.", "nullable": true }, "response_payload": { "description": "Only when include_payloads=true.", "nullable": true } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/webhooks/deliveries/{id}/replay": { "post": { "summary": "Replay a webhook delivery", "operationId": "replayWebhookDelivery", "tags": [ "Webhooks" ], "description": "Re-queue a past delivery so it is sent again - the fix-up after your receiver was down or rejecting. The original event and payload are replayed unchanged and signed afresh, and the attempt counter resets so retry backoff starts clean. Find delivery ids with `GET /webhooks/logs`.\n\nRequires scope `webhooks:write`. Not available under X-Profile-Id delegation.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Delivery id from GET /webhooks/logs." } ], "responses": { "202": { "description": "Delivery re-queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "delivery_id": { "type": "integer" }, "status": { "type": "string", "enum": [ "pending" ] } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/urls/{id}": { "patch": { "summary": "Update a short URL", "operationId": "updateShortUrl", "tags": [ "URLs" ], "description": "Repoint an existing short link at a new destination, rename it, or deactivate it. The short code never changes, so links already printed, posted or scanned keep working and their click history stays attached.\n\nSend only the fields you want to change. Free - the link was already charged for at creation. Requires scope `urls:write`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "New destination URL." }, "title": { "type": "string", "description": "New label. Send an empty string to clear it." }, "is_active": { "type": "boolean", "description": "Set false to stop the link resolving." } } } } } }, "responses": { "200": { "description": "Updated short URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/social/conversations/{conversation_id}/messages/{message_id}": { "delete": { "summary": "Delete a sent message", "operationId": "deleteMessage", "tags": [ "Direct Messages" ], "description": "Delete a message you sent. X and Bluesky only - Messenger, Instagram, and WhatsApp have no unsend API for a business-sent message. On Bluesky this deletes for YOUR side of the conversation only (their chat API has no unsend-for-everyone) - a successful response's `note` says so explicitly when it applies. Requires scope `social:write`.", "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "message_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Message id from GET /social/conversations/{conversation_id}/messages. Must be a message you sent." } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean" }, "note": { "type": "string", "description": "Present on Bluesky: clarifies the delete was for-self only." } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "success": true }, "meta": { "request_id": "req_abc123", "timestamp": "2026-08-04T16:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/social/conversations/{conversation_id}/messages/{message_id}/reactions": { "post": { "summary": "React to a message", "operationId": "reactToMessage", "tags": [ "Direct Messages" ], "description": "React to a message as the connected account. Sending a different emoji replaces the previous reaction.\n\nSupported on Messenger, Instagram, Bluesky and WhatsApp. Other platforms return an honest error rather than silently doing nothing. Requires scope `social:write`.", "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "message_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Message id from GET /social/conversations/{conversation_id}/messages." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "emoji" ], "properties": { "emoji": { "type": "string", "description": "The emoji to react with." } } } } } }, "responses": { "200": { "description": "Reaction sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean" }, "our_reaction": { "type": "string", "nullable": true } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "summary": "Remove a message reaction", "operationId": "removeMessageReaction", "tags": [ "Direct Messages" ], "description": "Clear the reaction this account previously sent on a message.\n\nSupported on Messenger, Instagram, Bluesky and WhatsApp. Other platforms return an honest error rather than silently doing nothing. Requires scope `social:write`.", "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "message_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Message id from GET /social/conversations/{conversation_id}/messages." } ], "responses": { "200": { "description": "Reaction removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean" }, "our_reaction": { "type": "string", "nullable": true } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/whatsapp/templates/{name}": { "get": { "summary": "Get a WhatsApp template", "operationId": "getWhatsappTemplate", "tags": [ "WhatsApp" ], "description": "One template by name. A template name can hold several rows - one per language - so this returns every translation under that name. Requires scope `social:read`.", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Template name." }, { "name": "account_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "A connected WhatsApp number (social account id)." } ], "responses": { "200": { "description": "Template versions", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "name": { "type": "string" }, "templates": { "type": "array", "items": { "type": "object" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "$ref": "#/components/responses/BadRequest" } } }, "patch": { "summary": "Update a WhatsApp template", "operationId": "updateWhatsappTemplate", "tags": [ "WhatsApp" ], "description": "Replace an existing template's components. Name and language are fixed at creation - changing either means creating a new template. Editing an approved template sends it back through Meta review.\n\nIf the name has more than one language version you must pass `template_id` to say which one to edit; the endpoint refuses to guess. Requires scope `social:write`.", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Template name." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "account_id", "components" ], "properties": { "account_id": { "type": "integer", "description": "A connected WhatsApp number (social account id)." }, "components": { "type": "array", "items": { "type": "object" }, "description": "Full replacement component list, in Meta's template component format." }, "category": { "type": "string", "enum": [ "MARKETING", "UTILITY", "AUTHENTICATION" ], "description": "Optional category change." }, "template_id": { "type": "string", "description": "Required only when the name has several language versions." } } } } } }, "responses": { "200": { "description": "Template updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "name": { "type": "string" }, "template_id": { "type": "string" }, "updated": { "type": "boolean" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "$ref": "#/components/responses/BadRequest" } } }, "delete": { "summary": "Delete a WhatsApp template", "operationId": "deleteWhatsappTemplate", "tags": [ "WhatsApp" ], "description": "Delete a template. Without `template_id` this removes every language version of the name; with it, only that one translation. Requires scope `social:write`.", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Template name." }, { "name": "account_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "A connected WhatsApp number (social account id)." }, { "name": "template_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Delete only this language version." } ], "responses": { "200": { "description": "Template deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "$ref": "#/components/responses/BadRequest" } } } }, "/whatsapp/business-profile/photo": { "post": { "summary": "Set the WhatsApp profile photo", "operationId": "updateWhatsappProfilePhoto", "tags": [ "WhatsApp" ], "description": "Set the profile picture customers see for this number. Meta does not accept an image URL here: upload the file through Meta's resumable upload API first and pass the handle it returns.\n\nRequires scope `social:write`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "account_id", "handle" ], "properties": { "account_id": { "type": "integer", "description": "A connected WhatsApp number (social account id)." }, "handle": { "type": "string", "description": "Media handle from Meta's resumable upload API." } } } } } }, "responses": { "200": { "description": "Photo updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "updated": { "type": "boolean" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "$ref": "#/components/responses/BadRequest" } } } }, "/whatsapp/business-profile/display-name": { "get": { "summary": "Get the WhatsApp display name", "operationId": "getWhatsappDisplayName", "tags": [ "WhatsApp" ], "description": "The name customers see in chat, plus where any pending name change stands with Meta review and the number's current quality rating. Requires scope `social:read`.", "parameters": [ { "name": "account_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "A connected WhatsApp number (social account id)." } ], "responses": { "200": { "description": "Display name", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "display_name": { "type": "string", "nullable": true }, "phone_number": { "type": "string", "nullable": true }, "name_status": { "type": "string", "nullable": true, "description": "Review state of the current name." }, "new_name_status": { "type": "string", "nullable": true, "description": "Review state of a pending change." }, "quality_rating": { "type": "string", "nullable": true } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "summary": "Request a WhatsApp display-name change", "operationId": "updateWhatsappDisplayName", "tags": [ "WhatsApp" ], "description": "Submit a new display name. This does not take effect immediately - Meta reviews it, and the old name stays live until approval, so a 202 here means \"submitted\", not \"changed\". Poll `GET /whatsapp/business-profile/display-name` and watch `name_status`.\n\nRequires scope `social:write`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "account_id", "display_name" ], "properties": { "account_id": { "type": "integer", "description": "A connected WhatsApp number (social account id)." }, "display_name": { "type": "string", "description": "The name to submit for review." } } } } } }, "responses": { "202": { "description": "Change submitted for review", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "submitted": { "type": "boolean" }, "display_name": { "type": "string" }, "note": { "type": "string" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "$ref": "#/components/responses/BadRequest" } } } }, "/analytics/youtube/channel-insights": { "get": { "summary": "YouTube channel insights", "operationId": "getYoutubeChannelInsights", "tags": [ "Analytics" ], "description": "Channel totals for a date range: views, watch time, average view duration and percentage, subscribers gained and lost, likes, dislikes, comments and shares.\n\nThis reads the YouTube Analytics API, which needs its own OAuth permission (`yt-analytics.readonly`). SmartlyQ only began requesting it on 28 July 2026, so channels connected before that answer `403 CONNECTION_SCOPE_MISSING` with `reconnect_required: true` until the account is reconnected. Requires scope `analytics:read`.", "parameters": [ { "name": "account_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "A connected YouTube channel (social account id)." }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Start of the range, YYYY-MM-DD. Defaults to 28 days before end_date." }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string" }, "description": "End of the range, YYYY-MM-DD. Defaults to yesterday." } ], "responses": { "200": { "description": "Report", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "columns": { "type": "array", "items": { "type": "string" }, "description": "Metric/dimension names, in row order." }, "rows": { "type": "array", "items": { "type": "object" }, "description": "One object per row, keyed by column name." }, "start_date": { "type": "string" }, "end_date": { "type": "string" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "$ref": "#/components/responses/BadRequest" } } } }, "/analytics/youtube/daily-views": { "get": { "summary": "YouTube daily views", "operationId": "getYoutubeDailyViews", "tags": [ "Analytics" ], "description": "Views, watch time, average view duration and subscribers gained broken down by day - the shape a time-series chart needs.\n\nThis reads the YouTube Analytics API, which needs its own OAuth permission (`yt-analytics.readonly`). SmartlyQ only began requesting it on 28 July 2026, so channels connected before that answer `403 CONNECTION_SCOPE_MISSING` with `reconnect_required: true` until the account is reconnected. Requires scope `analytics:read`.", "parameters": [ { "name": "account_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "A connected YouTube channel (social account id)." }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Start of the range, YYYY-MM-DD. Defaults to 28 days before end_date." }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string" }, "description": "End of the range, YYYY-MM-DD. Defaults to yesterday." } ], "responses": { "200": { "description": "Report", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "columns": { "type": "array", "items": { "type": "string" }, "description": "Metric/dimension names, in row order." }, "rows": { "type": "array", "items": { "type": "object" }, "description": "One object per row, keyed by column name." }, "start_date": { "type": "string" }, "end_date": { "type": "string" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "$ref": "#/components/responses/BadRequest" } } } }, "/analytics/youtube/video-retention": { "get": { "summary": "YouTube audience retention", "operationId": "getYoutubeVideoRetention", "tags": [ "Analytics" ], "description": "The retention curve for one video: what share of viewers is still watching at each point of the video, plus how that compares with similar videos on YouTube. Rows are ordered by `elapsedVideoTimeRatio`, from 0 (start) to 1 (end).\n\nThis reads the YouTube Analytics API, which needs its own OAuth permission (`yt-analytics.readonly`). SmartlyQ only began requesting it on 28 July 2026, so channels connected before that answer `403 CONNECTION_SCOPE_MISSING` with `reconnect_required: true` until the account is reconnected. Requires scope `analytics:read`.", "parameters": [ { "name": "account_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "A connected YouTube channel (social account id)." }, { "name": "video_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "YouTube video id (the v= value from its URL)." }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Start of the range, YYYY-MM-DD. Defaults to 28 days before end_date." }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string" }, "description": "End of the range, YYYY-MM-DD. Defaults to yesterday." } ], "responses": { "200": { "description": "Report", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "columns": { "type": "array", "items": { "type": "string" }, "description": "Metric/dimension names, in row order." }, "rows": { "type": "array", "items": { "type": "object" }, "description": "One object per row, keyed by column name." }, "start_date": { "type": "string" }, "end_date": { "type": "string" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "$ref": "#/components/responses/BadRequest" } } } }, "/analytics/youtube/demographics": { "get": { "summary": "YouTube viewer demographics", "operationId": "getYoutubeDemographics", "tags": [ "Analytics" ], "description": "Viewer split by age bracket and gender, as a percentage of views. Pass `video_id` to scope it to one video. YouTube withholds demographics below a privacy threshold - that comes back as an empty `rows` array rather than an error.\n\nThis reads the YouTube Analytics API, which needs its own OAuth permission (`yt-analytics.readonly`). SmartlyQ only began requesting it on 28 July 2026, so channels connected before that answer `403 CONNECTION_SCOPE_MISSING` with `reconnect_required: true` until the account is reconnected. Requires scope `analytics:read`.", "parameters": [ { "name": "account_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "A connected YouTube channel (social account id)." }, { "name": "video_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Limit to one video." }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Start of the range, YYYY-MM-DD. Defaults to 28 days before end_date." }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string" }, "description": "End of the range, YYYY-MM-DD. Defaults to yesterday." } ], "responses": { "200": { "description": "Report", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "columns": { "type": "array", "items": { "type": "string" }, "description": "Metric/dimension names, in row order." }, "rows": { "type": "array", "items": { "type": "object" }, "description": "One object per row, keyed by column name." }, "start_date": { "type": "string" }, "end_date": { "type": "string" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "$ref": "#/components/responses/BadRequest" } } } }, "/social/accounts/{account_id}/facebook/page": { "get": { "summary": "Get Facebook page details", "operationId": "getFacebookPage", "tags": [ "Social" ], "description": "The page's own profile - name, about, description, category, contact details, address, opening hours, follower counts and publish state. These are the fields a management screen shows and edits; the performance numbers live on `/facebook/page-insights`.\n\nRequires scope `social:read`. If the account was connected before SmartlyQ requested the permission this call needs, it answers `403 CONNECTION_SCOPE_MISSING` with `reconnect_required: true` - reconnect the account to fix it.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Connected social account id." } ], "responses": { "200": { "description": "Page details", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "page": { "type": "object" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "$ref": "#/components/responses/BadRequest" } } }, "patch": { "summary": "Update Facebook page details", "operationId": "updateFacebookPage", "tags": [ "Social" ], "description": "Edit the page's public details. Send only the fields you want to change.\n\nNeeds the page-metadata permission on the connection. Pages connected through an older flow that never requested it get `reconnect_required` rather than a silent no-op.\n\nRequires scope `social:write`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Connected social account id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "about": { "type": "string", "description": "Short description shown under the page name." }, "description": { "type": "string", "description": "Long description." }, "phone": { "type": "string" }, "website": { "type": "string", "format": "uri" }, "emails": { "type": "array", "items": { "type": "string" } }, "hours": { "type": "object", "description": "Opening hours keyed the way Facebook expects, e.g. mon_1_open / mon_1_close." } } } } } }, "responses": { "200": { "description": "Page updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "updated": { "type": "boolean" }, "fields": { "type": "array", "items": { "type": "string" }, "description": "Fields that were sent." } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "$ref": "#/components/responses/BadRequest" } } } }, "/social/accounts/{account_id}/youtube/playlists/{playlist_id}": { "patch": { "summary": "Update a YouTube playlist", "operationId": "updateYoutubePlaylist", "tags": [ "Social" ], "description": "Rename a playlist, change its description, or change who can see it. Send only what you want to change: YouTube's own update replaces every field you submit, so SmartlyQ reads the playlist first and merges, rather than blanking the fields you left out.\n\nRequires scope `social:write`. If the account was connected before SmartlyQ requested the permission this call needs, it answers `403 CONNECTION_SCOPE_MISSING` with `reconnect_required: true` - reconnect the account to fix it.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Connected social account id." }, { "name": "playlist_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Playlist id from GET /social/accounts/{account_id}/youtube/playlists." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "privacy_status": { "type": "string", "enum": [ "public", "private", "unlisted" ] } } } } } }, "responses": { "200": { "description": "Playlist updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "playlist": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "privacy_status": { "type": "string" } } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "$ref": "#/components/responses/BadRequest" } } } }, "/social/accounts/{account_id}/mentions": { "get": { "summary": "List mentions", "operationId": "listMentions", "tags": [ "Social" ], "description": "Posts where this account was tagged. Facebook pages return posts they were tagged in; Instagram returns media the account was @-mentioned in. X has its own richer endpoint at `/social/accounts/{account_id}/x/mentions`.\n\nRequires scope `social:read`. If the account was connected before SmartlyQ requested the permission this call needs, it answers `403 CONNECTION_SCOPE_MISSING` with `reconnect_required: true` - reconnect the account to fix it.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Connected social account id." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 50 } } ], "responses": { "200": { "description": "Mentions", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "mentions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "platform": { "type": "string" }, "text": { "type": "string" }, "author": { "type": "string", "nullable": true }, "created_at": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true }, "media_url": { "type": "string", "nullable": true } } } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "$ref": "#/components/responses/BadRequest" } } } }, "/social/accounts/{account_id}/mentions/{mention_id}/reply": { "post": { "summary": "Reply to a mention", "operationId": "replyToMention", "tags": [ "Social" ], "description": "Reply publicly to a mention. On Facebook this comments on the tagged post; on Instagram it goes through the mentions edge, which is how Meta expects a business to answer a tag.\n\nRequires scope `social:write`. If the account was connected before SmartlyQ requested the permission this call needs, it answers `403 CONNECTION_SCOPE_MISSING` with `reconnect_required: true` - reconnect the account to fix it.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Connected social account id." }, { "name": "mention_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Mention id from GET /social/accounts/{account_id}/mentions." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } } } } }, "responses": { "201": { "description": "Reply posted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "replied": { "type": "boolean" }, "mention_id": { "type": "string" }, "reply_id": { "type": "string", "nullable": true } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "$ref": "#/components/responses/BadRequest" } } } }, "/social/accounts/{account_id}/reddit/subreddits/{subreddit}/flairs": { "get": { "summary": "List subreddit post flairs", "operationId": "listRedditFlairs", "tags": [ "Social" ], "description": "The post flairs a subreddit offers. Many subreddits reject a submission that has no flair, so read this first and pass the id back as `platform_options.reddit.flair_id` when you post.\n\nSubreddits that expose no flairs, or restrict them to moderators, return an empty list - that is a normal answer, not a failure. Requires scope `social:read`.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Connected social account id." }, { "name": "subreddit", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Subreddit name, with or without the r/ prefix." } ], "responses": { "200": { "description": "Flairs", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "subreddit": { "type": "string" }, "flairs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "text_editable": { "type": "boolean" }, "background_color": { "type": "string", "nullable": true }, "text_color": { "type": "string", "nullable": true }, "mod_only": { "type": "boolean" } } } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "$ref": "#/components/responses/BadRequest" } } } }, "/whatsapp/template-library": { "get": { "summary": "Browse the shared template library", "operationId": "listWhatsappTemplateLibrary", "tags": [ "WhatsApp" ], "description": "Meta's library of prewritten, pre-approved message templates. Adopting one skips the draft-and-wait-for-review cycle, so it is worth browsing before writing a template by hand. Adopt an entry with `POST /whatsapp/templates/from-library`.\n\nRequires scope `social:read`.", "parameters": [ { "name": "account_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "A connected WhatsApp number (social account id)." }, { "name": "topic", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "industry", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 200 } } ], "responses": { "200": { "description": "Library entries", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "templates": { "type": "array", "items": { "type": "object" } }, "paging": { "type": "object", "nullable": true } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "$ref": "#/components/responses/BadRequest" } } } }, "/whatsapp/templates/from-library": { "post": { "summary": "Adopt a library template", "operationId": "createWhatsappTemplateFromLibrary", "tags": [ "WhatsApp" ], "description": "Create a template on your WhatsApp Business Account from a library entry. Meta clones the prewritten body under the name you choose; anything the entry leaves open, such as button URLs, is passed through from this request.\n\nRequires scope `social:write`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "account_id", "library_template_name", "name", "language" ], "properties": { "account_id": { "type": "integer", "description": "A connected WhatsApp number (social account id)." }, "library_template_name": { "type": "string", "description": "Entry name from GET /whatsapp/template-library." }, "name": { "type": "string", "description": "The name your template will have on your WABA." }, "language": { "type": "string", "description": "Language code, e.g. en_US." }, "category": { "type": "string", "enum": [ "MARKETING", "UTILITY", "AUTHENTICATION" ], "default": "UTILITY" }, "library_template_button_inputs": { "type": "array", "items": { "type": "object" }, "description": "Values for buttons the library entry leaves open." }, "message_send_ttl_seconds": { "type": "integer" } } } } } }, "responses": { "201": { "description": "Template created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "name": { "type": "string" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "$ref": "#/components/responses/BadRequest" } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "sqk_live_* or sqk_test_*", "description": "API key from Developer dashboard (Bearer token)." } }, "parameters": { "PageParam": { "name": "page", "in": "query", "description": "Page number (1-based).", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, "PerPageParam": { "name": "per_page", "in": "query", "description": "Items per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, "ArticleIdParam": { "name": "article_id", "in": "path", "required": true, "description": "Article ID (string UUID).", "schema": { "type": "string" } }, "ImageIdParam": { "name": "image_id", "in": "path", "required": true, "description": "Image ID (hex string).", "schema": { "type": "string" } }, "VideoIdParam": { "name": "video_id", "in": "path", "required": true, "description": "The unique video ID (hex string, e.g. 8a3621ff57d6587c4dbb68f6d803f6cc69d8a42b6ae84)", "schema": { "type": "string" } }, "PostIdParam": { "name": "post_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, "AudioIdParam": { "name": "audio_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, "UrlIdParam": { "name": "url_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, "ConversationIdParam": { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string" } }, "ChatbotIdParam": { "name": "id", "in": "path", "required": true, "description": "Chatbot ID.", "schema": { "type": "integer", "format": "int64" } }, "ConvIdParam": { "name": "conv_id", "in": "path", "required": true, "description": "Conversation ID.", "schema": { "type": "integer", "format": "int64" } }, "MediaIdParam": { "name": "media_id", "in": "path", "required": true, "description": "Media ID (string UUID).", "schema": { "type": "string" } }, "AccountIdParam": { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, "JobIdParam": { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } }, "ProfileIdParam": { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Profile id" }, "ProfileHeader": { "name": "X-Profile-Id", "in": "header", "required": false, "schema": { "type": "integer" }, "description": "Act inside a profile (sub-account) you own: data reads and writes target the profile workspace while billing, rate limits and usage stay on your own account. Requires the profiles:manage scope. Returns 404 for profiles you do not own and 409 for paused profiles." } }, "headers": { "X-RateLimit-Limit": { "description": "Max requests per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when window resets.", "schema": { "type": "integer" } }, "X-Request-ID": { "description": "Request ID for support.", "schema": { "type": "string" } } }, "responses": { "BadRequest": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "BAD_REQUEST", "message": "The request body is not valid JSON.", "details": {} }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "Unauthorized": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "INVALID_API_KEY", "message": "Missing or malformed Authorization header", "details": {} }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "InsufficientBalance": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "INSUFFICIENT_BALANCE", "message": "Wallet balance is insufficient for this request", "details": { "required": "0.0250", "balance": "0.0100" } }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "Forbidden": { "description": "Forbidden (scope or access)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "INSUFFICIENT_SCOPE", "message": "API key lacks required scope: social:write", "details": { "required_scope": "social:write" } }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "RESOURCE_NOT_FOUND", "message": "Post not found.", "details": {} }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "Conflict": { "description": "Conflict (e.g. duplicate idempotency or already-finished job)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "CONFLICT", "message": "This resource was modified by another request. Reload and retry.", "details": {} }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "ValidationError": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Missing required fields: content, platforms.", "details": { "fields": [ "content", "platforms" ] } }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "RateLimited": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry after 12 seconds.", "details": { "retry_after": 12 } }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } }, "ServerError": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": { "code": "SERVER_ERROR", "message": "Something went wrong on our side. Retry with the same request_id - it is safe.", "details": {} }, "meta": { "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34", "timestamp": "2026-07-26T09:41:22Z" } } } } } }, "schemas": { "WhatsAppSandboxSession": { "type": "object", "properties": { "id": { "type": "integer" }, "phone": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "active" ] }, "created_at": { "type": "string", "nullable": true }, "activated_at": { "type": "string", "nullable": true }, "expires_at": { "type": "string", "nullable": true } } }, "WhatsAppFlow": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "DRAFT", "PUBLISHED", "DEPRECATED", "BLOCKED", "THROTTLED" ] }, "categories": { "type": "array", "items": { "type": "string" } }, "validation_errors": { "type": "array", "items": { "type": "object" } } } }, "RequestMeta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34" }, "timestamp": { "type": "string", "format": "date-time", "example": "2026-07-26T09:41:22Z" } } }, "UsageMeta": { "type": "object", "properties": { "units": { "type": "integer" }, "cost": { "type": "string", "example": "0.0150" }, "balance_remaining": { "type": "string", "example": "99.9850" } } }, "PaginationMeta": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "pages": { "type": "integer" } } }, "ErrorResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "SuccessEnvelope": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": {}, "usage": { "$ref": "#/components/schemas/UsageMeta" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "PaginatedList": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": {} }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "ArticleGenerateRequest": { "type": "object", "description": "Either `topic` or `keywords` must be provided.", "properties": { "topic": { "type": "string", "description": "Article topic" }, "keywords": { "type": "string", "description": "Keywords to base the article on" }, "tone": { "type": "string", "description": "Writing tone (e.g. professional, casual, friendly)" }, "length": { "type": "string", "description": "Desired length (e.g. short, medium, long)" }, "language": { "type": "string", "description": "Output language (e.g. en, es, fr)" }, "format": { "type": "string", "description": "Output format (e.g. blog, essay, listicle)" }, "instructions": { "type": "string", "description": "Additional instructions for the AI" } } }, "Article": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "title": { "type": "string" }, "content": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "ArticleListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Article" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "ArticleSingleResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Article" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "ImageGenerateRequest": { "type": "object", "description": "Either `prompt` or `description` must be provided.", "properties": { "prompt": { "type": "string", "description": "Short image generation prompt" }, "description": { "type": "string", "description": "Detailed image description" }, "style": { "type": "string", "description": "Visual style (e.g. photorealistic, illustration, watercolor)" }, "size": { "type": "string", "description": "Image dimensions (e.g. 1024x1024, 1792x1024)" }, "format": { "type": "string", "description": "Output format (e.g. png, jpg, webp)" }, "quality": { "type": "string", "description": "Quality level (e.g. standard, hd)" } } }, "Image": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "url": { "type": "string" }, "prompt": { "type": "string" }, "style": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "ImageListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Image" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "ImageSingleResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Image" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "VideoGenerateRequest": { "type": "object", "required": [ "model", "type" ], "properties": { "model": { "type": "string", "description": "Model identifier. See GET /v1/videos/models for available values.", "example": "kling-v2-1" }, "type": { "type": "string", "enum": [ "text_to_video", "image_to_video" ], "description": "Generation mode. `text_to_video` requires `prompt`. `image_to_video` requires `image_url`; `prompt` is optional motion guidance.", "example": "text_to_video" }, "prompt": { "type": "string", "description": "Text description of the video. Required for text_to_video. Optional for image_to_video. Max length varies per model — see prompt_max_length in /v1/videos/models.", "example": "A lone astronaut walks across a crimson desert at sunset" }, "image_url": { "type": "string", "format": "uri", "description": "Source image URL for image_to_video. Must be a publicly accessible JPEG or PNG.", "example": "https://example.com/my-image.jpg" }, "duration": { "type": "integer", "description": "Video length in seconds. Valid values vary per model — see duration in /v1/videos/models. Defaults to the shortest valid duration.", "example": 10 }, "resolution": { "type": "string", "description": "Output resolution (e.g. 720p, 1080p). Valid values vary per model — see resolution in /v1/videos/models.", "example": "1080p" }, "mode": { "type": "string", "description": "Generation quality mode (e.g. Standard, Professional, Fast). Valid values vary per model — see mode in /v1/videos/models.", "example": "Professional" }, "aspect_ratio": { "type": "string", "description": "Output aspect ratio (e.g. 16:9, 9:16, 1:1). Valid values vary per model — see aspect_ratio in /v1/videos/models.", "example": "16:9" }, "style": { "type": "string", "description": "Visual style preset (e.g. Anime, Cyberpunk). Only supported by some models — see style in /v1/videos/models.", "example": "Anime" }, "movement": { "type": "string", "description": "Camera/subject movement amplitude (Auto, Small, Medium, Large). Only supported by some models — see movement in /v1/videos/models.", "example": "Medium" }, "negative_prompt": { "type": "string", "description": "Elements to suppress in the output. Only supported by some models — see supports_negative_prompt in /v1/videos/models.", "example": "blurry, low quality, watermark" }, "seed": { "type": "integer", "description": "Reproducibility seed. Only supported by some models — see supports_seed in /v1/videos/models.", "example": 42 }, "generate_audio": { "type": "boolean", "description": "Generate ambient audio alongside the video. Only supported by some models — see supports_generate_audio in /v1/videos/models.", "example": false }, "camera_fixed": { "type": "boolean", "description": "Lock the camera position (no camera movement). Only supported by some models — see supports_camera_fixed in /v1/videos/models.", "example": false } } }, "VideoModelParams": { "type": "object", "properties": { "duration": { "type": "array", "items": { "type": "integer" }, "description": "Valid duration values in seconds. Empty array means duration is not configurable." }, "resolution": { "type": "array", "items": { "type": "string" }, "description": "Valid resolution values. Empty array means resolution is not configurable." }, "mode": { "type": "array", "items": { "type": "string" }, "description": "Valid mode values. Empty array means mode is not applicable." }, "aspect_ratio": { "type": "array", "items": { "type": "string" }, "description": "Valid aspect ratio values. Empty array means aspect ratio is not configurable." }, "style": { "type": "array", "items": { "type": "string" }, "description": "Valid style preset values. Empty array means style is not supported." }, "movement": { "type": "array", "items": { "type": "string" }, "description": "Valid movement values. Empty array means movement is not supported." }, "supports_negative_prompt": { "type": "boolean" }, "supports_seed": { "type": "boolean" }, "supports_generate_audio": { "type": "boolean" }, "supports_camera_fixed": { "type": "boolean" }, "prompt_max_length": { "type": "integer", "description": "Maximum prompt length in characters. 0 means no enforced limit." } } }, "VideoModel": { "type": "object", "properties": { "model": { "type": "string", "example": "kling-v2-1" }, "type": { "type": "string", "enum": [ "text_to_video", "image_to_video" ], "example": "text_to_video" }, "params": { "$ref": "#/components/schemas/VideoModelParams" } } }, "VideoModelsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/VideoModel" } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "VideoJobCreatedResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "job_uid": { "type": "string", "description": "Use with GET /v1/jobs/{job_uid} to poll for status.", "example": "job_a1b2c3d4e5f6" }, "status": { "type": "string", "enum": [ "queued" ] } } }, "usage": { "$ref": "#/components/schemas/UsageMeta" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "Video": { "type": "object", "properties": { "id": { "type": "string", "example": "a1b2c3d4e5f6" }, "model": { "type": "string", "example": "kling-v2-1" }, "prompt": { "type": "string" }, "url": { "type": "string", "format": "uri", "description": "CDN URL of the generated video (available once completed)." }, "status": { "type": "integer", "description": "1 = completed, 2 = processing, 0 = failed", "example": 1 }, "created": { "type": "string", "format": "date-time" } } }, "VideoListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Video" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "VideoSingleResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Video" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "JobCreatedResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "job_id": { "type": "string" } } }, "usage": { "$ref": "#/components/schemas/UsageMeta" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "Job": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "cancelled" ] }, "result": { "type": "object" }, "error": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "JobSingleResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Job" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "JobListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Job" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "SocialAccount": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "platform": { "type": "string" }, "name": { "type": "string" } } }, "SocialAccountListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SocialAccount" } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "SocialPostCreateRequest": { "type": "object", "required": [ "content", "platforms", "account_ids" ], "properties": { "content": { "type": "string", "description": "Post text content" }, "platforms": { "type": "array", "items": { "type": "string", "enum": [ "facebook", "instagram", "twitter", "linkedin", "youtube", "tiktok", "gmb", "threads", "bluesky", "tumblr", "telegram", "discord" ] }, "description": "Target platforms. Use `twitter` for X and `gmb` for Google Business. `telegram` posts via the workspace's connected bot (created with @BotFather); `discord` posts via the connected server webhook. Both are connected in the dashboard's Social Accounts page." }, "account_ids": { "type": "array", "items": { "type": "integer" }, "description": "IDs of connected social accounts to post to" }, "media_urls": { "type": "array", "items": { "type": "string" }, "description": "Media URLs to attach to the post" }, "link": { "type": "string", "description": "URL to include with the post" }, "allow_duplicates": { "type": "boolean", "description": "Skip the 24h duplicate-content guard. Without it, content identical to a post created in this workspace in the last 24 hours is rejected with 409 DUPLICATE_CONTENT (and the charge is refunded)." }, "platform_options": { "type": "object", "description": "Per-platform composer options - the same payload the web composer stores; publish handlers read it as-is (unknown keys are ignored, max 20KB). Keyed by platform, e.g. {\"tiktok\": {\"privacy_level\": \"SELF_ONLY\"}, \"instagram\": {\"content\": \"IG-specific caption\"}, \"_thumbnail\": {\"timestamp_ms\": 3000}}. Common keys: per-platform `content` override; tiktok privacy/duet/stitch options; `_thumbnail` custom video cover. See the Platform options guide for every key each platform accepts (privacy, flair, first comments, formatting, AI-disclosure flags, thumbnails and more).", "example": { "tiktok": { "privacy_level": "PUBLIC_TO_EVERYONE" }, "instagram": { "content": "IG-flavored caption ✨" } } } } }, "SocialPostScheduleRequest": { "type": "object", "required": [ "content", "platforms", "account_ids" ], "properties": { "content": { "type": "string", "description": "Post text content" }, "platforms": { "type": "array", "items": { "type": "string", "enum": [ "facebook", "instagram", "twitter", "linkedin", "youtube", "tiktok", "gmb", "threads", "bluesky", "tumblr", "telegram", "discord" ] }, "description": "Target platforms. Use `twitter` for X and `gmb` for Google Business. `telegram` posts via the workspace's connected bot (created with @BotFather); `discord` posts via the connected server webhook. Both are connected in the dashboard's Social Accounts page." }, "account_ids": { "type": "array", "items": { "type": "integer" }, "description": "IDs of connected social accounts" }, "scheduled_time": { "type": "string", "format": "date-time", "description": "When to publish (ISO 8601)" }, "media_urls": { "type": "array", "items": { "type": "string" }, "description": "Media URLs to attach to the post" }, "link": { "type": "string", "description": "URL to include with the post" }, "queue_id": { "type": "integer", "description": "Schedule into a posting queue instead of a fixed time: the queue's next open slot is resolved server-side and the post occupies it. Mutually exclusive with scheduled_time." }, "timezone": { "type": "string", "description": "IANA timezone scheduled_time is expressed in (default UTC). Ignored with queue_id (the queue's own timezone applies)." }, "recycle": { "type": "object", "description": "Evergreen recycling: after this post publishes, the next occurrence is automatically scheduled interval_hours later, repeating until a bound is hit. A bound is REQUIRED - set max_repeats and/or until (no unbounded chains). Stop a chain anytime with DELETE /social/posts/{post_id}/recycle.", "required": [ "interval_hours" ], "properties": { "interval_hours": { "type": "integer", "minimum": 1, "maximum": 8760, "description": "Hours between occurrences (1 to 8760 = 1 year)." }, "max_repeats": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of automatic repeats after the original post." }, "until": { "type": "string", "description": "UTC datetime (Y-m-d H:i:s) after which no further occurrences are scheduled. Must be within 2 years." } } }, "allow_duplicates": { "type": "boolean", "description": "Skip the 24h duplicate-content guard. Without it, content identical to a post created in this workspace in the last 24 hours is rejected with 409 DUPLICATE_CONTENT (and the charge is refunded)." }, "platform_options": { "type": "object", "description": "Per-platform composer options - the same payload the web composer stores; publish handlers read it as-is (unknown keys are ignored, max 20KB). Keyed by platform, e.g. {\"tiktok\": {\"privacy_level\": \"SELF_ONLY\"}, \"instagram\": {\"content\": \"IG-specific caption\"}, \"_thumbnail\": {\"timestamp_ms\": 3000}}. Common keys: per-platform `content` override; tiktok privacy/duet/stitch options; `_thumbnail` custom video cover. Per-platform STAGGER: give any platform its own `scheduled_time` here (interpreted in the request `timezone`) and it publishes at that moment - platforms without one use the request-level scheduled_time. One call, one post per distinct time (response carries `staggered[]` with the created legs). Not combinable with queue_id or recycle.", "example": { "tiktok": { "privacy_level": "PUBLIC_TO_EVERYONE" }, "instagram": { "content": "IG-flavored caption ✨" } } } }, "description": "Schedule request. Provide scheduled_time (with optional timezone) OR queue_id (next open slot), not both." }, "SocialPostUpdateRequest": { "type": "object", "description": "At least one field must be provided.", "properties": { "content": { "type": "string" }, "platforms": { "type": "array", "items": { "type": "string", "enum": [ "facebook", "instagram", "twitter", "linkedin", "youtube", "tiktok", "gmb", "threads", "bluesky", "tumblr", "telegram", "discord" ] }, "description": "Target platforms. Use `twitter` for X and `gmb` for Google Business. `telegram` posts via the workspace's connected bot (created with @BotFather); `discord` posts via the connected server webhook. Both are connected in the dashboard's Social Accounts page." }, "account_ids": { "type": "array", "items": { "type": "integer" } }, "scheduled_time": { "type": "string", "format": "date-time" }, "media_urls": { "type": "array", "items": { "type": "string" } }, "link": { "type": "string" } } }, "SocialPost": { "type": "object", "properties": { "id": { "type": "integer" }, "content": { "type": "string" }, "platforms": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "scheduled_time": { "type": "string", "format": "date-time" }, "published_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "publish_stage": { "type": "string", "nullable": true, "enum": [ "validating", "processing_media", "publishing" ], "description": "Live progress inside a publish run: validating (pre-publish checks), processing_media (auto-transcode inspecting/converting media), publishing (dispatching to platforms). null when the post is idle or has reached a final status." }, "post_urls": { "type": "object", "description": "Per-platform permalinks of the published posts, keyed by platform (arrays of URLs). Two reserved keys: _errors holds per-platform failure reasons (plus _post for a whole-post failure), and _transcodes lists what auto-transcode fixed per platform (e.g. 'Frame rate was 15fps (below the 23fps minimum); raised to 30fps.').", "additionalProperties": true }, "post_ids": { "type": "object", "description": "Per-platform remote post IDs assigned by each platform, keyed by platform.", "additionalProperties": true } } }, "SocialPostResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/SocialPost" }, "usage": { "$ref": "#/components/schemas/UsageMeta" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "SocialPostListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SocialPost" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "SocialPostSingleResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/SocialPost" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "ContentRewriteRequest": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "Text to rewrite" }, "tone": { "type": "string", "description": "Desired tone (e.g. professional, casual)" }, "style": { "type": "string", "description": "Writing style (e.g. concise, elaborate)" }, "language": { "type": "string", "description": "Output language (e.g. en, es)" }, "instructions": { "type": "string", "description": "Additional rewriting instructions" } } }, "ContentRewriteResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "text": { "type": "string" } } }, "usage": { "$ref": "#/components/schemas/UsageMeta" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "TextToSpeechRequest": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "Text to convert to speech" }, "voice": { "type": "string", "description": "Voice to use for synthesis. Defaults to alloy if omitted or invalid.", "enum": [ "alloy", "echo", "fable", "onyx", "nova", "shimmer" ], "default": "alloy" }, "speed": { "type": "number", "description": "Playback speed multiplier (e.g. 0.5, 1.0, 2.0)" } } }, "SpeechToTextRequest": { "type": "object", "required": [ "audio_url" ], "properties": { "audio_url": { "type": "string", "format": "uri", "description": "Publicly accessible direct URL to the audio file (mp3, mp4, mpeg, mpga, m4a, wav, or webm). Must return raw audio bytes — Google Drive, Dropbox, OneDrive, and iCloud share links will not work as they return HTML instead of the file. The URL must be reachable without authentication." }, "language": { "type": "string", "description": "Audio language (e.g. en, es)" } } }, "AudioFile": { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string" }, "duration_seconds": { "type": "number" }, "created_at": { "type": "string", "format": "date-time" } } }, "AudioSingleResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/AudioFile" }, "usage": { "$ref": "#/components/schemas/UsageMeta" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "UrlShortenRequest": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "The long URL to shorten" }, "custom_code": { "type": "string", "description": "Custom short code (optional)" }, "title": { "type": "string", "description": "Display title for the link" }, "expires_at": { "type": "string", "format": "date-time", "description": "Expiration date (ISO 8601)" } } }, "ShortUrl": { "type": "object", "properties": { "id": { "type": "integer" }, "short_url": { "type": "string" }, "long_url": { "type": "string" }, "code": { "type": "string" }, "title": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "UrlSingleResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/ShortUrl" }, "usage": { "$ref": "#/components/schemas/UsageMeta" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "UrlListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ShortUrl" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "UrlStatsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "clicks": { "type": "integer" }, "last_click_at": { "type": "string", "format": "date-time" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "CaptainMessageRequest": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "User message to the AI Captain" }, "conversation_id": { "type": "string", "description": "Continue an existing conversation" } } }, "CaptainMessage": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "CaptainMessageResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "message": { "$ref": "#/components/schemas/CaptainMessage" }, "conversation_id": { "type": "string" } } }, "usage": { "$ref": "#/components/schemas/UsageMeta" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "Conversation": { "type": "object", "properties": { "id": { "type": "string" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/CaptainMessage" } }, "created_at": { "type": "string", "format": "date-time" } } }, "ConversationListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "ConversationSingleResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Conversation" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "MediaItem": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "url": { "type": "string" }, "filename": { "type": "string" }, "size_bytes": { "type": "integer" }, "mime_type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "MediaListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MediaItem" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "MediaSingleResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/MediaItem" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "MediaUploadUrlRequest": { "type": "object", "required": [ "filename", "content_type" ], "properties": { "filename": { "type": "string", "description": "Name of the file to upload" }, "content_type": { "type": "string", "description": "MIME type (e.g. image/png, video/mp4)" } } }, "MediaUploadUrlResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "upload_url": { "type": "string", "description": "Presigned URL to PUT your file to" }, "media_id": { "type": "integer", "format": "int64", "description": "ID of the created media record" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "UserProfileResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "plan": { "type": "string", "description": "Current subscription plan" }, "created_at": { "type": "string", "format": "date-time" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "UsageSummaryResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "total_requests": { "type": "integer" }, "total_credits_used": { "type": "number" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "BalanceResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "balance": { "type": "string", "description": "Total available balance", "example": "100.0000" }, "purchased_balance": { "type": "string", "description": "Credits purchased via top-up", "example": "50.0000" }, "monthly_balance": { "type": "string", "description": "Credits from subscription plan", "example": "50.0000" }, "monthly_reset_at": { "type": "string", "format": "date-time", "description": "When monthly credits reset" }, "currency": { "type": "string", "example": "USD" } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "PresentationSummary": { "type": "object", "properties": { "id": { "type": "string", "example": "cm9x1a2b3c4d5e6f7g8h9" }, "title": { "type": "string", "example": "Q3 Performance Review" }, "slides_count": { "type": "integer", "example": 8 }, "is_public": { "type": "boolean", "example": false }, "theme": { "type": "string", "example": "mystique" }, "total_views": { "type": "integer", "example": 12 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "PresentationDetail": { "type": "object", "properties": { "id": { "type": "string", "example": "cm9x1a2b3c4d5e6f7g8h9" }, "title": { "type": "string", "example": "Q3 Performance Review" }, "slides_count": { "type": "integer", "example": 8 }, "is_public": { "type": "boolean", "example": false }, "theme": { "type": "string", "example": "mystique" }, "total_views": { "type": "integer", "example": 12 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "edit_url": { "type": "string", "example": "https://presentations.smartlyq.com/presentation/cm9x1a2b3c4d5e6f7g8h9" }, "share_url": { "type": [ "string", "null" ], "description": "Public share link - null while the presentation is private.", "example": null } } }, "PresentationListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PresentationSummary" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "Profile": { "type": "object", "properties": { "id": { "type": "integer" }, "workspace_id": { "type": "integer" }, "name": { "type": "string" }, "external_id": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "paused", "deleted" ] }, "paused_for_billing": { "type": "boolean" }, "created_at": { "type": "string" } } } } }, "webhooks": { "post.published": { "post": { "operationId": "webhookPostPublished", "summary": "post.published", "description": "A post published successfully on every platform target. Delivered as a signed HTTP POST; respond with any 2xx to acknowledge. Retries: 5 attempts, exponential backoff, Retry-After honored on 429.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable event id (evt_...). Identical across fan-out and retries; also sent as X-SmartlyQ-Event-Id. Use for deduplication." }, "event": { "type": "string", "const": "post.published" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "post_id": { "type": "integer" }, "status": { "type": "string", "enum": [ "published", "partially_published", "failed" ] }, "platforms": { "type": "array", "description": "Per-platform outcome.", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "success": { "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" } }, "description": "Present only on failed platforms (normalized error catalog shape)." } }, "required": [ "platform", "success" ] } } }, "required": [ "post_id", "status", "platforms" ] } }, "required": [ "id", "event", "created_at", "data" ], "description": "Delivery envelope. Signed via X-SmartlyQ-Signature (t=,v1=HMAC-SHA256(ts + '.' + raw body)). When the event originated inside a profile workspace, data additionally carries profile_id and profile_workspace_id." } } } }, "responses": { "200": { "description": "Acknowledged. Any 2xx status is treated as delivered." } } } }, "post.partial": { "post": { "operationId": "webhookPostPartial", "summary": "post.partial", "description": "A post published on some platforms and failed on others. Delivered as a signed HTTP POST; respond with any 2xx to acknowledge. Retries: 5 attempts, exponential backoff, Retry-After honored on 429.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable event id (evt_...). Identical across fan-out and retries; also sent as X-SmartlyQ-Event-Id. Use for deduplication." }, "event": { "type": "string", "const": "post.partial" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "post_id": { "type": "integer" }, "status": { "type": "string", "enum": [ "published", "partially_published", "failed" ] }, "platforms": { "type": "array", "description": "Per-platform outcome.", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "success": { "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" } }, "description": "Present only on failed platforms (normalized error catalog shape)." } }, "required": [ "platform", "success" ] } } }, "required": [ "post_id", "status", "platforms" ] } }, "required": [ "id", "event", "created_at", "data" ], "description": "Delivery envelope. Signed via X-SmartlyQ-Signature (t=,v1=HMAC-SHA256(ts + '.' + raw body)). When the event originated inside a profile workspace, data additionally carries profile_id and profile_workspace_id." } } } }, "responses": { "200": { "description": "Acknowledged. Any 2xx status is treated as delivered." } } } }, "post.failed": { "post": { "operationId": "webhookPostFailed", "summary": "post.failed", "description": "A post failed on every platform target. Delivered as a signed HTTP POST; respond with any 2xx to acknowledge. Retries: 5 attempts, exponential backoff, Retry-After honored on 429.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable event id (evt_...). Identical across fan-out and retries; also sent as X-SmartlyQ-Event-Id. Use for deduplication." }, "event": { "type": "string", "const": "post.failed" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "post_id": { "type": "integer" }, "status": { "type": "string", "enum": [ "published", "partially_published", "failed" ] }, "platforms": { "type": "array", "description": "Per-platform outcome.", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "success": { "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" } }, "description": "Present only on failed platforms (normalized error catalog shape)." } }, "required": [ "platform", "success" ] } } }, "required": [ "post_id", "status", "platforms" ] } }, "required": [ "id", "event", "created_at", "data" ], "description": "Delivery envelope. Signed via X-SmartlyQ-Signature (t=,v1=HMAC-SHA256(ts + '.' + raw body)). When the event originated inside a profile workspace, data additionally carries profile_id and profile_workspace_id." } } } }, "responses": { "200": { "description": "Acknowledged. Any 2xx status is treated as delivered." } } } }, "account.connected": { "post": { "operationId": "webhookAccountConnected", "summary": "account.connected", "description": "A social account was connected or reactivated. Delivered as a signed HTTP POST; respond with any 2xx to acknowledge. Retries: 5 attempts, exponential backoff, Retry-After honored on 429.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable event id (evt_...). Identical across fan-out and retries; also sent as X-SmartlyQ-Event-Id. Use for deduplication." }, "event": { "type": "string", "const": "account.connected" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "account_id": { "type": "integer" }, "platform": { "type": "string" }, "account_name": { "type": "string" }, "account_username": { "type": "string" } }, "required": [ "account_id", "platform" ] } }, "required": [ "id", "event", "created_at", "data" ], "description": "Delivery envelope. Signed via X-SmartlyQ-Signature (t=,v1=HMAC-SHA256(ts + '.' + raw body)). When the event originated inside a profile workspace, data additionally carries profile_id and profile_workspace_id." } } } }, "responses": { "200": { "description": "Acknowledged. Any 2xx status is treated as delivered." } } } }, "account.disconnected": { "post": { "operationId": "webhookAccountDisconnected", "summary": "account.disconnected", "description": "A social account's connection was revoked or invalidated. Delivered as a signed HTTP POST; respond with any 2xx to acknowledge. Retries: 5 attempts, exponential backoff, Retry-After honored on 429.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable event id (evt_...). Identical across fan-out and retries; also sent as X-SmartlyQ-Event-Id. Use for deduplication." }, "event": { "type": "string", "const": "account.disconnected" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "account_id": { "type": "integer" }, "platform": { "type": "string" }, "account_name": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "account_id", "platform", "reason" ] } }, "required": [ "id", "event", "created_at", "data" ], "description": "Delivery envelope. Signed via X-SmartlyQ-Signature (t=,v1=HMAC-SHA256(ts + '.' + raw body)). When the event originated inside a profile workspace, data additionally carries profile_id and profile_workspace_id." } } } }, "responses": { "200": { "description": "Acknowledged. Any 2xx status is treated as delivered." } } } }, "account.token_expired": { "post": { "operationId": "webhookAccountTokenExpired", "summary": "account.token_expired", "description": "A social account's token expired; reconnect to resume. Delivered as a signed HTTP POST; respond with any 2xx to acknowledge. Retries: 5 attempts, exponential backoff, Retry-After honored on 429.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable event id (evt_...). Identical across fan-out and retries; also sent as X-SmartlyQ-Event-Id. Use for deduplication." }, "event": { "type": "string", "const": "account.token_expired" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "account_id": { "type": "integer" }, "platform": { "type": "string" }, "account_name": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "account_id", "platform", "reason" ] } }, "required": [ "id", "event", "created_at", "data" ], "description": "Delivery envelope. Signed via X-SmartlyQ-Signature (t=,v1=HMAC-SHA256(ts + '.' + raw body)). When the event originated inside a profile workspace, data additionally carries profile_id and profile_workspace_id." } } } }, "responses": { "200": { "description": "Acknowledged. Any 2xx status is treated as delivered." } } } }, "comment.received": { "post": { "operationId": "webhookCommentReceived", "summary": "comment.received", "description": "A new comment was ingested on one of your posts. Delivered as a signed HTTP POST; respond with any 2xx to acknowledge. Retries: 5 attempts, exponential backoff, Retry-After honored on 429.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable event id (evt_...). Identical across fan-out and retries; also sent as X-SmartlyQ-Event-Id. Use for deduplication." }, "event": { "type": "string", "const": "comment.received" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "platform": { "type": "string" }, "account_id": { "type": "integer" }, "social_post_id": { "type": [ "integer", "null" ], "description": "SmartlyQ post id; null when the comment is on an external post." }, "remote_post_id": { "type": "string" }, "remote_comment_id": { "type": "string" }, "author_name": { "type": "string" }, "content": { "type": "string" }, "is_reply": { "type": "boolean" }, "commented_at": { "type": "string" } }, "required": [ "platform", "account_id", "remote_comment_id", "content" ] } }, "required": [ "id", "event", "created_at", "data" ], "description": "Delivery envelope. Signed via X-SmartlyQ-Signature (t=,v1=HMAC-SHA256(ts + '.' + raw body)). When the event originated inside a profile workspace, data additionally carries profile_id and profile_workspace_id." } } } }, "responses": { "200": { "description": "Acknowledged. Any 2xx status is treated as delivered." } } } }, "message.received": { "post": { "operationId": "webhookMessageReceived", "summary": "message.received", "description": "A new incoming direct message was ingested. Delivered as a signed HTTP POST; respond with any 2xx to acknowledge. Retries: 5 attempts, exponential backoff, Retry-After honored on 429.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable event id (evt_...). Identical across fan-out and retries; also sent as X-SmartlyQ-Event-Id. Use for deduplication." }, "event": { "type": "string", "const": "message.received" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "platform": { "type": "string" }, "account_name": { "type": "string" }, "conversation_id": { "type": "integer" }, "message_id": { "type": "integer" }, "remote_message_id": { "type": "string" }, "sender_name": { "type": "string" }, "content": { "type": "string" }, "sent_at": { "type": "string" } }, "required": [ "platform", "conversation_id", "message_id" ] } }, "required": [ "id", "event", "created_at", "data" ], "description": "Delivery envelope. Signed via X-SmartlyQ-Signature (t=,v1=HMAC-SHA256(ts + '.' + raw body)). When the event originated inside a profile workspace, data additionally carries profile_id and profile_workspace_id." } } } }, "responses": { "200": { "description": "Acknowledged. Any 2xx status is treated as delivered." } } } }, "job.completed": { "post": { "operationId": "webhookJobCompleted", "summary": "job.completed", "description": "An async job finished successfully. Delivered as a signed HTTP POST; respond with any 2xx to acknowledge. Retries: 5 attempts, exponential backoff, Retry-After honored on 429.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable event id (evt_...). Identical across fan-out and retries; also sent as X-SmartlyQ-Event-Id. Use for deduplication." }, "event": { "type": "string", "const": "job.completed" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "job_id": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string", "enum": [ "completed" ] } }, "required": [ "job_id", "type", "status" ] } }, "required": [ "id", "event", "created_at", "data" ], "description": "Delivery envelope. Signed via X-SmartlyQ-Signature (t=,v1=HMAC-SHA256(ts + '.' + raw body)). When the event originated inside a profile workspace, data additionally carries profile_id and profile_workspace_id." } } } }, "responses": { "200": { "description": "Acknowledged. Any 2xx status is treated as delivered." } } } }, "job.failed": { "post": { "operationId": "webhookJobFailed", "summary": "job.failed", "description": "An async job failed. Delivered as a signed HTTP POST; respond with any 2xx to acknowledge. Retries: 5 attempts, exponential backoff, Retry-After honored on 429.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable event id (evt_...). Identical across fan-out and retries; also sent as X-SmartlyQ-Event-Id. Use for deduplication." }, "event": { "type": "string", "const": "job.failed" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "job_id": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string", "enum": [ "failed" ] }, "error": { "type": "string" } }, "required": [ "job_id", "type", "status" ] } }, "required": [ "id", "event", "created_at", "data" ], "description": "Delivery envelope. Signed via X-SmartlyQ-Signature (t=,v1=HMAC-SHA256(ts + '.' + raw body)). When the event originated inside a profile workspace, data additionally carries profile_id and profile_workspace_id." } } } }, "responses": { "200": { "description": "Acknowledged. Any 2xx status is treated as delivered." } } } }, "balance.low": { "post": { "operationId": "webhookBalanceLow", "summary": "balance.low", "description": "Wallet balance crossed below the low threshold. Delivered as a signed HTTP POST; respond with any 2xx to acknowledge. Retries: 5 attempts, exponential backoff, Retry-After honored on 429.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable event id (evt_...). Identical across fan-out and retries; also sent as X-SmartlyQ-Event-Id. Use for deduplication." }, "event": { "type": "string", "const": "balance.low" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "balance": { "type": "number" }, "threshold": { "type": "number" } }, "required": [ "balance", "threshold" ] } }, "required": [ "id", "event", "created_at", "data" ], "description": "Delivery envelope. Signed via X-SmartlyQ-Signature (t=,v1=HMAC-SHA256(ts + '.' + raw body)). When the event originated inside a profile workspace, data additionally carries profile_id and profile_workspace_id." } } } }, "responses": { "200": { "description": "Acknowledged. Any 2xx status is treated as delivered." } } } }, "balance.depleted": { "post": { "operationId": "webhookBalanceDepleted", "summary": "balance.depleted", "description": "Wallet balance reached zero. Delivered as a signed HTTP POST; respond with any 2xx to acknowledge. Retries: 5 attempts, exponential backoff, Retry-After honored on 429.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable event id (evt_...). Identical across fan-out and retries; also sent as X-SmartlyQ-Event-Id. Use for deduplication." }, "event": { "type": "string", "const": "balance.depleted" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "balance": { "type": "number" } }, "required": [ "balance" ] } }, "required": [ "id", "event", "created_at", "data" ], "description": "Delivery envelope. Signed via X-SmartlyQ-Signature (t=,v1=HMAC-SHA256(ts + '.' + raw body)). When the event originated inside a profile workspace, data additionally carries profile_id and profile_workspace_id." } } } }, "responses": { "200": { "description": "Acknowledged. Any 2xx status is treated as delivered." } } } }, "key.revoked": { "post": { "operationId": "webhookKeyRevoked", "summary": "key.revoked", "description": "An API key was revoked. Delivered as a signed HTTP POST; respond with any 2xx to acknowledge. Retries: 5 attempts, exponential backoff, Retry-After honored on 429.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable event id (evt_...). Identical across fan-out and retries; also sent as X-SmartlyQ-Event-Id. Use for deduplication." }, "event": { "type": "string", "const": "key.revoked" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "key_id": { "type": "integer" }, "key_prefix": { "type": "string" }, "name": { "type": "string" } }, "required": [ "key_id" ] } }, "required": [ "id", "event", "created_at", "data" ], "description": "Delivery envelope. Signed via X-SmartlyQ-Signature (t=,v1=HMAC-SHA256(ts + '.' + raw body)). When the event originated inside a profile workspace, data additionally carries profile_id and profile_workspace_id." } } } }, "responses": { "200": { "description": "Acknowledged. Any 2xx status is treated as delivered." } } } }, "wallet.recharge.succeeded": { "post": { "operationId": "webhookWalletRechargeSucceeded", "summary": "wallet.recharge.succeeded", "description": "Auto-recharge charged your card and credited the wallet. Delivered as a signed HTTP POST; respond with any 2xx to acknowledge. Retries: 5 attempts, exponential backoff, Retry-After honored on 429.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable event id (evt_...). Identical across fan-out and retries; also sent as X-SmartlyQ-Event-Id. Use for deduplication." }, "event": { "type": "string", "const": "wallet.recharge.succeeded" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string" }, "balance_after": { "type": [ "number", "null" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "id", "event", "created_at", "data" ], "description": "Delivery envelope. Signed via X-SmartlyQ-Signature (t=,v1=HMAC-SHA256(ts + '.' + raw body)). When the event originated inside a profile workspace, data additionally carries profile_id and profile_workspace_id." } } } }, "responses": { "200": { "description": "Acknowledged. Any 2xx status is treated as delivered." } } } }, "wallet.recharge.failed": { "post": { "operationId": "webhookWalletRechargeFailed", "summary": "wallet.recharge.failed", "description": "Auto-recharge failed, or the depletion grace window expired. Delivered as a signed HTTP POST; respond with any 2xx to acknowledge. Retries: 5 attempts, exponential backoff, Retry-After honored on 429.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable event id (evt_...). Identical across fan-out and retries; also sent as X-SmartlyQ-Event-Id. Use for deduplication." }, "event": { "type": "string", "const": "wallet.recharge.failed" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string" }, "error": { "type": "string" }, "balance": { "type": "number" }, "retry_after": { "type": "string" }, "reason": { "type": "string", "description": "Set to wallet_depleted on grace-expiry pauses." }, "profiles_paused": { "type": "boolean" }, "grace_days": { "type": "integer" } }, "description": "Two variants: a failed charge attempt (amount/currency/error/balance/retry_after) or a grace-expiry pause (reason/profiles_paused/grace_days)." } }, "required": [ "id", "event", "created_at", "data" ], "description": "Delivery envelope. Signed via X-SmartlyQ-Signature (t=,v1=HMAC-SHA256(ts + '.' + raw body)). When the event originated inside a profile workspace, data additionally carries profile_id and profile_workspace_id." } } } }, "responses": { "200": { "description": "Acknowledged. Any 2xx status is treated as delivered." } } } }, "account_billing.charged": { "post": { "operationId": "webhookAccountBillingCharged", "summary": "account_billing.charged", "description": "Monthly per-account billing charged your wallet. Delivered as a signed HTTP POST; respond with any 2xx to acknowledge. Retries: 5 attempts, exponential backoff, Retry-After honored on 429.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable event id (evt_...). Identical across fan-out and retries; also sent as X-SmartlyQ-Event-Id. Use for deduplication." }, "event": { "type": "string", "const": "account_billing.charged" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "period": { "type": "string", "description": "Billing period, e.g. 2026-07." }, "accounts": { "type": "integer" }, "amount": { "type": "number" }, "balance_after": { "type": [ "number", "null" ] } }, "required": [ "period", "accounts", "amount" ] } }, "required": [ "id", "event", "created_at", "data" ], "description": "Delivery envelope. Signed via X-SmartlyQ-Signature (t=,v1=HMAC-SHA256(ts + '.' + raw body)). When the event originated inside a profile workspace, data additionally carries profile_id and profile_workspace_id." } } } }, "responses": { "200": { "description": "Acknowledged. Any 2xx status is treated as delivered." } } } }, "account_billing.failed": { "post": { "operationId": "webhookAccountBillingFailed", "summary": "account_billing.failed", "description": "Monthly per-account billing could not charge your wallet. Delivered as a signed HTTP POST; respond with any 2xx to acknowledge. Retries: 5 attempts, exponential backoff, Retry-After honored on 429.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable event id (evt_...). Identical across fan-out and retries; also sent as X-SmartlyQ-Event-Id. Use for deduplication." }, "event": { "type": "string", "const": "account_billing.failed" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "period": { "type": "string" }, "accounts": { "type": "integer" }, "amount_due": { "type": "number" }, "error": { "type": "string" }, "grace_days_remaining": { "type": "integer" }, "profiles_paused": { "type": "boolean", "description": "Present once profiles were paused after the grace window." } }, "required": [ "period", "accounts", "amount_due" ] } }, "required": [ "id", "event", "created_at", "data" ], "description": "Delivery envelope. Signed via X-SmartlyQ-Signature (t=,v1=HMAC-SHA256(ts + '.' + raw body)). When the event originated inside a profile workspace, data additionally carries profile_id and profile_workspace_id." } } } }, "responses": { "200": { "description": "Acknowledged. Any 2xx status is treated as delivered." } } } }, "contact.created": { "post": { "operationId": "webhookContactCreated", "summary": "contact.created", "description": "A CRM contact was created (app or API). Delivered as a signed HTTP POST; respond with any 2xx to acknowledge. Retries: 5 attempts, exponential backoff, Retry-After honored on 429.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable event id (evt_...). Identical across fan-out and retries; also sent as X-SmartlyQ-Event-Id. Use for deduplication." }, "event": { "type": "string", "const": "contact.created" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "email": { "type": "string" }, "contact": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "name": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "company": { "type": "string" }, "phone": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "attributes": { "type": "object", "additionalProperties": true } } } }, "required": [ "contact" ] } }, "required": [ "id", "event", "created_at", "data" ], "description": "Delivery envelope. Signed via X-SmartlyQ-Signature (t=,v1=HMAC-SHA256(ts + '.' + raw body)). When the event originated inside a profile workspace, data additionally carries profile_id and profile_workspace_id." } } } }, "responses": { "200": { "description": "Acknowledged. Any 2xx status is treated as delivered." } } } }, "contact.updated": { "post": { "operationId": "webhookContactUpdated", "summary": "contact.updated", "description": "A CRM contact was updated (app or API). Delivered as a signed HTTP POST; respond with any 2xx to acknowledge. Retries: 5 attempts, exponential backoff, Retry-After honored on 429.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable event id (evt_...). Identical across fan-out and retries; also sent as X-SmartlyQ-Event-Id. Use for deduplication." }, "event": { "type": "string", "const": "contact.updated" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "email": { "type": "string" }, "contact": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "name": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "company": { "type": "string" }, "phone": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "attributes": { "type": "object", "additionalProperties": true } } } }, "required": [ "contact" ] } }, "required": [ "id", "event", "created_at", "data" ], "description": "Delivery envelope. Signed via X-SmartlyQ-Signature (t=,v1=HMAC-SHA256(ts + '.' + raw body)). When the event originated inside a profile workspace, data additionally carries profile_id and profile_workspace_id." } } } }, "responses": { "200": { "description": "Acknowledged. Any 2xx status is treated as delivered." } } } }, "contact.tag_added": { "post": { "operationId": "webhookContactTagAdded", "summary": "contact.tag_added", "description": "A tag was added to a contact. Delivered as a signed HTTP POST; respond with any 2xx to acknowledge. Retries: 5 attempts, exponential backoff, Retry-After honored on 429.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable event id (evt_...). Identical across fan-out and retries; also sent as X-SmartlyQ-Event-Id. Use for deduplication." }, "event": { "type": "string", "const": "contact.tag_added" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "email": { "type": "string" }, "contact": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "name": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "company": { "type": "string" }, "phone": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "attributes": { "type": "object", "additionalProperties": true } } }, "tag": { "type": "string" } }, "required": [ "contact", "tag" ] } }, "required": [ "id", "event", "created_at", "data" ], "description": "Delivery envelope. Signed via X-SmartlyQ-Signature (t=,v1=HMAC-SHA256(ts + '.' + raw body)). When the event originated inside a profile workspace, data additionally carries profile_id and profile_workspace_id." } } } }, "responses": { "200": { "description": "Acknowledged. Any 2xx status is treated as delivered." } } } }, "contact.tag_removed": { "post": { "operationId": "webhookContactTagRemoved", "summary": "contact.tag_removed", "description": "A tag was removed from a contact. Delivered as a signed HTTP POST; respond with any 2xx to acknowledge. Retries: 5 attempts, exponential backoff, Retry-After honored on 429.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable event id (evt_...). Identical across fan-out and retries; also sent as X-SmartlyQ-Event-Id. Use for deduplication." }, "event": { "type": "string", "const": "contact.tag_removed" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "email": { "type": "string" }, "contact": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "name": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "company": { "type": "string" }, "phone": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "attributes": { "type": "object", "additionalProperties": true } } }, "tag": { "type": "string" } }, "required": [ "contact", "tag" ] } }, "required": [ "id", "event", "created_at", "data" ], "description": "Delivery envelope. Signed via X-SmartlyQ-Signature (t=,v1=HMAC-SHA256(ts + '.' + raw body)). When the event originated inside a profile workspace, data additionally carries profile_id and profile_workspace_id." } } } }, "responses": { "200": { "description": "Acknowledged. Any 2xx status is treated as delivered." } } } }, "deal.created": { "post": { "operationId": "webhookDealCreated", "summary": "deal.created", "description": "An opportunity was created. Delivered as a signed HTTP POST; respond with any 2xx to acknowledge. Retries: 5 attempts, exponential backoff, Retry-After honored on 429.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable event id (evt_...). Identical across fan-out and retries; also sent as X-SmartlyQ-Event-Id. Use for deduplication." }, "event": { "type": "string", "const": "deal.created" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "email": { "type": "string" }, "deal": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "value": { "type": "number" }, "stage": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "won", "lost" ] }, "pipeline_id": { "type": [ "integer", "null" ] }, "assigned_user_id": { "type": [ "integer", "null" ] }, "stage_changed_at": { "type": "string" } } } }, "required": [ "deal" ] } }, "required": [ "id", "event", "created_at", "data" ], "description": "Delivery envelope. Signed via X-SmartlyQ-Signature (t=,v1=HMAC-SHA256(ts + '.' + raw body)). When the event originated inside a profile workspace, data additionally carries profile_id and profile_workspace_id." } } } }, "responses": { "200": { "description": "Acknowledged. Any 2xx status is treated as delivered." } } } }, "deal.stage_changed": { "post": { "operationId": "webhookDealStageChanged", "summary": "deal.stage_changed", "description": "An opportunity moved to a different pipeline stage. Delivered as a signed HTTP POST; respond with any 2xx to acknowledge. Retries: 5 attempts, exponential backoff, Retry-After honored on 429.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable event id (evt_...). Identical across fan-out and retries; also sent as X-SmartlyQ-Event-Id. Use for deduplication." }, "event": { "type": "string", "const": "deal.stage_changed" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "email": { "type": "string" }, "deal": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "value": { "type": "number" }, "stage": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "won", "lost" ] }, "pipeline_id": { "type": [ "integer", "null" ] }, "assigned_user_id": { "type": [ "integer", "null" ] }, "stage_changed_at": { "type": "string" }, "old_stage": { "type": "string", "description": "The stage the deal moved FROM." } } } }, "required": [ "deal" ] } }, "required": [ "id", "event", "created_at", "data" ], "description": "Delivery envelope. Signed via X-SmartlyQ-Signature (t=,v1=HMAC-SHA256(ts + '.' + raw body)). When the event originated inside a profile workspace, data additionally carries profile_id and profile_workspace_id." } } } }, "responses": { "200": { "description": "Acknowledged. Any 2xx status is treated as delivered." } } } }, "deal.won": { "post": { "operationId": "webhookDealWon", "summary": "deal.won", "description": "An opportunity was marked won. Delivered as a signed HTTP POST; respond with any 2xx to acknowledge. Retries: 5 attempts, exponential backoff, Retry-After honored on 429.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable event id (evt_...). Identical across fan-out and retries; also sent as X-SmartlyQ-Event-Id. Use for deduplication." }, "event": { "type": "string", "const": "deal.won" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "email": { "type": "string" }, "deal": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "value": { "type": "number" }, "stage": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "won", "lost" ] }, "pipeline_id": { "type": [ "integer", "null" ] }, "assigned_user_id": { "type": [ "integer", "null" ] }, "stage_changed_at": { "type": "string" } } } }, "required": [ "deal" ] } }, "required": [ "id", "event", "created_at", "data" ], "description": "Delivery envelope. Signed via X-SmartlyQ-Signature (t=,v1=HMAC-SHA256(ts + '.' + raw body)). When the event originated inside a profile workspace, data additionally carries profile_id and profile_workspace_id." } } } }, "responses": { "200": { "description": "Acknowledged. Any 2xx status is treated as delivered." } } } }, "deal.lost": { "post": { "operationId": "webhookDealLost", "summary": "deal.lost", "description": "An opportunity was marked lost. Delivered as a signed HTTP POST; respond with any 2xx to acknowledge. Retries: 5 attempts, exponential backoff, Retry-After honored on 429.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable event id (evt_...). Identical across fan-out and retries; also sent as X-SmartlyQ-Event-Id. Use for deduplication." }, "event": { "type": "string", "const": "deal.lost" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "email": { "type": "string" }, "deal": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "value": { "type": "number" }, "stage": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "won", "lost" ] }, "pipeline_id": { "type": [ "integer", "null" ] }, "assigned_user_id": { "type": [ "integer", "null" ] }, "stage_changed_at": { "type": "string" } } } }, "required": [ "deal" ] } }, "required": [ "id", "event", "created_at", "data" ], "description": "Delivery envelope. Signed via X-SmartlyQ-Signature (t=,v1=HMAC-SHA256(ts + '.' + raw body)). When the event originated inside a profile workspace, data additionally carries profile_id and profile_workspace_id." } } } }, "responses": { "200": { "description": "Acknowledged. Any 2xx status is treated as delivered." } } } }, "post.scheduled": { "post": { "operationId": "webhookPostScheduled", "summary": "post.scheduled", "description": "A post was accepted and queued for a future publish. Delivered as a signed HTTP POST; respond with any 2xx to acknowledge. Retries: 5 attempts, exponential backoff, Retry-After honored on 429.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable event id (evt_...). Identical across fan-out and retries; also sent as X-SmartlyQ-Event-Id. Use for deduplication." }, "event": { "type": "string", "const": "post.scheduled" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "post_id": { "type": "integer" }, "status": { "type": "string" }, "scheduled_at": { "type": "string", "format": "date-time" }, "platforms": { "type": "array", "items": { "type": "string" } } } } } } } } }, "responses": { "200": { "description": "Acknowledged." } } } }, "post.cancelled": { "post": { "operationId": "webhookPostCancelled", "summary": "post.cancelled", "description": "A scheduled post was cancelled before publishing. Delivered as a signed HTTP POST; respond with any 2xx to acknowledge. Retries: 5 attempts, exponential backoff, Retry-After honored on 429.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable event id (evt_...). Identical across fan-out and retries; also sent as X-SmartlyQ-Event-Id. Use for deduplication." }, "event": { "type": "string", "const": "post.cancelled" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "post_id": { "type": "integer" }, "status": { "type": "string" } } } } } } } }, "responses": { "200": { "description": "Acknowledged." } } } }, "post.recycled": { "post": { "operationId": "webhookPostRecycled", "summary": "post.recycled", "description": "A recycling chain spawned a new occurrence of a post. Delivered as a signed HTTP POST; respond with any 2xx to acknowledge. Retries: 5 attempts, exponential backoff, Retry-After honored on 429.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable event id (evt_...). Identical across fan-out and retries; also sent as X-SmartlyQ-Event-Id. Use for deduplication." }, "event": { "type": "string", "const": "post.recycled" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "post_id": { "type": "integer", "description": "The new occurrence." }, "recycled_from": { "type": "integer" }, "status": { "type": "string" }, "scheduled_at": { "type": "string", "format": "date-time" } } } } } } } }, "responses": { "200": { "description": "Acknowledged." } } } }, "post.external.created": { "post": { "operationId": "webhookPostExternalCreated", "summary": "post.external.created", "description": "A post authored natively on the platform (not via SmartlyQ) was detected by external sync. Delivered as a signed HTTP POST; respond with any 2xx to acknowledge. Retries: 5 attempts, exponential backoff, Retry-After honored on 429.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable event id (evt_...). Identical across fan-out and retries; also sent as X-SmartlyQ-Event-Id. Use for deduplication." }, "event": { "type": "string", "const": "post.external.created" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "post_id": { "type": "integer" }, "platform": { "type": "string" }, "remote_id": { "type": "string", "nullable": true }, "status": { "type": "string" } } } } } } } }, "responses": { "200": { "description": "Acknowledged." } } } }, "post.external.updated": { "post": { "operationId": "webhookPostExternalUpdated", "summary": "post.external.updated", "description": "A synced native post's text or media changed on the platform. Delivered as a signed HTTP POST; respond with any 2xx to acknowledge. Retries: 5 attempts, exponential backoff, Retry-After honored on 429.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable event id (evt_...). Identical across fan-out and retries; also sent as X-SmartlyQ-Event-Id. Use for deduplication." }, "event": { "type": "string", "const": "post.external.updated" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "post_id": { "type": "integer" }, "platform": { "type": "string" }, "remote_id": { "type": "string", "nullable": true }, "status": { "type": "string" } } } } } } } }, "responses": { "200": { "description": "Acknowledged." } } } }, "message.sent": { "post": { "operationId": "webhookMessageSent", "summary": "message.sent", "description": "An outbound DM was delivered from the inbox (via app or API). Delivered as a signed HTTP POST; respond with any 2xx to acknowledge. Retries: 5 attempts, exponential backoff, Retry-After honored on 429.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable event id (evt_...). Identical across fan-out and retries; also sent as X-SmartlyQ-Event-Id. Use for deduplication." }, "event": { "type": "string", "const": "message.sent" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "platform": { "type": "string" }, "conversation_id": { "type": "integer" }, "message_id": { "type": "integer" }, "remote_message_id": { "type": "string", "nullable": true }, "content": { "type": "string" } } } } } } } }, "responses": { "200": { "description": "Acknowledged." } } } }, "conversation.started": { "post": { "operationId": "webhookConversationStarted", "summary": "conversation.started", "description": "A new inbox conversation was opened with a contact. Delivered as a signed HTTP POST; respond with any 2xx to acknowledge. Retries: 5 attempts, exponential backoff, Retry-After honored on 429.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable event id (evt_...). Identical across fan-out and retries; also sent as X-SmartlyQ-Event-Id. Use for deduplication." }, "event": { "type": "string", "const": "conversation.started" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "platform": { "type": "string" }, "conversation_id": { "type": "integer" }, "participant_name": { "type": "string" } } } } } } } }, "responses": { "200": { "description": "Acknowledged." } } } }, "reaction.received": { "post": { "operationId": "webhookReactionReceived", "summary": "reaction.received", "description": "A participant added or removed an emoji reaction on a message. Delivered as a signed HTTP POST; respond with any 2xx to acknowledge. Retries: 5 attempts, exponential backoff, Retry-After honored on 429.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable event id (evt_...). Identical across fan-out and retries; also sent as X-SmartlyQ-Event-Id. Use for deduplication." }, "event": { "type": "string", "const": "reaction.received" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "platform": { "type": "string" }, "action": { "type": "string" }, "emoji": { "type": "string" }, "conversation_id": { "type": "integer", "nullable": true }, "message_id": { "type": "integer", "nullable": true }, "remote_message_id": { "type": "string" } } } } } } } }, "responses": { "200": { "description": "Acknowledged." } } } }, "review.new": { "post": { "operationId": "webhookReviewNew", "summary": "review.new", "description": "A new review was posted on a connected account (Google Business). Delivered as a signed HTTP POST; respond with any 2xx to acknowledge. Retries: 5 attempts, exponential backoff, Retry-After honored on 429.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable event id (evt_...). Identical across fan-out and retries; also sent as X-SmartlyQ-Event-Id. Use for deduplication." }, "event": { "type": "string", "const": "review.new" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "review_id": { "type": "integer" }, "account_id": { "type": "integer" }, "platform": { "type": "string" }, "rating": { "type": "integer" }, "author_name": { "type": "string" }, "content": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } } } } }, "responses": { "200": { "description": "Acknowledged." } } } }, "review.updated": { "post": { "operationId": "webhookReviewUpdated", "summary": "review.updated", "description": "A review was edited, or a reply was posted/removed. Delivered as a signed HTTP POST; respond with any 2xx to acknowledge. Retries: 5 attempts, exponential backoff, Retry-After honored on 429.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable event id (evt_...). Identical across fan-out and retries; also sent as X-SmartlyQ-Event-Id. Use for deduplication." }, "event": { "type": "string", "const": "review.updated" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "review_id": { "type": "integer" }, "account_id": { "type": "integer" }, "platform": { "type": "string" }, "rating": { "type": "integer" }, "author_name": { "type": "string" }, "content": { "type": "string" }, "reply": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } } } } } } }, "responses": { "200": { "description": "Acknowledged." } } } }, "message.delivered": { "post": { "operationId": "webhookMessageDelivered", "summary": "message.delivered", "description": "An outbound message was delivered to the recipient (WhatsApp). Delivered as a signed HTTP POST; respond 2xx to acknowledge. Retries: 5 attempts, exponential backoff.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "event": { "type": "string", "const": "message.delivered" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "platform": { "type": "string" }, "remote_message_id": { "type": "string" }, "status": { "type": "string" } } } } } } } }, "responses": { "200": { "description": "Acknowledged." } } } }, "message.read": { "post": { "operationId": "webhookMessageRead", "summary": "message.read", "description": "A recipient read an outbound message (WhatsApp). Delivered as a signed HTTP POST; respond 2xx to acknowledge. Retries: 5 attempts, exponential backoff.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "event": { "type": "string", "const": "message.read" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "platform": { "type": "string" }, "remote_message_id": { "type": "string" }, "status": { "type": "string" } } } } } } } }, "responses": { "200": { "description": "Acknowledged." } } } }, "message.failed": { "post": { "operationId": "webhookMessageFailed", "summary": "message.failed", "description": "An outbound message failed to deliver (WhatsApp), with the platform error. Delivered as a signed HTTP POST; respond 2xx to acknowledge. Retries: 5 attempts, exponential backoff.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "event": { "type": "string", "const": "message.failed" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "platform": { "type": "string" }, "remote_message_id": { "type": "string" }, "status": { "type": "string" }, "error": { "type": "object" } } } } } } } }, "responses": { "200": { "description": "Acknowledged." } } } } } }