> ## 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. # Send test webhook > Synchronously sends a `webhook.test` delivery to the endpoint through the real signing pipeline (same headers and HMAC signature as production events) and returns the outcome. Works even when the endpoint is paused or failing. Test deliveries are never retried by the worker. Requires scope `webhooks:write`. Not available under X-Profile-Id delegation - webhooks live on your developer workspace and receive profile events automatically (with profile_id attached). ## OpenAPI ````yaml /openapi.json post /webhooks/{id}/test 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: /webhooks/{id}/test: post: tags: - Webhooks summary: Send test webhook description: >- Synchronously sends a `webhook.test` delivery to the endpoint through the real signing pipeline (same headers and HMAC signature as production events) and returns the outcome. Works even when the endpoint is paused or failing. Test deliveries are never retried by the worker. Requires scope `webhooks:write`. Not available under X-Profile-Id delegation - webhooks live on your developer workspace and receive profile events automatically (with profile_id attached). operationId: testWebhook parameters: - name: id in: path required: true schema: type: integer description: Webhook id. responses: '200': description: Test result content: application/json: schema: type: object properties: success: type: boolean enum: - true data: type: object properties: delivered: type: boolean description: True when the endpoint answered 2xx. event_id: type: string delivery_id: type: integer response_code: type: integer nullable: true response_body: type: string nullable: true meta: $ref: '#/components/schemas/RequestMeta' example: success: true data: delivered: true event_id: evt_1a2b3c delivery_id: 9812 response_code: 200 response_body: ok meta: request_id: req_abc123 '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' 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' NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: RESOURCE_NOT_FOUND message: Post not found. details: {} meta: request_id: req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34 timestamp: '2026-07-26T09:41:22Z' securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: sqk_live_* or sqk_test_* description: API key from Developer dashboard (Bearer token). ````