> ## 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. # Inbox source breakdown > Active conversations and message volume per platform. Requires scope `analytics:read`. ## OpenAPI ````yaml /openapi.json get /analytics/inbox/source-breakdown 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/my/developer](https://app.smartlyq.com/my/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 | | `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 | | `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/my/developer](https://app.smartlyq.com/my/developer) (wallet / top-up). ## Rate Limiting Limits apply per API key (and may be enforced per user or IP). Default is 60 requests per minute per key (overridable per key). 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`, `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: Workspaces description: Create sub-account workspaces - name: Articles description: Long-form article generation and management - name: Images description: AI image generation and listing - name: Videos description: AI video generation and listing - name: Social description: Social accounts and post scheduling - name: Content description: Content rewriting - name: Audio description: Text-to-speech and speech-to-text - name: URLs description: URL shortening and analytics - name: AI Captain description: AI Captain conversations - name: Chatbot description: Chatbots, training, and conversations - name: Media description: Media library and uploads - name: Analytics description: Analytics overview and reports - name: Jobs description: Async job status and cancellation - name: SEO description: >- DataForSEO-backed keyword research, SERP, rank tracking, competitors, backlinks and on-page audits - name: Account description: Current user, usage, and balance - name: Comments description: Comments endpoints - name: Direct Messages description: Direct Messages endpoints - name: Webhooks description: Subscribe to event notifications (HMAC-signed deliveries with retries). - name: Shorts description: 'Magic Shorts: turn long videos into ranked viral clips' - name: Presentations description: AI presentation (slide deck) generation from a prompt paths: /analytics/inbox/source-breakdown: get: tags: - Analytics summary: Inbox source breakdown description: >- Active conversations and message volume per platform. Requires scope `analytics:read`. operationId: inboxSourceBreakdown parameters: - name: days in: query schema: type: integer default: 30 minimum: 1 maximum: 365 description: Window in days. responses: '200': description: Breakdown content: application/json: schema: type: object properties: success: type: boolean enum: - true data: type: object properties: days: type: integer platforms: type: array items: type: object properties: platform: type: string conversations: type: integer incoming: type: integer outgoing: type: integer meta: $ref: '#/components/schemas/RequestMeta' example: success: true data: days: 30 platforms: - platform: twitter conversations: 1 incoming: 34 outgoing: 29 meta: request_id: req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34 timestamp: '2026-07-26T09:41:22Z' '401': $ref: '#/components/responses/Unauthorized' components: schemas: 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' securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: sqk_live_* or sqk_test_* description: API key from Developer dashboard (Bearer token). ````