{ "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## 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| `social:read` | List accounts and posts |\n| `social:write` | Create, update, delete posts |\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, posts, account analytics |\n| `jobs:read` | List and get async jobs, cancel |\n| `seo:read` | Keyword research, SERP, rank tracking, competitors, backlinks, on-page audits |\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:** e.g. `job.completed`, `job.failed`, `chatbot.conversation.ended`.\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": "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)." } ], "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" } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "/avatar-videos/avatars": { "get": { "summary": "List avatars", "description": "Lists available AI avatars and talking photos for avatar video generation. Not billed.", "operationId": "listAvatars", "tags": [ "Videos" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/avatar-videos/voices": { "get": { "summary": "List avatar voices", "description": "Lists available voices (id, name, language, gender) for avatar videos. Not billed.", "operationId": "listAvatarVoices", "tags": [ "Videos" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/avatar-videos/generate": { "post": { "summary": "Generate avatar video", "description": "Generates a talking-avatar video from a script. Returns `202 Accepted` with a `job_uid`; poll `GET /v1/avatar-videos/{uid}` for status and the final video URL.\n\n**Before submitting:** call `GET /v1/avatar-videos/avatars` and `GET /v1/avatar-videos/voices` to pick a valid `avatar_id` + `voice_id`.\n\n**Billing:** the cost is deducted from your API wallet when the job is accepted. If the render fails the charge is automatically refunded.", "operationId": "generateAvatarVideo", "tags": [ "Videos" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "script", "avatar_id", "voice_id" ], "properties": { "script": { "type": "string", "description": "Text the avatar will speak." }, "avatar_id": { "type": "string", "description": "Avatar id from GET /v1/avatar-videos/avatars." }, "voice_id": { "type": "string", "description": "Voice id from GET /v1/avatar-videos/voices." }, "dimension": { "type": "string", "description": "Output resolution WxH.", "default": "1920x1080" }, "title": { "type": "string", "description": "Optional title for the render." } } }, "example": { "script": "Hello from SmartlyQ.", "avatar_id": "Daisy-inskirt-20220818", "voice_id": "2d5b0e6cf36f460aa7fc47e3eee4ba54", "dimension": "1920x1080" } } } }, "responses": { "202": { "description": "Accepted — poll GET /v1/avatar-videos/{uid} for result", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "data": { "job_uid": "hg_a1b2c3d4e5f6", "status": "queued" }, "usage": { "units": 1, "cost": "12.0000", "balance_remaining": "88.0000" } } } } }, "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" } } } }, "/avatar-videos/translate": { "post": { "summary": "Translate a video", "description": "Re-voices an existing video into other languages. Returns `202 Accepted` with a `job_uid`; poll `GET /v1/avatar-videos/{uid}`. Billed per request from your API wallet; refunded on failure.", "operationId": "translateVideo", "tags": [ "Videos" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "source_video_url", "target_languages" ], "properties": { "source_video_url": { "type": "string", "description": "URL of the video to translate." }, "target_languages": { "type": "array", "items": { "type": "string" }, "description": "Target languages, e.g. [\"Spanish\", \"French\"]." }, "quality": { "type": "string", "enum": [ "speed", "precision" ], "default": "speed" }, "title": { "type": "string" } } } } } }, "responses": { "202": { "description": "Accepted — poll GET /v1/avatar-videos/{uid} for result" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientBalance" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/avatar-videos/lipsync": { "post": { "summary": "Lipsync a video", "description": "Drives an avatar with a provided audio track. Returns `202 Accepted` with a `job_uid`; poll `GET /v1/avatar-videos/{uid}`. Billed per request from your API wallet; refunded on failure.", "operationId": "lipsyncVideo", "tags": [ "Videos" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "avatar_id", "audio_url" ], "properties": { "avatar_id": { "type": "string", "description": "Avatar id from GET /v1/avatar-videos/avatars." }, "audio_url": { "type": "string", "description": "URL of the audio to lipsync." }, "quality": { "type": "string", "enum": [ "speed", "precision" ], "default": "speed" }, "title": { "type": "string" } } } } } }, "responses": { "202": { "description": "Accepted — poll GET /v1/avatar-videos/{uid} for result" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientBalance" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/avatar-videos/agent": { "post": { "summary": "Generate a video from a prompt", "description": "Prompt-to-video. From a single prompt the agent writes the script, picks the avatar and voice, and renders - no `avatar_id`/`voice_id` needed. Returns `202 Accepted` with a `job_uid`; poll `GET /v1/avatar-videos/{uid}`. Billed per request from your API wallet; refunded on failure.", "operationId": "agentVideo", "tags": [ "Videos" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "prompt" ], "properties": { "prompt": { "type": "string", "description": "What the video should be about, e.g. 'A 30-second product launch announcement, upbeat and confident'.", "maxLength": 2000 }, "dimension": { "type": "string", "description": "WxH, e.g. 1920x1080 (default) or 1080x1920." }, "title": { "type": "string" } } } } } }, "responses": { "202": { "description": "Accepted — poll GET /v1/avatar-videos/{uid} for result" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientBalance" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/avatar-videos/{uid}": { "get": { "summary": "Get avatar video render", "description": "Returns the status and (when complete) the video URL for an avatar-video render.", "operationId": "getAvatarVideo", "tags": [ "Videos" ], "parameters": [ { "name": "uid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The job_uid returned by generate/translate/lipsync." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "data": { "job_uid": "hg_a1b2c3d4e5f6", "status": "completed", "kind": "stock", "progress": 100, "video_url": "https://videocdn.smartlyq.com/video-studio/42/hg_a1b2c3d4e5f6.mp4", "duration_sec": 42, "error": "", "created_at": "2026-10-15 09:16:00" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/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" } } } }, "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" } } } }, "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" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/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" } } } }, "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" } } }, "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" } ], "responses": { "200": { "description": "Paginated list of posts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SocialPostListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/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" } } } }, "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" } } } }, "/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" } } } }, "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" } } } }, "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" } } } }, "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 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": { "200": { "description": "Historical rank overview", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "target": { "type": "string" }, "history": { "type": "array", "items": { "type": "object", "properties": { "year": { "type": "integer" }, "month": { "type": "integer" }, "organic_keywords": { "type": "integer" }, "organic_etv": { "type": "number" } } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "target": "example.com", "history": [ { "year": 2026, "month": 5, "organic_keywords": 11800, "organic_etv": 44210.3 }, { "year": 2026, "month": 6, "organic_keywords": 12500, "organic_etv": 48230.7 } ] }, "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/site-audit": { "post": { "summary": "Deep site audit", "description": "Crawl-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": { "200": { "description": "Deep site audit", "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" }, "pages": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "onpage_score": { "type": "number" }, "status_code": { "type": "integer" }, "title": { "type": "string" }, "flagged_checks": { "type": "array", "items": { "type": "string" } } } } } } } } }, "meta": { "$ref": "#/components/schemas/RequestMeta" } } }, "example": { "success": true, "data": { "url": "https://example.com", "audit": { "crawl_progress": "finished", "pages_crawled": 20, "pages_with_errors": 3, "onpage_score": 88.4, "checks": { "duplicate_title": false, "broken_links": true }, "pages": [ { "url": "https://example.com/old", "onpage_score": 61.2, "status_code": 200, "title": "Old Page", "flagged_checks": [ "low_content_rate", "no_description" ] } ] } }, "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" } } } }, "/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" } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "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" } } ], "responses": { "200": { "description": "Analytics overview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/social/accounts/{account_id}": { "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": "" } ], "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}": { "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": "" } ], "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" } } } } } }, "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" } } } }, "/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" }, "description": "Event names to subscribe to." } } } } } }, "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" } } } }, "/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`.", "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" ] }, "description": "Platform to connect. All 13 platforms are supported (use `twitter` for X, `gmb` for Google Business)." } ], "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." } } } } } }, "responses": { "201": { "description": "Connection link created", "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" } } } } } }, "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)." } ], "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" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } } }, "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" } } }, "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" } } } }, "Unauthorized": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "InsufficientBalance": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Forbidden": { "description": "Forbidden (scope or access)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Conflict": { "description": "Conflict (e.g. duplicate idempotency or already-finished job)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ValidationError": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "RateLimited": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ServerError": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "RequestMeta": { "type": "object", "properties": { "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } }, "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" }, "description": "Target platforms (e.g. facebook, twitter, instagram)" }, "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" } } }, "SocialPostScheduleRequest": { "type": "object", "required": [ "content", "platforms", "account_ids", "scheduled_time" ], "properties": { "content": { "type": "string", "description": "Post text content" }, "platforms": { "type": "array", "items": { "type": "string" }, "description": "Target platforms" }, "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" } } }, "SocialPostUpdateRequest": { "type": "object", "description": "At least one field must be provided.", "properties": { "content": { "type": "string" }, "platforms": { "type": "array", "items": { "type": "string" } }, "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" } } }, "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" } } } } } }