> ## 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. # AI Visibility Audit (async) > Zero-input GEO audit: give a website URL and the audit auto-generates realistic customer queries in the market's language (or accepts your own), runs every query across ChatGPT, Claude, Gemini and Perplexity, and scores unaided brand presence. The result contains an AI Presence Score (0-100 = share of query x model checks whose answer mentions the brand or domain), per-query mention results, and the competitors AI recommends instead. Long-running (typically 5-15 minutes): returns 202 with a job_id - poll GET /jobs/{job_id}. Billed per (query x model) check. ## OpenAPI ````yaml /openapi.json post /seo/ai-audit 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: /seo/ai-audit: post: tags: - SEO summary: AI Visibility Audit (async) description: >- Zero-input GEO audit: give a website URL and the audit auto-generates realistic customer queries in the market's language (or accepts your own), runs every query across ChatGPT, Claude, Gemini and Perplexity, and scores unaided brand presence. The result contains an AI Presence Score (0-100 = share of query x model checks whose answer mentions the brand or domain), per-query mention results, and the competitors AI recommends instead. Long-running (typically 5-15 minutes): returns 202 with a job_id - poll GET /jobs/{job_id}. Billed per (query x model) check. operationId: seoAiAudit requestBody: required: true content: application/json: schema: type: object required: - url properties: url: type: string description: The business website URL to audit. brand: type: string description: >- Brand name to detect in answers (auto-detected from the site when omitted). location: type: string default: United States description: >- Market/location name (queries are generated in its language). language: type: string description: ISO language code override for generated queries. queries: type: array maxItems: 12 items: type: string description: >- Custom customer queries (max 12). Omit to auto-generate 8 from the website. models: type: array items: type: string enum: - chat_gpt - claude - gemini - perplexity description: Which models to check (default all four). name: type: string description: Optional audit name. example: url: acme-plumbing.com location: United Kingdom responses: '202': description: Accepted; poll job for the audit report content: application/json: schema: $ref: '#/components/schemas/JobCreatedResponse' example: success: true data: job_id: ext_7f2c91 usage: units: 1 cost: '0.0150' balance_remaining: '99.9850' meta: request_id: req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34 timestamp: '2026-07-26T09:41:22Z' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/InsufficientBalance' '403': $ref: '#/components/responses/Forbidden' '422': $ref: '#/components/responses/ValidationError' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' components: schemas: 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' UsageMeta: type: object properties: units: type: integer cost: type: string example: '0.0150' balance_remaining: type: string example: '99.9850' 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' RateLimited: description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: RATE_LIMITED message: Rate limit exceeded. Retry after 12 seconds. details: retry_after: 12 meta: request_id: req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34 timestamp: '2026-07-26T09:41:22Z' ServerError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: SERVER_ERROR message: >- Something went wrong on our side. Retry with the same request_id - it is safe. details: {} meta: request_id: req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34 timestamp: '2026-07-26T09:41:22Z' securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: sqk_live_* or sqk_test_* description: API key from Developer dashboard (Bearer token). ````