> ## Documentation Index > Fetch the complete documentation index at: https://docs.smartlyq.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a video edit > Edits one video (any aspect ratio, up to 60 minutes): word-by-word captions, magic zooms, stock b-roll, silence and filler removal, clean audio, hook title, music and your brand template. Every field is checked before any charge (422 naming it). Returns `202 Accepted` with an `edit_uid`; the edit becomes `ready` (open it with `editor_url`) and can then be exported with POST /v1/edits/{uid}/export, or set `auto_export` to export straight away. Pass `webhook_url` to be told when it is ready and when it is exported. Billed per source minute (rounded up): 1 minute up front, the rest once the length is known; clean audio and exports are billed per minute too. A failed edit is refunded, except when the video is over 60 minutes or your wallet cannot pay the rest: then the first minute is kept for the download and checks already done. Requires scope `videos:write`. ## OpenAPI ````yaml /openapi.json post /edits openapi: 3.1.0 info: title: SmartlyQ API version: 1.0.0 description: > # SmartlyQ API REST API for the SmartlyQ platform: generate content, manage social posts, chatbots, media, and more. ## Quick Start 1. Get an API key from [app.smartlyq.com/next/developer](https://app.smartlyq.com/next/developer). 2. Send your first request: ```bash curl -H "Authorization: Bearer YOUR_API_KEY" https://api.smartlyq.com/v1/me ``` ## Idempotency Every `POST`/`PUT`/`PATCH` endpoint supports safe retries: send an `X-Idempotency-Key` header (any unique string, e.g. a UUID). If the same key is replayed within 24 hours with the same request, you get the original response back - the action never runs twice, and you are never double-billed. Reusing a key with a *different* body or endpoint returns `409 IDEMPOTENCY_CONFLICT`. ```bash curl -X POST https://api.smartlyq.com/v1/social/posts/schedule \ -H "Authorization: Bearer sqk_live_xxxx" \ -H "X-Idempotency-Key: 5f0c9a4e-2b7d-4d1a-9c58-e2ff10c3a771" \ -d '{...}' ``` ## Authentication All requests (except health/docs) require a **Bearer token**. Use your API key as the token: - **Key types:** `sqk_live_*` (live) or `sqk_test_*` (test/sandbox). - **Header:** `Authorization: Bearer sqk_live_xxxx` or `Authorization: Bearer sqk_test_xxxx`. | Scope | Description | |-------|-------------| | `articles:read` | List and get articles | | `articles:write` | Generate, delete articles | | `images:read` | List and get images | | `images:write` | Generate, delete images | | `videos:read` | List and get videos | | `videos:write` | Generate, delete videos | | `presentations:read` | List and get presentations | | `presentations:write` | Generate presentations | | `social:read` | Accounts (health, follower stats, platform lookups), posts, queues, comments, DMs, reviews, pre-flight validation, Reddit research | | `social:write` | Create/schedule/bulk posts, recycling, unpublish, queues, reply to comments/DMs/reviews, account rename/move, account groups | | `audio:read` | Get audio resources | | `audio:write` | Text-to-speech, speech-to-text | | `urls:read` | List and get short URLs and stats | | `urls:write` | Shorten, delete URLs | | `captain:use` | AI Captain messages and conversations | | `chatbot:use` | Chatbots, train, messages, conversations | | `media:read` | List and get media | | `media:write` | Upload, delete media | | `analytics:read` | Overview, post and account analytics, derived insights (best-time, decay, frequency), inbox analytics | | `jobs:read` | List and get async jobs, cancel | | `seo:read` | Keyword research, SERP, rank tracking, competitors, backlinks, on-page audits | | `contacts:read` | List and get CRM contacts, tags, notes; list automations and their runs | | `contacts:write` | Create/update/delete contacts (single or bulk); tags and notes; enroll in, activate and trigger automations | | `companies:read` | List and get companies, their contacts, deals and value rollup | | `companies:write` | Create/update/delete companies; link and unlink contacts | | `tasks:read` | List and get CRM tasks and activities | | `tasks:write` | Create/update/delete tasks, log time; fires task_created and task_completed | | `calendar:read` | List booking pages and the open slots on them | | `calendar:write` | Take and cancel bookings | | `opportunities:read` | List pipelines and deals/opportunities | | `opportunities:write` | Create/update deals, move stages, set status | | `webhooks:read` | List webhooks and delivery logs | | `webhooks:write` | Create, update, test and delete webhooks | | `logs:read` | Read your API request + webhook delivery logs | | `workspaces:read` | List and get sub-account workspaces | | `workspaces:write` | Create, disable SaaS, and delete sub-account workspaces | | `workspaces:bulk` | Apply pause / resume / disable-SaaS to many sub-accounts at once (high-trust; requires an active SaaS plan) | ## Billing & Credits - **Prepaid wallet:** API usage is deducted from your Developer API wallet (credits in SQC). - **Pricing:** See the [pricing table](https://smartlyq.com/pricing) and in-app Developer dashboard for per-operation costs. - **How it works:** Each billable request (e.g. generate, post, chatbot message) consumes credits; response may include `usage` with `cost` and `balance_remaining`. - **Top up:** Add credits via [app.smartlyq.com/next/developer](https://app.smartlyq.com/next/developer) (wallet / top-up). ## Rate Limiting Limits apply per workspace: every API key in a workspace, including the keys MCP connections create, shares one allowance of 60, 600 or 1,200 requests per minute depending on the connected social accounts, and analytics reads also have a per-second ceiling. Test keys have a separate allowance of the same size. Details: [Rate limiting guide](https://docs.smartlyq.com/guides/rate-limiting). Response headers: | Header | Description | |--------|-------------| | `X-RateLimit-Limit` | Max requests per window | | `X-RateLimit-Remaining` | Remaining in current window | | `X-RateLimit-Reset` | Unix timestamp when the window resets | When exceeded: HTTP `429` with `Retry-After` header. ## Errors Errors are JSON with a consistent shape: ```json { "success": false, "error": { "code": "ERROR_CODE", "message": "Human-readable message", "details": {} }, "meta": { "request_id": "...", "timestamp": "..." } } ``` | HTTP | Code | Meaning | |-----|------|---------| | 400 | `BAD_REQUEST` | Malformed or invalid request | | 401 | `UNAUTHORIZED` | Missing or invalid API key | | 402 | `INSUFFICIENT_BALANCE` | Not enough credits | | 403 | `FORBIDDEN` | Valid key but insufficient scope or access | | 404 | `RESOURCE_NOT_FOUND` | Resource does not exist | | 409 | `CONFLICT` | Conflict (e.g. duplicate idempotency) | | 422 | `VALIDATION_ERROR` | Validation failed (fields in details) | | 429 | `RATE_LIMIT_EXCEEDED` | Too many requests | | 500 | `INTERNAL_ERROR` | Server error | ## Async Jobs & Polling Some operations (e.g. article or video generation) return **HTTP 202 Accepted** with a `job_id`. Poll for status: - **Poll:** `GET /jobs/{job_id}` until `status` is `completed`, `failed`, or `cancelled`. - Response includes `result` or `error` when finished. ## Webhooks Configure webhook URLs in the Developer dashboard. We send HTTP POST to your URL with a signed payload. - **Verification:** Validate signature using your webhook secret (see dashboard). - **Events:** 25 events across posting, accounts, inbox, jobs, billing, and CRM - e.g. `post.published`, `comment.received`, `contact.created`. Full catalog with payload schemas: the `webhooks` object in this spec and the [Webhooks guide](https://docs.smartlyq.com/guides/webhooks). ## Idempotency For 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. ## Pagination - **Offset:** `page` (1-based) and `per_page` (default 20, max 100). - Response includes `pagination` with `page`, `per_page`, `total`, `total_pages`. ## Versioning Current version is **v1**. Base path: `https://api.smartlyq.com/v1`. Future versions will use new path prefixes (e.g. `/v2/`). contact: name: SmartlyQ Support url: https://smartlyq.com email: support@smartlyq.com license: name: Proprietary url: https://smartlyq.com/terms servers: - url: https://api.smartlyq.com/v1 description: Production security: - BearerAuth: [] tags: - name: CRM Contacts description: 'CRM contacts: create, update, upsert, tags and notes' - name: CRM Custom Fields description: Custom field (custom attribute) definitions - name: CRM Opportunities description: Sales pipelines and deals/opportunities - name: CRM Companies description: Companies / organisations, and the contacts linked to them. - name: CRM Tasks description: Tasks and activities, with the automation events they fire. - name: CRM Tags description: The workspace's contact tag vocabulary. - name: Calendar description: Booking pages, open slots, and taking or cancelling bookings. - name: Workspaces description: Create sub-account workspaces - name: Articles description: Long-form article generation and management - name: Images description: AI image generation and listing - name: Videos description: AI video generation and listing - name: Social description: Social accounts and post scheduling - name: Content description: Content rewriting - name: Audio description: Text-to-speech and speech-to-text - name: URLs description: URL shortening and analytics - name: AI Captain description: AI Captain conversations - name: Chatbot description: Chatbots, training, and conversations - name: Media description: Media library and uploads - name: Analytics description: Analytics overview and reports - name: Jobs description: Async job status and cancellation - name: SEO description: >- DataForSEO-backed keyword research, SERP, rank tracking, competitors, backlinks and on-page audits - name: Account description: Current user, usage, and balance - name: Comments description: Comments endpoints - name: Direct Messages description: Direct Messages endpoints - name: Webhooks description: Subscribe to event notifications (HMAC-signed deliveries with retries). - name: Shorts description: 'Magic Shorts: turn long videos into ranked viral clips' - name: Edits description: >- Edit a whole video by API: captions, zooms, b-roll, silence and filler removal, clean audio, hook, music. Open the result in the editor or export it. - name: Presentations description: AI presentation (slide deck) generation from a prompt - name: Logs description: Your own API request and webhook delivery history. - name: WhatsApp description: WhatsApp Business Cloud messaging, templates and business profile. - name: Ads description: >- Campaigns, ad sets, ads, audiences, pixels, lead forms, creatives, connected ad accounts, and diagnostics across Meta, Google, TikTok and LinkedIn Ads. paths: /edits: post: tags: - Edits summary: Create a video edit description: >- Edits one video (any aspect ratio, up to 60 minutes): word-by-word captions, magic zooms, stock b-roll, silence and filler removal, clean audio, hook title, music and your brand template. Every field is checked before any charge (422 naming it). Returns `202 Accepted` with an `edit_uid`; the edit becomes `ready` (open it with `editor_url`) and can then be exported with POST /v1/edits/{uid}/export, or set `auto_export` to export straight away. Pass `webhook_url` to be told when it is ready and when it is exported. Billed per source minute (rounded up): 1 minute up front, the rest once the length is known; clean audio and exports are billed per minute too. A failed edit is refunded, except when the video is over 60 minutes or your wallet cannot pay the rest: then the first minute is kept for the download and checks already done. Requires scope `videos:write`. operationId: createEdit requestBody: required: true content: application/json: schema: type: object required: - video_url properties: video_url: type: string format: uri description: Direct https media URL of the video (MP4/MOV/WebM). title: type: string maxLength: 255 language: type: string default: auto description: 'Spoken language: a code from GET /v1/languages, or "auto".' settings: $ref: '#/components/schemas/EditSettings' webhook_url: type: string format: uri description: >- Public https URL told when the edit is ready, exported or failed (job.completed / job.failed), signed with this edit's webhook_secret. auto_export: type: boolean default: false description: >- Export as soon as the edit is ready (export minutes are billed then). example: video_url: https://cdn.example.com/videos/launch.mp4 title: Product launch settings: caption_style: word-pop magic_zooms: true magic_broll: true remove_silence: natural remove_fillers: true webhook_url: https://example.com/hooks/smartlyq responses: '202': description: 'Accepted: the edit is queued.' content: application/json: schema: type: object properties: success: type: boolean enum: - true data: type: object properties: edit_uid: type: string status: type: string example: queued title: type: string language: type: string settings: $ref: '#/components/schemas/EditSettings' auto_export: type: boolean webhook_url: type: string description: Only present when you sent webhook_url. webhook_secret: type: string description: >- Only present when you sent webhook_url. Shown once: verify X-SmartlyQ-Signature with it. meta: $ref: '#/components/schemas/RequestMeta' example: success: true data: edit_uid: 4f1c9a2e7b3d4c5e8f9a0b1c2d3e4f5a status: queued title: Product launch language: auto settings: captions: true caption_style: word-pop caption_position: bottom magic_zooms: true magic_broll: true broll_percentage: 40 remove_silence: natural remove_fillers: true clean_audio: false auto_export: false webhook_url: https://example.com/hooks/smartlyq webhook_secret: whsec_******** meta: request_id: req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34 timestamp: '2026-10-07T09:41:22Z' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/InsufficientBalance' '403': $ref: '#/components/responses/Forbidden' '422': $ref: '#/components/responses/ValidationError' components: schemas: EditSettings: type: object description: >- How the edit looks. Every key is optional; GET /v1/edits/options lists them with their defaults and allowed values. An unknown key or value is a 422 naming it (e.g. settings.caption_style). additionalProperties: false properties: captions: type: boolean default: true description: Burn word-by-word captions into the video. caption_style: type: string nullable: true description: >- Caption style id (GET /v1/edits/options). Not sent: your brand template's style. caption_format: type: object description: Text formatting switches. properties: italic: type: boolean underline: type: boolean strikethrough: type: boolean uppercase: type: boolean light_bold: type: boolean additionalProperties: false caption_position: type: string enum: - bottom - middle - top default: bottom magic_zooms: type: boolean default: false description: Punch-in zooms on key moments. magic_broll: type: boolean default: false description: Stock b-roll cutaways over the speaker. broll_percentage: type: integer minimum: 0 maximum: 100 default: 50 description: Share of the eligible moments that get b-roll (with magic_broll). remove_silence: type: string enum: - 'off' - natural - fast - extra_fast default: 'off' description: >- Shorten pauses between phrases to 0.6 s (natural), 0.2 s (fast) or 0.1 s (extra_fast). remove_fillers: type: boolean default: false description: Cut filler sounds such as "um" and "uh". clean_audio: type: boolean default: false description: >- Voice-only cleaned soundtrack. Billed separately (edits/clean-audio, per source minute). hook_title: type: string nullable: true maxLength: 120 description: Headline shown for the first 3 seconds. music_url: type: string nullable: true format: uri description: >- Background music: a public https URL (a private or internal host is refused with a 422). music_volume: type: number minimum: 0 maximum: 1 default: 0.15 description: Music volume under the voice. apply_brand_template: type: boolean default: true description: >- Use the workspace brand template (logo, caption styling, hook style, music). RequestMeta: type: object properties: request_id: type: string example: req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34 timestamp: type: string format: date-time example: '2026-07-26T09:41:22Z' 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' responses: Unauthorized: description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: INVALID_API_KEY message: Missing or malformed Authorization header details: {} meta: request_id: req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34 timestamp: '2026-07-26T09:41:22Z' InsufficientBalance: description: Insufficient credits content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: INSUFFICIENT_BALANCE message: Wallet balance is insufficient for this request details: required: '0.0250' balance: '0.0100' meta: request_id: req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34 timestamp: '2026-07-26T09:41:22Z' Forbidden: description: Forbidden (scope or access) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: INSUFFICIENT_SCOPE message: 'API key lacks required scope: social:write' details: required_scope: social:write meta: request_id: req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34 timestamp: '2026-07-26T09:41:22Z' ValidationError: description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: VALIDATION_ERROR message: 'Missing required fields: content, platforms.' details: fields: - content - platforms meta: request_id: req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34 timestamp: '2026-07-26T09:41:22Z' securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: sqk_live_* or sqk_test_* description: API key from Developer dashboard (Bearer token). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.