# SmartlyQ ## Docs - [Introduction](https://docs.smartlyq.com/introduction.md): Build with the SmartlyQ API — generate content, manage social posts, chatbots, media, and more. - [Quickstart](https://docs.smartlyq.com/quickstart.md): Make your first SmartlyQ API call in under 5 minutes. - [Authentication](https://docs.smartlyq.com/authentication.md): How to authenticate requests to the SmartlyQ API. - [AI Agents](https://docs.smartlyq.com/ai-agents.md): Every way to drive SmartlyQ from an AI agent or LLM — MCP, llms.txt, the per-page AI menu, and the REST API. - [MCP](https://docs.smartlyq.com/mcp-server.md): Connect SmartlyQ to Claude, Cursor, ChatGPT, and any MCP client — manage social media and generate content with natural language. - [SDKs & CLI](https://docs.smartlyq.com/sdks/overview.md): Official SmartlyQ client libraries for Node.js, Python, Go, and PHP - plus a CLI and a chatbot adapter. - [Node.js SDK](https://docs.smartlyq.com/sdks/node.md): The official SmartlyQ SDK for Node.js and TypeScript. - [Python SDK](https://docs.smartlyq.com/sdks/python.md): The official SmartlyQ SDK for Python. - [Go SDK](https://docs.smartlyq.com/sdks/go.md): The official SmartlyQ SDK for Go. - [PHP SDK](https://docs.smartlyq.com/sdks/php.md): The official SmartlyQ SDK for PHP. - [Chat SDK Adapter](https://docs.smartlyq.com/sdks/chat-sdk-adapter.md): Build a multi-platform chatbot on the SmartlyQ unified inbox. - [CLI](https://docs.smartlyq.com/sdks/cli.md): Every SmartlyQ API operation as a shell command. - [Webhooks](https://docs.smartlyq.com/guides/webhooks.md): Receive real-time notifications when events happen. - [Connecting Accounts](https://docs.smartlyq.com/guides/connecting-accounts.md): Connect social accounts to SmartlyQ and keep them healthy. - [Idempotency & Safe Retries](https://docs.smartlyq.com/guides/idempotency.md): Retry any create call without ever double-posting. - [Platform Options](https://docs.smartlyq.com/guides/platform-options.md): Every per-platform option you can set on a post, per platform. - [WhatsApp](https://docs.smartlyq.com/guides/whatsapp.md): Send and receive WhatsApp Business messages through the SmartlyQ API. - [Workspaces](https://docs.smartlyq.com/guides/workspaces.md): How workspace scoping works in the SmartlyQ API. - [Profiles](https://docs.smartlyq.com/guides/profiles.md): Build your own multi-tenant product on the SmartlyQ API - one profile per end-customer, self-serve account connection, per-account billing - [Agency sub-accounts & SaaS](https://docs.smartlyq.com/guides/agency-saas.md): Manage agency sub-accounts over the API, and which actions are reserved for SaaS-plan members. - [Billing & Credits](https://docs.smartlyq.com/guides/billing-and-credits.md): How API credits work, pricing, and wallet management. - [Rate Limiting](https://docs.smartlyq.com/guides/rate-limiting.md): API rate limits and how to handle them. - [Async Jobs](https://docs.smartlyq.com/guides/async-jobs.md): How long-running operations work with the job queue. - [Errors](https://docs.smartlyq.com/guides/errors.md): Error codes, response format, and troubleshooting. - [Pricing](https://docs.smartlyq.com/pricing.md): Pay-as-you-go API pricing with prepaid SmartlyQ Credits — only pay for what you use. - [Platforms](https://docs.smartlyq.com/platforms.md): Which social platforms SmartlyQ supports, and exactly what each one can do through the API. - [Facebook](https://docs.smartlyq.com/platforms/facebook.md): Facebook support in the SmartlyQ API: limits, post types, capabilities, and how to connect. - [Instagram](https://docs.smartlyq.com/platforms/instagram.md): Instagram support in the SmartlyQ API: limits, post types, capabilities, and how to connect. - [X (Twitter)](https://docs.smartlyq.com/platforms/twitter.md): X (Twitter) support in the SmartlyQ API: limits, post types, capabilities, and how to connect. - [LinkedIn](https://docs.smartlyq.com/platforms/linkedin.md): LinkedIn support in the SmartlyQ API: limits, post types, capabilities, and how to connect. - [YouTube](https://docs.smartlyq.com/platforms/youtube.md): YouTube support in the SmartlyQ API: limits, post types, capabilities, and how to connect. - [TikTok](https://docs.smartlyq.com/platforms/tiktok.md): TikTok support in the SmartlyQ API: limits, post types, capabilities, and how to connect. - [Threads](https://docs.smartlyq.com/platforms/threads.md): Threads support in the SmartlyQ API: limits, post types, capabilities, and how to connect. - [Bluesky](https://docs.smartlyq.com/platforms/bluesky.md): Bluesky support in the SmartlyQ API: limits, post types, capabilities, and how to connect. - [Pinterest](https://docs.smartlyq.com/platforms/pinterest.md): Pinterest support in the SmartlyQ API: limits, post types, capabilities, and how to connect. - [Reddit](https://docs.smartlyq.com/platforms/reddit.md): Reddit support in the SmartlyQ API: limits, post types, capabilities, and how to connect. - [Snapchat](https://docs.smartlyq.com/platforms/snapchat.md): Snapchat support in the SmartlyQ API: limits, post types, capabilities, and how to connect. - [Tumblr](https://docs.smartlyq.com/platforms/tumblr.md): Tumblr support in the SmartlyQ API: limits, post types, capabilities, and how to connect. - [Google Business](https://docs.smartlyq.com/platforms/google-business.md): Google Business support in the SmartlyQ API: limits, post types, capabilities, and how to connect. - [Telegram](https://docs.smartlyq.com/platforms/telegram.md): Telegram support in the SmartlyQ API: limits, post types, capabilities, and how to connect. - [Discord](https://docs.smartlyq.com/platforms/discord.md): Discord support in the SmartlyQ API: limits, post types, capabilities, and how to connect. - [Get current user profile](https://docs.smartlyq.com/api-reference/account/get-current-user-profile.md) - [Get usage summary](https://docs.smartlyq.com/api-reference/account/get-usage-summary.md) - [Get wallet balance](https://docs.smartlyq.com/api-reference/account/get-wallet-balance.md) - [Billing overview](https://docs.smartlyq.com/api-reference/account/billing-overview.md): A read-only superset of GET /me/balance: the wallet balance breakdown, the monthly cycle reset, auto-recharge configuration, and whether a card is on file. Use payment.status to know if the next billable call is at risk. - [List jobs](https://docs.smartlyq.com/api-reference/jobs/list-jobs.md) - [Get job](https://docs.smartlyq.com/api-reference/jobs/get-job.md) - [Cancel job](https://docs.smartlyq.com/api-reference/jobs/cancel-job.md): 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. - [List webhooks](https://docs.smartlyq.com/api-reference/webhooks/list-webhooks.md): List the workspace's webhook subscriptions and the available event names. Requires scope `webhooks:read`. - [Create webhook](https://docs.smartlyq.com/api-reference/webhooks/create-webhook.md): 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, messa… - [Update webhook](https://docs.smartlyq.com/api-reference/webhooks/update-webhook.md): Update a webhook's `url`, `events`, or `status`. Only supplied fields change. `url` is re-validated (public HTTPS, SSRF-guarded); `events` must all come from the 25-event catalog (unknown names are rejected); setting `status` to `active` also recovers an endpoint auto-paused as `failing`. Requires s… - [Send test webhook](https://docs.smartlyq.com/api-reference/webhooks/send-test-webhook.md): 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… - [List webhook delivery logs](https://docs.smartlyq.com/api-reference/webhooks/list-webhook-delivery-logs.md): Paginated log of webhook delivery attempts across your endpoints, newest first (90-day retention). Each row carries the full delivery envelope, the destination's response code and a response-body excerpt, the attempt count, and the next retry time when pending. Requires scope `webhooks:read`. Not av… - [Delete webhook](https://docs.smartlyq.com/api-reference/webhooks/delete-webhook.md): Delete a webhook subscription. Requires scope `webhooks:write`. - [Replay a webhook delivery](https://docs.smartlyq.com/api-reference/webhooks/replay-a-webhook-delivery.md): Re-queue a past delivery so it is sent again - the fix-up after your receiver was down or rejecting. The original event and payload are replayed unchanged and signed afresh, and the attempt counter resets so retry backoff starts clean. Find delivery ids with `GET /webhooks/logs`. - [List developer logs](https://docs.smartlyq.com/api-reference/logs/list-developer-logs.md): Your workspace's own request history: API calls and webhook delivery attempts merged into one time-ordered feed, newest first, with 90-day retention. `source` tells the two apart and decides which fields are populated - API rows carry method/endpoint/timing/cost, webhook rows carry event/attempt/sta… - [Create or upsert a contact](https://docs.smartlyq.com/api-reference/crm-contacts/create-or-upsert-a-contact.md): Create a CRM contact. With no `id` and a matching `email`, the existing contact is updated instead of duplicated (upsert). Fires the contact_created / contact_updated automation events. - [Bulk import contacts](https://docs.smartlyq.com/api-reference/crm/bulk-import-contacts.md): Import up to 100 contacts in one call. Each row goes through the same email/phone upsert as POST /contacts, so re-importing the same file is idempotent. Per-row results report created / updated / failed. Requires scope `contacts:write`. - [List contacts](https://docs.smartlyq.com/api-reference/crm-contacts/list-contacts.md): List CRM contacts in the workspace. Supports `search`, `tag` and `status` filters plus pagination. - [Get a contact](https://docs.smartlyq.com/api-reference/crm-contacts/get-a-contact.md) - [Delete contact](https://docs.smartlyq.com/api-reference/crm/delete-contact.md): Soft-deletes the contact (recoverable from Deleted contacts in the app). Requires scope `contacts:write`. - [Update a contact](https://docs.smartlyq.com/api-reference/crm-contacts/update-a-contact.md): Update a contact by id. Fires the contact_updated automation event (plus tag_added / tag_removed for tag changes). - [Add tags to a contact](https://docs.smartlyq.com/api-reference/crm-contacts/add-tags-to-a-contact.md): Add one or more tags (idempotent union). Each newly added tag fires the tag_added automation event. - [Remove tags from a contact](https://docs.smartlyq.com/api-reference/crm-contacts/remove-tags-from-a-contact.md): Remove one or more tags. Each removed tag fires the tag_removed automation event. - [Set one custom field](https://docs.smartlyq.com/api-reference/crm-contacts/set-one-custom-field.md): Set a single custom field on a contact by its slug (the field's key). The slug must be a defined custom field in this workspace (create one with POST /custom-fields). Merges into the contact's attributes without touching other fields. Requires contacts:write. - [Clear one custom field](https://docs.smartlyq.com/api-reference/crm-contacts/clear-one-custom-field.md): Remove a single custom field from a contact by slug. Succeeds (200) even if the field was not set. Requires contacts:write. - [Contact channels](https://docs.smartlyq.com/api-reference/crm/contact-channels.md): The channels this contact has actually communicated on (from the conversation timeline), with per-channel volume and last activity - pick the right channel before reaching out. Requires scope `contacts:read`. - [List contact notes](https://docs.smartlyq.com/api-reference/crm-contacts/list-contact-notes.md) - [Add a note to a contact](https://docs.smartlyq.com/api-reference/crm-contacts/add-a-note-to-a-contact.md) - [Enroll a contact in an automation](https://docs.smartlyq.com/api-reference/crm-contacts/enroll-a-contact-in-an-automation.md): Enrol a contact into an active automation. Queues a run for that automation carrying the contact's context. - [Log a message on a contact's timeline](https://docs.smartlyq.com/api-reference/crm-contacts/log-a-message-on-a-contacts-timeline.md): Record an inbound/outbound message in the contact's conversation timeline (feeds the Inbox). Does NOT deliver email/SMS — channel delivery goes through automations/campaigns, which carry billing + compliance. - [List custom fields](https://docs.smartlyq.com/api-reference/crm-custom-fields/list-custom-fields.md): List CRM custom field (custom attribute) definitions — the schema behind {{attributes.}}. - [Create a custom field](https://docs.smartlyq.com/api-reference/crm-custom-fields/create-a-custom-field.md): Define a new CRM custom field. Its attr_key is derived from the label and is used to set values via the contact's `attributes` object. - [Update custom field](https://docs.smartlyq.com/api-reference/crm/update-custom-field.md): Updates the definition (label, type, options, default, group, sort order). attr_key is immutable - it names the values already stored on contacts. Requires scope `contacts:write`. - [Delete a custom field](https://docs.smartlyq.com/api-reference/crm-custom-fields/delete-a-custom-field.md) - [List pipelines](https://docs.smartlyq.com/api-reference/crm-opportunities/list-pipelines.md): List sales pipelines in the workspace, each with its ordered stages. - [Create a pipeline](https://docs.smartlyq.com/api-reference/crm-opportunities/create-a-pipeline.md) - [List opportunities](https://docs.smartlyq.com/api-reference/crm-opportunities/list-opportunities.md): List deals/opportunities. Filter by `pipeline_id`, `status`, `stage` or `assigned_user_id`. - [Create an opportunity](https://docs.smartlyq.com/api-reference/crm-opportunities/create-an-opportunity.md): Create a deal/opportunity. Fires deal_created (and deal_won / deal_lost when created with a terminal status). Falls back to the default pipeline when `pipeline_id` is omitted. - [Get an opportunity](https://docs.smartlyq.com/api-reference/crm-opportunities/get-an-opportunity.md) - [Update an opportunity](https://docs.smartlyq.com/api-reference/crm-opportunities/update-an-opportunity.md): Update a deal. Moving `stage` follows won/lost stage semantics into `status` unless `status` is set explicitly. Fires deal_stage_changed / deal_won / deal_lost as applicable. - [Update opportunity status](https://docs.smartlyq.com/api-reference/crm-opportunities/update-opportunity-status.md): Set the opportunity outcome. Transitioning into won/lost fires deal_won / deal_lost. - [Delete an opportunity](https://docs.smartlyq.com/api-reference/crm-opportunities/delete-an-opportunity.md) - [Create a workspace (sub-account)](https://docs.smartlyq.com/api-reference/workspaces/create-a-workspace-sub-account.md): Create a sub-account workspace under the agency the API key belongs to. Requires the workspaces:write scope; plan workspace caps apply. - [Bulk sub-account action](https://docs.smartlyq.com/api-reference/workspaces/bulk-sub-account-action.md): Apply one lifecycle action - pause, resume, or disable_saas - to many client sub-accounts in a single call. **Requires an active SaaS plan**: the agency must have a connected, charges-enabled Stripe account able to bill its clients; otherwise the call returns 403 SAAS_PLAN_REQUIRED. High-trust: requ… - [List workspaces (sub-accounts)](https://docs.smartlyq.com/api-reference/workspaces/list-workspaces-sub-accounts.md): List the sub-account workspaces under the agency the API key belongs to, each with its billing state and sub-wallet balance. Requires the workspaces:read scope. - [Get a workspace (sub-account)](https://docs.smartlyq.com/api-reference/workspaces/get-a-workspace-sub-account.md): Get one sub-account: name, account type, billing mode, rebilling state, and sub-wallet balance. Requires the workspaces:read scope. - [Disable SaaS mode for a workspace](https://docs.smartlyq.com/api-reference/workspaces/disable-saas-mode-for-a-workspace.md): Disable SaaS mode for a sub-account: switch it back to agency billing, turn off rebilling, and refund any remaining sub-wallet balance to the agency wallet. Optionally cancels the client's subscription. Required before a SaaS sub-account can be deleted. Requires the workspaces:write scope. **SaaS-me… - [Delete a workspace (sub-account)](https://docs.smartlyq.com/api-reference/workspaces/delete-a-workspace-sub-account.md): Permanently delete a client sub-account. The workspace is scheduled for asynchronous teardown and disappears immediately; its data is purged within a few minutes. Blocked (409) while the sub-account is still in SaaS mode - disable SaaS first - and blocked (422) for the agency's own workspaces. Requi… - [Pause (suspend) a workspace](https://docs.smartlyq.com/api-reference/workspaces/pause-suspend-a-workspace.md): Pause a client sub-account: block all access + operations for its users, but keep the data (reversible with resume). Cannot pause the agency's own workspaces. Requires the workspaces:write scope. - [Resume a paused workspace](https://docs.smartlyq.com/api-reference/workspaces/resume-a-paused-workspace.md): Reactivate a paused sub-account: restore access + operations. Requires the workspaces:write scope. - [Get a sub-account's subscription](https://docs.smartlyq.com/api-reference/workspaces/get-a-sub-accounts-subscription.md): Read a sub-account's SaaS subscription + billing snapshot: billing_mode, rebilling state, plan_id, Stripe subscription_status, billing_cycle, and sub-wallet balance. Requires the workspaces:read scope. - [Get a sub-account's wallet balance](https://docs.smartlyq.com/api-reference/workspaces/get-a-sub-accounts-wallet-balance.md): Read a sub-account's wallet balance in SQC. Requires the workspaces:read scope. - [List SaaS plans](https://docs.smartlyq.com/api-reference/workspaces/list-saas-plans.md): List the SaaS plans (client packages) configured for the agency the API key belongs to, with price, interval, setup fee, features and limits. Read-only. Requires the workspaces:read scope. - [Get a SaaS plan](https://docs.smartlyq.com/api-reference/workspaces/get-a-saas-plan.md): Get one SaaS plan (client package) by id. Read-only. Requires the workspaces:read scope. - [Create a profile](https://docs.smartlyq.com/api-reference/profiles/create-a-profile.md): Create a profile - a managed sub-account for one end-customer of your product. Connected accounts inside profiles are billed monthly per account from your API wallet (no plan caps). Requires the profiles:write scope. - [List profiles](https://docs.smartlyq.com/api-reference/profiles/list-profiles.md): List your profiles (newest first). Requires the profiles:read scope. - [Get a profile](https://docs.smartlyq.com/api-reference/profiles/get-a-profile.md) - [Update a profile](https://docs.smartlyq.com/api-reference/profiles/update-a-profile.md): Rename a profile and/or change its external_id. Only the fields you send are modified; renaming also renames the profile's backing workspace so the two never drift. Requires `profiles:write`. - [List a profile's connected accounts](https://docs.smartlyq.com/api-reference/profiles/list-a-profiles-connected-accounts.md): The social accounts the end-customer has connected to this profile. Requires the profiles:read scope. - [Create a hosted connect link](https://docs.smartlyq.com/api-reference/profiles/create-a-hosted-connect-link.md): Mints a signed, single-use hosted page URL you forward to your end-customer. They open it with no login, pick platforms, and approve access; connected accounts land in this profile. The link dies for other browsers once opened. Requires the profiles:write scope. - [Get a raw connect URL for one platform](https://docs.smartlyq.com/api-reference/profiles/get-a-raw-connect-url-for-one-platform.md): Per-platform OAuth connect URL targeting this profile, for developers building their own connect UI. Same mechanics as POST /social/connect/{platform}. Requires the profiles:write scope. - [Pause a profile](https://docs.smartlyq.com/api-reference/profiles/pause-a-profile.md): Pause a profile: its workspace is suspended, delegated calls return 409, and its accounts stop counting toward monthly account billing. Requires the profiles:write scope. - [Resume a profile](https://docs.smartlyq.com/api-reference/profiles/resume-a-profile.md): Resume a paused profile. Requires the profiles:write scope. - [Delete a profile](https://docs.smartlyq.com/api-reference/profiles/delete-a-profile.md): Soft-deletes the profile and schedules async teardown of its workspace and connected accounts. Send {"confirm": "DELETE"} in the body. Requires the profiles:write scope. - [Account billing summary](https://docs.smartlyq.com/api-reference/profiles/account-billing-summary.md): Live count of billable connected accounts across your profiles, the price bands, the estimated next monthly charge, and recent billing history. Accounts are billed per calendar month from your API wallet: \$6 each for accounts 1-10, \$3 for 11-100, \$1 from 101 up, snapshotted on the 1st (UTC). Requ… - [Generate article](https://docs.smartlyq.com/api-reference/articles/generate-article.md): Start article generation. Returns 202 with job_id; poll GET /jobs/{job_id} for result. Either `topic` or `keywords` must be provided. - [List articles](https://docs.smartlyq.com/api-reference/articles/list-articles.md) - [Get article](https://docs.smartlyq.com/api-reference/articles/get-article.md) - [Delete article](https://docs.smartlyq.com/api-reference/articles/delete-article.md) - [Generate image](https://docs.smartlyq.com/api-reference/images/generate-image.md): Returns 202 with job_id for async generation. Either `prompt` or `description` must be provided. - [List images](https://docs.smartlyq.com/api-reference/images/list-images.md) - [Get image](https://docs.smartlyq.com/api-reference/images/get-image.md) - [Delete image](https://docs.smartlyq.com/api-reference/images/delete-image.md) - [List available video models](https://docs.smartlyq.com/api-reference/videos/list-available-video-models.md): Returns every model currently available for video generation, including valid parameter values for each model and generation type. - [Generate video](https://docs.smartlyq.com/api-reference/videos/generate-video.md): 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. - [List videos](https://docs.smartlyq.com/api-reference/videos/list-videos.md) - [Get video](https://docs.smartlyq.com/api-reference/videos/get-video.md) - [Delete video](https://docs.smartlyq.com/api-reference/videos/delete-video.md) - [Generate a viral hook line](https://docs.smartlyq.com/api-reference/videos/generate-a-viral-hook-line.md): Writes ONE scroll-stopping hook line (<=8 words) to overlay on a short's first seconds. Provide `script` or `transcript_words`. Billed per request from your API wallet; refunded on failure. - [Suggest B-roll moments](https://docs.smartlyq.com/api-reference/videos/suggest-b-roll-moments.md): Suggests B-roll moments (with timings) for a word-level transcript. Billed per request; refunded on failure. - [Suggest on-screen emphasis](https://docs.smartlyq.com/api-reference/videos/suggest-on-screen-emphasis.md): Picks on-screen emphasis moments (punchy full-screen text with timings) from a word-level transcript. Billed per request; refunded on failure. - [Generate a viral thumbnail](https://docs.smartlyq.com/api-reference/videos/generate-a-viral-thumbnail.md): Generates a viral, click-optimized thumbnail from a video title (optionally guided by a reference image) and returns a hosted `image_url`. Billed per request; refunded on failure. - [Generate viral shorts from a long video](https://docs.smartlyq.com/api-reference/shorts/generate-viral-shorts-from-a-long-video.md): Turns one long video into ranked, ready-to-post vertical (9:16) clips with hooks + virality scores. Provide `video_url` (direct media) OR `source_url` (a YouTube/Vimeo/TikTok link). Returns `202 Accepted` with a `job_uid`; poll `GET /v1/shorts/{uid}`. Billed per REQUESTED clip from your API wallet;… - [List shorts jobs](https://docs.smartlyq.com/api-reference/shorts/list-shorts-jobs.md): Lists your workspace's Magic Shorts jobs. - [Get shorts job + clips](https://docs.smartlyq.com/api-reference/shorts/get-shorts-job-+-clips.md): Gets a Magic Shorts job's status and its ranked clips (hooks, scores, clip URLs). Poll after `generateShorts` until `status` is `completed`. - [Generate presentation](https://docs.smartlyq.com/api-reference/presentations/generate-presentation.md): Generates a complete AI presentation (slide deck) from a single prompt. Returns `202 Accepted` immediately with a `job_id`; poll `GET /v1/jobs/{job_uid}` for status. Generation typically takes 60-120 seconds. When the job completes, its `result` contains the `presentation_id` and a `url` that opens… - [List presentations](https://docs.smartlyq.com/api-reference/presentations/list-presentations.md): Lists the authenticated user's presentations, newest first. Requires the `presentations:read` scope. Read-only - consumes no credits. - [Get presentation](https://docs.smartlyq.com/api-reference/presentations/get-presentation.md): Returns a presentation's details including its editor URL and, when public, its share URL. Requires the `presentations:read` scope. Read-only - consumes no credits. - [Delete presentation](https://docs.smartlyq.com/api-reference/presentations/delete-presentation.md): Permanently deletes a presentation and removes it from the media library. Requires the `presentations:write` scope. - [Text to speech](https://docs.smartlyq.com/api-reference/audio/text-to-speech.md) - [Speech to text](https://docs.smartlyq.com/api-reference/audio/speech-to-text.md) - [Get audio](https://docs.smartlyq.com/api-reference/audio/get-audio.md) - [Rewrite content](https://docs.smartlyq.com/api-reference/content/rewrite-content.md) - [Generate a social caption](https://docs.smartlyq.com/api-reference/content/generate-a-social-caption.md): Writes ONE platform-tuned social caption (with hashtags) for a short-form video. Billed per request; refunded on failure. - [Keyword research](https://docs.smartlyq.com/api-reference/seo/keyword-research.md): Keyword suggestions for a seed keyword with real monthly search volume, CPC and competition. - [Live SERP lookup](https://docs.smartlyq.com/api-reference/seo/live-serp-lookup.md): Live Google organic SERP for a keyword: ranked results, SERP features and People Also Ask. - [Keyword difficulty](https://docs.smartlyq.com/api-reference/seo/keyword-difficulty.md): Bulk keyword difficulty scores (0-100) for a list of keywords. - [Ranked keywords (rank tracking)](https://docs.smartlyq.com/api-reference/seo/ranked-keywords-rank-tracking.md): Every keyword a domain ranks for, with position, search volume and estimated traffic. - [Domain rank overview](https://docs.smartlyq.com/api-reference/seo/domain-rank-overview.md): Organic rank overview for a domain: estimated keyword count, traffic value and position buckets. - [Organic competitors](https://docs.smartlyq.com/api-reference/seo/organic-competitors.md): Domains overlapping a target on shared keywords, with common-keyword counts and traffic. - [Backlink profile summary](https://docs.smartlyq.com/api-reference/seo/backlink-profile-summary.md): Backlink profile summary for a domain: authority rank, totals, referring domains, broken links and link types. - [On-page SEO audit](https://docs.smartlyq.com/api-reference/seo/on-page-seo-audit.md): Instant on-page SEO audit for a single URL: on-page score and flagged checks. - [Backlink prospects (link gap)](https://docs.smartlyq.com/api-reference/seo/backlink-prospects-link-gap.md): Find link-building prospects: referring domains that link to competitors of the target but not to the target itself. - [Referring domains](https://docs.smartlyq.com/api-reference/seo/referring-domains.md): List the top referring domains for a domain by authority, with backlink counts, first-seen date and dofollow counts. - [Backlink anchors](https://docs.smartlyq.com/api-reference/seo/backlink-anchors.md): List the top backlink anchor texts for a domain, with backlink and referring-domain counts. - [Backlink spam score](https://docs.smartlyq.com/api-reference/seo/backlink-spam-score.md): Get the backlink spam/toxicity score (0-100) for one or more domains. - [Historical rank overview](https://docs.smartlyq.com/api-reference/seo/historical-rank-overview.md): Historical organic rank/traffic trend by month. Premium lookup. Async: returns 202 + job_uid - poll GET /jobs/{job_uid} for the result. - [Deep site audit](https://docs.smartlyq.com/api-reference/seo/deep-site-audit.md): Deep crawl-based technical site audit. Async: returns 202 + job_uid - poll GET /jobs/{job_uid}; result_data carries the audit (typically 30-90s). - [AI Visibility: brand lookup](https://docs.smartlyq.com/api-reference/seo/ai-visibility:-brand-lookup.md): AI Visibility brand/domain citation lookup. Async: returns 202 + job_uid - poll GET /jobs/{job_uid} for the result (may take ~1 minute). - [AI Visibility: prompt explorer](https://docs.smartlyq.com/api-reference/seo/ai-visibility:-prompt-explorer.md): Run a prompt across ChatGPT/Claude/Gemini/Perplexity. Async: returns 202 + job_uid - poll GET /jobs/{job_uid} for the result (1-2 minutes). - [AI Visibility Audit (async)](https://docs.smartlyq.com/api-reference/seo/ai-visibility-audit-async.md): 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… - [List social accounts](https://docs.smartlyq.com/api-reference/social/list-social-accounts.md): Returns all connected social media accounts for the authenticated user. - [Bulk account health](https://docs.smartlyq.com/api-reference/social/bulk-account-health.md): Health of every connected account in one call: healthy / expiring (token within 7 days) / expired / paused tallies plus per-account status. Same fields as the per-account health endpoint. Requires scope `social:read`. - [Live account insights](https://docs.smartlyq.com/api-reference/social/live-account-insights.md): LIVE account metrics straight from the platform (followers, following, posts, profile views, impressions, reach, engagements, new followers - whatever the platform exposes), via the same per-platform providers the daily analytics sync uses. Works for every connected platform with an analytics provid… - [Connection target options](https://docs.smartlyq.com/api-reference/social/connection-target-options.md): Which entity this connection is bound to and, where the stored token allows, the alternatives it could be re-pointed at. Google Business tokens are user-level, so every location under the parent account is selectable; platforms with entity-bound tokens (e.g. Facebook page tokens) report supported: f… - [Select connection target](https://docs.smartlyq.com/api-reference/social/select-connection-target.md): Re-points a Google Business connection at another location of the same parent account (the assign-location operation). The target is verified against Google's live location list - never trusted from input. Requires scope `social:write`. - [Get Messenger menu](https://docs.smartlyq.com/api-reference/social/get-messenger-menu.md): The Facebook page's persistent menu (Meta messenger_profile shape). Requires scope `social:read`. - [Set Messenger menu](https://docs.smartlyq.com/api-reference/social/set-messenger-menu.md): Replaces the page's persistent menu (Meta menu objects, passthrough). Requires scope `social:write`. - [Delete Messenger menu](https://docs.smartlyq.com/api-reference/social/delete-messenger-menu.md) - [Get ice breakers](https://docs.smartlyq.com/api-reference/social/get-ice-breakers.md): The Instagram account's DM ice breakers (the FAQ chips new visitors see). Requires scope `social:read`. - [Set ice breakers](https://docs.smartlyq.com/api-reference/social/set-ice-breakers.md): Replaces the ice breakers (1-4 Meta ice-breaker objects, passthrough). Requires scope `social:write`. - [Delete ice breakers](https://docs.smartlyq.com/api-reference/social/delete-ice-breakers.md) - [Facebook page insights](https://docs.smartlyq.com/api-reference/social/facebook-page-insights.md): Metric passthrough to Meta's Page Insights: request any page metric by name (Meta validates, so new metrics work without waiting for us). Defaults to impressions, engagements and fans. Requires scope `analytics:read`. - [Instagram audience demographics](https://docs.smartlyq.com/api-reference/social/instagram-audience-demographics.md): Follower demographics by city, country, age or gender (IG follower_demographics insights). Instagram requires 100+ followers and hides small buckets - its errors are surfaced verbatim. Requires scope `analytics:read`. - [Follower stats](https://docs.smartlyq.com/api-reference/social/follower-stats.md): Daily follower history and growth per account, from the analytics snapshots the platform collects. Requires scope `social:read`. - [Start headless account connection](https://docs.smartlyq.com/api-reference/social/start-headless-account-connection.md): 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… - [Poll headless connection status](https://docs.smartlyq.com/api-reference/social/poll-headless-connection-status.md): 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 `connec… - [Rename account](https://docs.smartlyq.com/api-reference/social/rename-account.md): Rename a connected social account (display name inside SmartlyQ - does not change anything on the platform). Requires scope `social:write`. - [Account health](https://docs.smartlyq.com/api-reference/social/account-health.md) - [Account reconnect URL](https://docs.smartlyq.com/api-reference/social/account-reconnect-url.md) - [TikTok creator info](https://docs.smartlyq.com/api-reference/social/tiktok-creator-info.md): Live TikTok creator settings for a connected TikTok account: available privacy levels, whether comments/duet/stitch are disabled, and the account's maximum video duration. TikTok requires surfacing these before showing post options. Requires scope `social:read`. - [Pinterest boards](https://docs.smartlyq.com/api-reference/social/pinterest-boards.md): The account's Pinterest boards (id, name, privacy) - required to target a board when pinning. Requires scope `social:read`. - [YouTube playlists](https://docs.smartlyq.com/api-reference/social/youtube-playlists.md): The channel's playlists (title, privacy, item count) - target one when uploading. Requires scope `social:read`. - [Instagram publishing limit](https://docs.smartlyq.com/api-reference/social/instagram-publishing-limit.md): Instagram's daily content-publishing quota for this account: total, remaining, and whether a publish would be allowed right now. Requires scope `social:read`. - [Google Business performance](https://docs.smartlyq.com/api-reference/social/google-business-performance.md): Business Profile performance for the window: impressions by surface (Search/Maps, mobile/desktop) with deltas vs the previous window, plus a daily series. Data lags ~1 day (Google). Requires scope `social:read`. - [Google Business search keywords](https://docs.smartlyq.com/api-reference/social/google-business-search-keywords.md): The search terms people used on Google before seeing this Business Profile, with monthly impression counts. Requires scope `social:read`. - [Instagram stories](https://docs.smartlyq.com/api-reference/social/instagram-stories.md): The account's currently live stories (id, media type, URL, permalink, timestamp). Requires scope `social:read`. - [Instagram story insights](https://docs.smartlyq.com/api-reference/social/instagram-story-insights.md): Insights for one story. Defaults to views and replies; pass ?metrics= (comma-separated) to request other metrics - Instagram validates them, so newly released metrics work without waiting for us. Requires scope `analytics:read`. - [X mentions](https://docs.smartlyq.com/api-reference/social/x-mentions.md): Recent posts mentioning the connected X account, with engagement metrics. Requires scope `social:read`. - [Retweet on X](https://docs.smartlyq.com/api-reference/social/retweet-on-x.md): Retweets a post with the connected X account. Covered by the tweet.write permission your connection already has. Requires scope `social:write`. - [Undo retweet](https://docs.smartlyq.com/api-reference/social/undo-retweet.md): Removes the account's retweet of a post. Requires scope `social:write`. - [Facebook post reactions](https://docs.smartlyq.com/api-reference/social/facebook-post-reactions.md): Reaction-type breakdown (like, love, wow, haha, sad, angry, care) for a published Facebook post. Pass remote_post_id, or post_id of a SmartlyQ post published to this account. Requires scope `social:read`. - [Reddit search](https://docs.smartlyq.com/api-reference/social/reddit-search.md): Search Reddit (optionally restricted to one subreddit) with the account's own credentials - find where a topic is being discussed before posting. Requires scope `social:read`. - [Reddit feed](https://docs.smartlyq.com/api-reference/social/reddit-feed.md): The account's home feed or one subreddit's feed (hot / new / top / rising). Requires scope `social:read`. - [Subscribed subreddits](https://docs.smartlyq.com/api-reference/social/subscribed-subreddits.md): Subreddits the connected account subscribes to (name, title, subscriber count). Requires scope `social:read`. - [Subreddit info + eligibility](https://docs.smartlyq.com/api-reference/social/subreddit-info-+-eligibility.md): Subreddit details plus a posting-eligibility check for THIS connected account: does it exist, what submission kinds it accepts, is the account banned, and a computed can_post verdict. Check before submitting. Requires scope `social:read`. - [Subreddit rules](https://docs.smartlyq.com/api-reference/social/subreddit-rules.md): A subreddit's posting rules - check them BEFORE submitting so the post doesn't get removed. Requires scope `social:read`. - [Pause posting to an account](https://docs.smartlyq.com/api-reference/social/pause-posting-to-an-account.md) - [Resume posting to an account](https://docs.smartlyq.com/api-reference/social/resume-posting-to-an-account.md) - [Disconnect a social account](https://docs.smartlyq.com/api-reference/social/disconnect-a-social-account.md) - [Move account to profile](https://docs.smartlyq.com/api-reference/social/move-account-to-profile.md): Move a connected account between your developer workspace and one of your profiles (or profile to profile). Pass profile_id 0 to move it back to the developer workspace. Must be called WITHOUT X-Profile-Id; requires scopes `social:write` AND `profiles:manage`. Rejected with 409 while the account has… - [List account groups](https://docs.smartlyq.com/api-reference/social/list-account-groups.md): Named sets of connected accounts, so integrations can address a whole client or brand with one id. Requires scope `social:read`. - [Create account group](https://docs.smartlyq.com/api-reference/social/create-account-group.md): Create a group (max 50 per workspace, 100 accounts per group). Every account id must be a connected account of this workspace. Requires scope `social:write`. - [Get account group](https://docs.smartlyq.com/api-reference/social/get-account-group.md) - [Update account group](https://docs.smartlyq.com/api-reference/social/update-account-group.md): Update the name and/or replace the member list. Requires scope `social:write`. - [Delete account group](https://docs.smartlyq.com/api-reference/social/delete-account-group.md): Deletes the group only - the accounts stay connected. Requires scope `social:write`. - [Get Facebook page details](https://docs.smartlyq.com/api-reference/social/get-facebook-page-details.md): The page's own profile - name, about, description, category, contact details, address, opening hours, follower counts and publish state. These are the fields a management screen shows and edits; the performance numbers live on `/facebook/page-insights`. - [Update Facebook page details](https://docs.smartlyq.com/api-reference/social/update-facebook-page-details.md): Edit the page's public details. Send only the fields you want to change. - [Create a Pinterest board](https://docs.smartlyq.com/api-reference/social/create-a-pinterest-board.md): Create a board to pin into. Listing the existing boards is the GET on this same path. - [Update a YouTube playlist](https://docs.smartlyq.com/api-reference/social/update-a-youtube-playlist.md): Rename a playlist, change its description, or change who can see it. Send only what you want to change: YouTube's own update replaces every field you submit, so SmartlyQ reads the playlist first and merges, rather than blanking the fields you left out. - [List mentions](https://docs.smartlyq.com/api-reference/social/list-mentions.md): Posts where this account was tagged. Facebook pages return posts they were tagged in; Instagram returns media the account was @-mentioned in. X has its own richer endpoint at `/social/accounts/{account_id}/x/mentions`. - [Reply to a mention](https://docs.smartlyq.com/api-reference/social/reply-to-a-mention.md): Reply publicly to a mention. On Facebook this comments on the tagged post; on Instagram it goes through the mentions edge, which is how Meta expects a business to answer a tag. - [List subreddit post flairs](https://docs.smartlyq.com/api-reference/social/list-subreddit-post-flairs.md): The post flairs a subreddit offers. Many subreddits reject a submission that has no flair, so read this first and pass the id back as `platform_options.reddit.flair_id` when you post. - [List Google locations](https://docs.smartlyq.com/api-reference/social/list-google-locations.md): Every location under the connected profile's parent Google account (multi-location businesses). Override fields with ?read_mask=. Requires a connected Google Business account; bodies/responses are honest passthroughs of Google's resource shapes, so every Google field works. Requires scope `social:re… - [Get business info](https://docs.smartlyq.com/api-reference/social/get-business-info.md): The location's full business information: hours, phone numbers, categories, service area, profile description, service items and more. Override fields with ?read_mask=. Requires a connected Google Business account; bodies/responses are honest passthroughs of Google's resource shapes, so every Google… - [Update business info](https://docs.smartlyq.com/api-reference/social/update-business-info.md): Updates any Google Location fields named in update_mask - hours, phone, website, description, categories, service items. Requires a connected Google Business account; bodies/responses are honest passthroughs of Google's resource shapes, so every Google field works. Requires scope `social:write`. - [Get attributes](https://docs.smartlyq.com/api-reference/social/get-attributes.md): The attributes currently set on the location (Wi-Fi, outdoor seating, wheelchair access, ...). Requires a connected Google Business account; bodies/responses are honest passthroughs of Google's resource shapes, so every Google field works. Requires scope `social:read`. - [Available attributes](https://docs.smartlyq.com/api-reference/social/available-attributes.md): Which attributes Google allows for THIS location's category, with display names and value types - fetch before updating attributes. Requires a connected Google Business account; bodies/responses are honest passthroughs of Google's resource shapes, so every Google field works. Requires scope `social:… - [Update attributes](https://docs.smartlyq.com/api-reference/social/update-attributes.md): Sets/updates the attributes named in attribute_mask. Discover what this location supports with GET .../attributes/metadata. Requires a connected Google Business account; bodies/responses are honest passthroughs of Google's resource shapes, so every Google field works. Requires scope `social:write`. - [List media](https://docs.smartlyq.com/api-reference/social/list-media.md): Photos/videos on the Business Profile with view counts and Google-hosted URLs. Requires a connected Google Business account; bodies/responses are honest passthroughs of Google's resource shapes, so every Google field works. Requires scope `social:read`. - [Add photo](https://docs.smartlyq.com/api-reference/social/add-photo.md): Publishes a photo to the Business Profile from a public URL. Requires a connected Google Business account; bodies/responses are honest passthroughs of Google's resource shapes, so every Google field works. Requires scope `social:write`. - [Delete media](https://docs.smartlyq.com/api-reference/social/delete-media.md): Removes a media item; name must be a media resource of this location. Requires a connected Google Business account; bodies/responses are honest passthroughs of Google's resource shapes, so every Google field works. Requires scope `social:write`. - [Get food menus](https://docs.smartlyq.com/api-reference/social/get-food-menus.md): The location's structured food menus (sections, items, prices). ONLY available for food-serving business categories (restaurants, cafes, bakeries...) - Google returns a precondition error for other business types, which we pass through as a clear 502. Requires a connected Google Business account; bo… - [Update food menus](https://docs.smartlyq.com/api-reference/social/update-food-menus.md): Replaces the structured menus with the given Google FoodMenu objects. ONLY available for food-serving business categories - other business types get Google's precondition error passed through. Requires a connected Google Business account; bodies/responses are honest passthroughs of Google's resource… - [List place-action links](https://docs.smartlyq.com/api-reference/social/list-place-action-links.md): The location's action links shown on Google (order, reserve, appointment, menu...). Requires a connected Google Business account; bodies/responses are honest passthroughs of Google's resource shapes, so every Google field works. Requires scope `social:read`. - [Create place-action link](https://docs.smartlyq.com/api-reference/social/create-place-action-link.md): Adds an action link (APPOINTMENT, ORDER, RESERVATION, MENU, BOOK_ONLINE...). Requires a connected Google Business account; bodies/responses are honest passthroughs of Google's resource shapes, so every Google field works. Requires scope `social:write`. - [Update place-action link](https://docs.smartlyq.com/api-reference/social/update-place-action-link.md): Updates an action link's URI in place. name must belong to this location. Requires scope `social:write`. - [Delete place-action link](https://docs.smartlyq.com/api-reference/social/delete-place-action-link.md): Removes an action link; name must belong to this location. Requires a connected Google Business account; bodies/responses are honest passthroughs of Google's resource shapes, so every Google field works. Requires scope `social:write`. - [List verifications](https://docs.smartlyq.com/api-reference/social/list-verifications.md): Past and pending verification attempts for the location. Requires a connected Google Business account; bodies/responses are honest passthroughs of Google's resource shapes, so every Google field works. Requires scope `social:read`. - [Verification options](https://docs.smartlyq.com/api-reference/social/verification-options.md): Which verification methods Google offers this location (postcard, phone, email, auto). Requires a connected Google Business account; bodies/responses are honest passthroughs of Google's resource shapes, so every Google field works. Requires scope `social:read`. - [Create post (publish immediately)](https://docs.smartlyq.com/api-reference/social/create-post-publish-immediately.md) - [Schedule post](https://docs.smartlyq.com/api-reference/social/schedule-post.md): Pass queue_id (instead of scheduled_time) to drop the post into a posting queue's next open slot. Supports evergreen recycling via the optional `recycle` object: each published occurrence automatically schedules the next one until the chain hits its bound. - [Bulk schedule posts](https://docs.smartlyq.com/api-reference/social/bulk-schedule-posts.md): Schedule up to 50 posts in one call, from a JSON `posts` array or an inline `csv` string. Billed one post unit per row x platform. Any structural problem (missing fields, bad dates, in-batch duplicate rows) rejects the WHOLE batch with 422 before anything is created - and the charge is refunded. Aft… - [Validate a bulk batch](https://docs.smartlyq.com/api-reference/social/validate-a-bulk-batch.md): Free dry-run of the same batch body as POST /social/posts/bulk: per-row structural checks, per-platform caption/media limits, and the 24h duplicate-content check. Nothing is created or billed. Requires scope `social:read`. - [List social posts](https://docs.smartlyq.com/api-reference/social/list-social-posts.md): Posts imported by external sync carry status 'external' - filter with ?status=external. - [Get social post](https://docs.smartlyq.com/api-reference/social/get-social-post.md) - [Update social post](https://docs.smartlyq.com/api-reference/social/update-social-post.md) - [Retry publishing a post](https://docs.smartlyq.com/api-reference/social/retry-publishing-a-post.md) - [Unpublish post](https://docs.smartlyq.com/api-reference/social/unpublish-post.md): Delete a PUBLISHED post from its native platforms while keeping the SmartlyQ record - its status flips to `unpublished`. Optional `platforms` restricts which networks are removed. Supported for deletion: Threads, Facebook, LinkedIn, YouTube, X/Twitter, Pinterest, Tumblr, Bluesky, Google Business (In… - [Edit published post](https://docs.smartlyq.com/api-reference/social/edit-published-post.md): Edits a post that has ALREADY been published, natively on the platform. Honest per-platform support: Facebook page posts work today; X's edit API is paid-tier-only and Reddit's needs a re-auth scope - those report unsupported per platform instead of failing the call. The SmartlyQ record keeps its or… - [Update YouTube metadata](https://docs.smartlyq.com/api-reference/social/update-youtube-metadata.md): Post-publish updates for the post's YouTube leg: title, description, tags (snippet is fetched and merged so nothing else changes), add to a playlist, and/or set a custom thumbnail from a public URL (max 2MB). Requires scope `social:write`. - [Sync external posts](https://docs.smartlyq.com/api-reference/social/sync-external-posts.md): On-demand import of posts published natively on the platform (outside SmartlyQ) for one account - facebook, instagram, threads, youtube or tiktok. Imported posts appear in GET /social/posts with status 'external', with analytics snapshots. Discovery is a per-account opt-in: pass enable: true the fir… - [Stop recycling](https://docs.smartlyq.com/api-reference/social/stop-recycling.md): Stops an evergreen recycling chain: clears the recycle config on every post in the chain and cancels any not-yet-published auto-spawned occurrences back to draft. Works on any post in the chain (original or an occurrence). Unbilled. Requires scope `social:write`. - [Delete social post](https://docs.smartlyq.com/api-reference/social/delete-social-post.md) - [List queues](https://docs.smartlyq.com/api-reference/social/list-queues.md): List the workspace's posting queues (recurring weekly slot schedules). Requires scope `social:read`. - [Create queue](https://docs.smartlyq.com/api-reference/social/create-queue.md): Create a posting queue. Posts join it via `POST /social/posts/schedule` with `queue_id`; each post takes the next open slot (FIFO). Max 20 queues per workspace. Requires scope `social:write`. - [Get queue](https://docs.smartlyq.com/api-reference/social/get-queue.md): Fetch one queue, including its next open slot. Requires scope `social:read`. - [Update queue](https://docs.smartlyq.com/api-reference/social/update-queue.md): Update name, slots, timezone, or active state. Only supplied fields change; already-queued posts keep their resolved times. Requires scope `social:write`. - [Delete queue](https://docs.smartlyq.com/api-reference/social/delete-queue.md): Delete a queue. Posts already scheduled through it keep their resolved times. Requires scope `social:write`. - [Get next open slot](https://docs.smartlyq.com/api-reference/social/get-next-open-slot.md): The next unoccupied slot in the queue (UTC). For preview only - to actually schedule into the queue, pass `queue_id` to `POST /social/posts/schedule` (that call resolves and occupies the slot atomically). Requires scope `social:read`. - [Preview upcoming slots](https://docs.smartlyq.com/api-reference/social/preview-upcoming-slots.md): The next N open slots (default 10, max 50), continuing the same walk `next-slot` uses. Requires scope `social:read`. - [Validate post content](https://docs.smartlyq.com/api-reference/social/validate-post-content.md): Dry-run the same declarative checks the create path uses, WITHOUT creating anything: per-platform caption limits (each limit grounded in the platform handler or the platform's documented maximum), required-media rules (e.g. Instagram), and media extension screening. Free and unbilled. Platforms with… - [Validate media URL](https://docs.smartlyq.com/api-reference/social/validate-media-url.md): Checks that a media URL is publicly reachable and reports its content type, byte size, and detected kind (image/video). SSRF-guarded: private and internal hosts are rejected. Uses a HEAD request with a 1-byte ranged-GET fallback for CDNs that refuse HEAD. Free and unbilled. Requires scope `social:re… - [Get analytics overview](https://docs.smartlyq.com/api-reference/analytics/get-analytics-overview.md) - [Get post analytics](https://docs.smartlyq.com/api-reference/analytics/get-post-analytics.md) - [Post metric timeline](https://docs.smartlyq.com/api-reference/analytics/post-metric-timeline.md): Every metric snapshot collected for one post, per platform, oldest first - impressions, reach, engagements, likes, comments, shares, saves, clicks, video views over time. Requires scope `analytics:read`. - [Daily metrics](https://docs.smartlyq.com/api-reference/analytics/daily-metrics.md): Per-day aggregates across all accounts (impressions, reach, engagements, follower deltas, posts published) plus a per-platform breakdown. Computed from stored snapshots - fast and unbilled. Requires scope `analytics:read`. - [Best time to post](https://docs.smartlyq.com/api-reference/analytics/best-time-to-post.md): When your audience actually engages: a 7x24 heatmap of average engagement per published post by weekday and hour (in your timezone), plus the top 5 slots. Requires scope `analytics:read`. - [Content decay](https://docs.smartlyq.com/api-reference/analytics/content-decay.md): How long a post keeps working: the average share of a post's final engagement reached by each age-day (0-13), across posts published in the window. Requires scope `analytics:read`. - [Posting frequency vs engagement](https://docs.smartlyq.com/api-reference/analytics/posting-frequency-vs-engagement.md): Per ISO week: how many posts you published and what they averaged in engagement - the data behind 'are we posting too much or too little'. Requires scope `analytics:read`. - [Inbox volume](https://docs.smartlyq.com/api-reference/analytics/inbox-volume.md): Daily incoming/outgoing message counts plus new conversations started, across the social inbox. Requires scope `analytics:read`. - [Inbox heatmap](https://docs.smartlyq.com/api-reference/analytics/inbox-heatmap.md): Incoming messages bucketed by weekday and hour (in your timezone) - when your audience actually writes to you. Requires scope `analytics:read`. - [Inbox source breakdown](https://docs.smartlyq.com/api-reference/analytics/inbox-source-breakdown.md): Active conversations and message volume per platform. Requires scope `analytics:read`. - [Inbox response time](https://docs.smartlyq.com/api-reference/analytics/inbox-response-time.md): How fast you answer: for every incoming message answered by a later reply in the same conversation, the wait - average, median, and a histogram (under_15m, 15m_1h, 1h_4h, 4h_24h, over_24h). Requires scope `analytics:read`. - [Inbox top accounts](https://docs.smartlyq.com/api-reference/analytics/inbox-top-accounts.md): Your busiest connected accounts by incoming messages. Requires scope `analytics:read`. - [Inbox conversation stats](https://docs.smartlyq.com/api-reference/analytics/inbox-conversation-stats.md): Per-conversation message volume for the window, busiest first. Requires scope `analytics:read`. - [Conversation analytics](https://docs.smartlyq.com/api-reference/analytics/conversation-analytics.md): One conversation's full stats: message counts and response times (average, median). Requires scope `analytics:read`. - [Get account analytics](https://docs.smartlyq.com/api-reference/analytics/get-account-analytics.md) - [YouTube channel insights](https://docs.smartlyq.com/api-reference/analytics/youtube-channel-insights.md): Channel totals for a date range: views, watch time, average view duration and percentage, subscribers gained and lost, likes, dislikes, comments and shares. - [YouTube daily views](https://docs.smartlyq.com/api-reference/analytics/youtube-daily-views.md): Views, watch time, average view duration and subscribers gained broken down by day - the shape a time-series chart needs. - [YouTube audience retention](https://docs.smartlyq.com/api-reference/analytics/youtube-audience-retention.md): The retention curve for one video: what share of viewers is still watching at each point of the video, plus how that compares with similar videos on YouTube. Rows are ordered by `elapsedVideoTimeRatio`, from 0 (start) to 1 (end). - [YouTube viewer demographics](https://docs.smartlyq.com/api-reference/analytics/youtube-viewer-demographics.md): Viewer split by age bracket and gender, as a percentage of views. Pass `video_id` to scope it to one video. YouTube withholds demographics below a privacy threshold - that comes back as an empty `rows` array rather than an error. - [List reviews](https://docs.smartlyq.com/api-reference/reviews/list-reviews.md): Google Business reviews synced into SmartlyQ's Reputation Management, newest first. Filter by rating, reply status, or account. Requires scope `social:read`. - [Reply to review](https://docs.smartlyq.com/api-reference/reviews/reply-to-review.md): Publishes a reply to the review on Google Business. Requires scope `social:write`. - [Delete review reply](https://docs.smartlyq.com/api-reference/reviews/delete-review-reply.md): Removes the business reply from the review on Google Business and clears it in SmartlyQ (status returns to pending). Requires scope `social:write`. - [Sync reviews](https://docs.smartlyq.com/api-reference/reviews/sync-reviews.md): Pulls fresh reviews from Google Business on demand - one account (account_id) or every connected GBP account in the workspace. Requires scope `social:write`. - [List automations](https://docs.smartlyq.com/api-reference/automations/list-automations.md): The workspace's automations (built in the visual builder), with run/error counts. Requires scope `contacts:read`. - [Get automation](https://docs.smartlyq.com/api-reference/automations/get-automation.md): Full automation detail including the node graph. Requires scope `contacts:read`. - [Activate automation](https://docs.smartlyq.com/api-reference/automations/activate-automation.md): Turns the automation on (validates the graph has a trigger and at least one action; webhook triggers get their URL provisioned). Requires scope `contacts:write`. - [Pause automation](https://docs.smartlyq.com/api-reference/automations/pause-automation.md): Pauses the automation and its triggers. Requires scope `contacts:write`. - [Trigger automation](https://docs.smartlyq.com/api-reference/automations/trigger-automation.md): Queues a manual run with an optional payload (available to the automation's steps as the trigger payload). The automation must be active. Requires scope `contacts:write`. - [List runs](https://docs.smartlyq.com/api-reference/automations/list-runs.md): Run history, newest first. Requires scope `contacts:read`. - [Get run](https://docs.smartlyq.com/api-reference/automations/get-run.md): One run with its trigger payload and per-step execution logs. Requires scope `contacts:read`. - [Get presigned upload URL](https://docs.smartlyq.com/api-reference/media/get-presigned-upload-url.md) - [Upload a file directly](https://docs.smartlyq.com/api-reference/media/upload-a-file-directly.md): Upload a file in one multipart/form-data request - no presign step. The file is stored and recorded in your media library, and the response is the same shape as GET /media/{id}. The file type is detected from the bytes (not the declared Content-Type); max 200MB (upload larger media by URL). Requires… - [List media](https://docs.smartlyq.com/api-reference/media/list-media.md) - [Get media](https://docs.smartlyq.com/api-reference/media/get-media.md) - [Delete media](https://docs.smartlyq.com/api-reference/media/delete-media.md) - [Shorten URL](https://docs.smartlyq.com/api-reference/urls/shorten-url.md) - [List short URLs](https://docs.smartlyq.com/api-reference/urls/list-short-urls.md) - [Get short URL](https://docs.smartlyq.com/api-reference/urls/get-short-url.md) - [Get short URL stats](https://docs.smartlyq.com/api-reference/urls/get-short-url-stats.md) - [Delete short URL](https://docs.smartlyq.com/api-reference/urls/delete-short-url.md) - [Update a short URL](https://docs.smartlyq.com/api-reference/urls/update-a-short-url.md): Repoint an existing short link at a new destination, rename it, or deactivate it. The short code never changes, so links already printed, posted or scanned keep working and their click history stays attached. - [Send a WhatsApp message](https://docs.smartlyq.com/api-reference/whatsapp/send-a-whatsapp-message.md): Send a message from a connected WhatsApp number. `text`, `media`, `interactive_buttons`, `interactive_list`, `location`, `contacts`, and `flow` are SESSION messages - deliverable only inside the 24-hour customer window (i.e. after the user messaged you). Outside it, only `template` (an approved HSM)… - [List message templates](https://docs.smartlyq.com/api-reference/whatsapp/list-message-templates.md): List the WhatsApp Business Account's message templates. Requires social:read. - [Create a message template](https://docs.smartlyq.com/api-reference/whatsapp/create-a-message-template.md): Submit a message template to Meta for approval. Requires social:write. - [Get business profile](https://docs.smartlyq.com/api-reference/whatsapp/get-business-profile.md): Read the number's WhatsApp business profile. Requires social:read. - [Update business profile](https://docs.smartlyq.com/api-reference/whatsapp/update-business-profile.md): Update about/address/email/description/vertical/websites on the number's profile. Requires social:write. - [List phone numbers](https://docs.smartlyq.com/api-reference/whatsapp/list-phone-numbers.md): List the phone numbers on this connection's WhatsApp Business Account. Requires social:read. - [Get a WhatsApp template](https://docs.smartlyq.com/api-reference/whatsapp/get-a-whatsapp-template.md): One template by name. A template name can hold several rows - one per language - so this returns every translation under that name. Requires scope `social:read`. - [Update a WhatsApp template](https://docs.smartlyq.com/api-reference/whatsapp/update-a-whatsapp-template.md): Replace an existing template's components. Name and language are fixed at creation - changing either means creating a new template. Editing an approved template sends it back through Meta review. - [Delete a WhatsApp template](https://docs.smartlyq.com/api-reference/whatsapp/delete-a-whatsapp-template.md): Delete a template. Without `template_id` this removes every language version of the name; with it, only that one translation. Requires scope `social:write`. - [Set the WhatsApp profile photo](https://docs.smartlyq.com/api-reference/whatsapp/set-the-whatsapp-profile-photo.md): Set the profile picture customers see for this number. Meta does not accept an image URL here: upload the file through Meta's resumable upload API first and pass the handle it returns. - [Get the WhatsApp display name](https://docs.smartlyq.com/api-reference/whatsapp/get-the-whatsapp-display-name.md): The name customers see in chat, plus where any pending name change stands with Meta review and the number's current quality rating. Requires scope `social:read`. - [Request a WhatsApp display-name change](https://docs.smartlyq.com/api-reference/whatsapp/request-a-whatsapp-display-name-change.md): Submit a new display name. This does not take effect immediately - Meta reviews it, and the old name stays live until approval, so a 202 here means "submitted", not "changed". Poll `GET /whatsapp/business-profile/display-name` and watch `name_status`. - [Browse the shared template library](https://docs.smartlyq.com/api-reference/whatsapp/browse-the-shared-template-library.md): Meta's library of prewritten, pre-approved message templates. Adopting one skips the draft-and-wait-for-review cycle, so it is worth browsing before writing a template by hand. Adopt an entry with `POST /whatsapp/templates/from-library`. - [Adopt a library template](https://docs.smartlyq.com/api-reference/whatsapp/adopt-a-library-template.md): Create a template on your WhatsApp Business Account from a library entry. Meta clones the prewritten body under the name you choose; anything the entry leaves open, such as button URLs, is passed through from this request. - [List comments](https://docs.smartlyq.com/api-reference/comments/list-comments.md) - [Get one post's comments (threaded)](https://docs.smartlyq.com/api-reference/comments/get-one-posts-comments-threaded.md): Returns a single post's comments as a nested reply tree, with post metadata. A by-id convenience over GET /social/comments (which already threads replies). Reply nesting is populated for every platform except Pinterest (whose comments are flat). Requires social:read. - [Reply to a comment](https://docs.smartlyq.com/api-reference/comments/reply-to-a-comment.md) - [Private reply (comment-to-DM)](https://docs.smartlyq.com/api-reference/social/private-reply-comment-to-dm.md): Sends a DIRECT MESSAGE to the author of a Facebook or Instagram comment via Meta's private-reply mechanism. Meta allows one private reply per comment, within 7 days - violations are surfaced verbatim. Also available as the automation action `action.private_reply` paired with the `comment_created` tr… - [Hide or unhide a comment](https://docs.smartlyq.com/api-reference/comments/hide-or-unhide-a-comment.md) - [Delete a comment](https://docs.smartlyq.com/api-reference/comments/delete-a-comment.md) - [List DM conversations](https://docs.smartlyq.com/api-reference/direct-messages/list-dm-conversations.md) - [Search conversations](https://docs.smartlyq.com/api-reference/social/search-conversations.md): Full-inbox search across participant names and message content; each hit includes the latest matching message. Requires scope `social:read`. - [Get conversation](https://docs.smartlyq.com/api-reference/social/get-conversation.md): Conversation detail plus incoming/outgoing message counts. Requires scope `social:read`. - [Archive / reopen conversation](https://docs.smartlyq.com/api-reference/social/archive-reopen-conversation.md): Set the conversation status to archived or open. Requires scope `social:write`. - [List messages in a conversation](https://docs.smartlyq.com/api-reference/direct-messages/list-messages-in-a-conversation.md) - [Send a direct message](https://docs.smartlyq.com/api-reference/direct-messages/send-a-direct-message.md): Supports structured payloads: buttons (Facebook) and quick_replies (Facebook + Instagram). - [Mark a conversation read](https://docs.smartlyq.com/api-reference/direct-messages/mark-a-conversation-read.md) - [Typing indicator](https://docs.smartlyq.com/api-reference/social/typing-indicator.md): Shows the typing indicator to the other side of a Facebook or Instagram conversation (Meta sender_action). Other platforms return 422. Requires scope `social:write`. - [React to a message](https://docs.smartlyq.com/api-reference/direct-messages/react-to-a-message.md): React to a message as the connected account. Sending a different emoji replaces the previous reaction. - [Remove a message reaction](https://docs.smartlyq.com/api-reference/direct-messages/remove-a-message-reaction.md): Clear the reaction this account previously sent on a message. - [Send AI Captain message](https://docs.smartlyq.com/api-reference/ai-captain/send-ai-captain-message.md) - [List AI Captain conversations](https://docs.smartlyq.com/api-reference/ai-captain/list-ai-captain-conversations.md) - [Get AI Captain conversation](https://docs.smartlyq.com/api-reference/ai-captain/get-ai-captain-conversation.md) - [Create chatbot](https://docs.smartlyq.com/api-reference/chatbot/create-chatbot.md) - [List chatbots](https://docs.smartlyq.com/api-reference/chatbot/list-chatbots.md) - [Get chatbot](https://docs.smartlyq.com/api-reference/chatbot/get-chatbot.md) - [Update chatbot](https://docs.smartlyq.com/api-reference/chatbot/update-chatbot.md) - [Delete chatbot](https://docs.smartlyq.com/api-reference/chatbot/delete-chatbot.md) - [Start chatbot training](https://docs.smartlyq.com/api-reference/chatbot/start-chatbot-training.md): 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. - [Get chatbot training status](https://docs.smartlyq.com/api-reference/chatbot/get-chatbot-training-status.md) - [Send chatbot message](https://docs.smartlyq.com/api-reference/chatbot/send-chatbot-message.md) - [List chatbot conversations](https://docs.smartlyq.com/api-reference/chatbot/list-chatbot-conversations.md) - [Get conversation messages](https://docs.smartlyq.com/api-reference/chatbot/get-conversation-messages.md) - [Changelog](https://docs.smartlyq.com/changelog.md): New endpoints, improvements, and fixes to the SmartlyQ API ## OpenAPI Specs - [openapi](https://docs.smartlyq.com/openapi.json)