# Developer Docs

- [Introduction](https://apidoc.client.fo/index.md): Connect your own systems to your social media and messaging workspace.
- [Quickstart](https://apidoc.client.fo/quickstart.md): Create a key and make your first request.
- [Authentication](https://apidoc.client.fo/authentication.md): Workspace API keys, how to send them and what they can do.
- [Errors and limits](https://apidoc.client.fo/errors-and-limits.md): Status codes, error bodies and rate limits.
- [Webhooks overview](https://apidoc.client.fo/webhooks/overview.md): Receive an HTTPS request whenever something happens in your workspace.
- [Verify signatures](https://apidoc.client.fo/webhooks/verify-signatures.md): Check that a webhook really came from the platform and was not replayed.
- [Events](https://apidoc.client.fo/webhooks/events.md): Every event you can subscribe to, and what its data contains.
- [Managing endpoints](https://apidoc.client.fo/webhooks/manage.md): Create, update, test and inspect webhook endpoints through the API.
- [Zapier](https://apidoc.client.fo/zapier.md): Trigger Zaps from messaging events without writing code.
- [Get the authenticated workspace](https://apidoc.client.fo/messaging/account/get-the-authenticated-workspace.md): Returns the workspace (account) the API key belongs to. Use it as a connectivity / auth check.
- [List automations](https://apidoc.client.fo/messaging/automations/list-automations.md): Paginated list of flows and quick automations. `live` tells you whether an automation actually answers right now — a flow switched on but never published shows status active while every inbound skips it.
- [Get an automation](https://apidoc.client.fo/messaging/automations/get-an-automation.md): Returns a single automation.
- [Activate an automation](https://apidoc.client.fo/messaging/automations/activate-an-automation.md): Switches it on. Refused (422) if the plan's per-channel active-bot cap is reached, if a flow has no published version, or if the published flow uses a step the plan does not include.
- [Pause an automation](https://apidoc.client.fo/messaging/automations/pause-an-automation.md): Switches it off. Conversations mid-flow are unaffected until they finish.
- [List broadcasts](https://apidoc.client.fo/messaging/broadcasts/list-broadcasts.md): Paginated list of campaigns with their aggregate delivery counters.
- [Create a broadcast](https://apidoc.client.fo/messaging/broadcasts/create-a-broadcast.md): Creates a campaign. Draft unless `schedule` is true. `timezone_mode: contact` sends the same wall-clock in each recipient's own timezone and requires `scheduled_local_at`. Set `type: retarget` with `source_broadcast_id` + `retarget_engagement` to re-message a prior broadcast's recipients instead of…
- [Get a broadcast](https://apidoc.client.fo/messaging/broadcasts/get-a-broadcast.md): Returns a single broadcast with its channel and delivery counters.
- [Update a broadcast](https://apidoc.client.fo/messaging/broadcasts/update-a-broadcast.md): Partial update, allowed only while draft or scheduled — an in-flight or finished broadcast is a historical record. Re-enabling `requires_approval` voids any prior sign-off.
- [Delete a broadcast](https://apidoc.client.fo/messaging/broadcasts/delete-a-broadcast.md): Deletes the campaign.
- [Approve a held broadcast](https://apidoc.client.fo/messaging/broadcasts/approve-a-held-broadcast.md): Clears the approval gate, records the approver, and schedules the broadcast.
- [Send a broadcast now](https://apidoc.client.fo/messaging/broadcasts/send-a-broadcast-now.md): Schedules the broadcast for immediate send; the dispatch sweep claims it. Refused for anything not draft or scheduled (so an audience cannot be messaged twice) and for a broadcast still held for approval.
- [List a broadcast's recipients](https://apidoc.client.fo/messaging/broadcasts/list-a-broadcasts-recipients.md): The per-contact delivery rows, with status, provider message id and any error.
- [List channels](https://apidoc.client.fo/messaging/channels/list-channels.md): Paginated list of connected messaging channels. `name` is the live profile name, not the connect-time snapshot.
- [Get a channel](https://apidoc.client.fo/messaging/channels/get-a-channel.md): Returns a single channel by id.
- [List contacts](https://apidoc.client.fo/messaging/contacts/list-contacts.md): Paginated, filterable list of contacts with their tags and pipeline stage.
- [Create a contact](https://apidoc.client.fo/messaging/contacts/create-a-contact.md): Creates a contact and fires contact.created. To make it reachable on WhatsApp, supply `channel` (one of the workspace's WhatsApp numbers), `phone` in international form and `opt_in_attested: true`, confirming the person agreed to receive WhatsApp messages from you; no other channel can be bound here…
- [Bulk action on contacts](https://apidoc.client.fo/messaging/contacts/bulk-action-on-contacts.md): Applies one action to up to 500 contacts: up to 50 inline, more queued (202, `queued: true`). Actions: delete, add_tag, remove_tag, set_stage. `value` is the tag NAME for add_tag/remove_tag and the stage id for set_stage. Per-contact webhooks still fire; contact-event automation triggers are suppres…
- [Get a contact](https://apidoc.client.fo/messaging/contacts/get-a-contact.md): Returns a single contact with its tags and stage.
- [Update a contact](https://apidoc.client.fo/messaging/contacts/update-a-contact.md): Partial update — omitted fields keep their stored value. Any tags supplied are ADDED, never synced. Fires contact.updated.
- [Delete a contact](https://apidoc.client.fo/messaging/contacts/delete-a-contact.md): Deletes the contact and cascades its channel identities, messages, notes and tag links.
- [Add tags to a contact](https://apidoc.client.fo/messaging/contacts/add-tags-to-a-contact.md): Attaches tags by name, creating any that do not exist. Fires contact.tagged and the tag_applied automation trigger.
- [Remove tags from a contact](https://apidoc.client.fo/messaging/contacts/remove-tags-from-a-contact.md): Detaches tags by name. Names that do not exist are ignored — no tag is created just to detach it.
- [Add an internal note](https://apidoc.client.fo/messaging/contacts/add-an-internal-note.md): Records an internal note on the contact. Never sent to the customer.
- [Move a contact's pipeline stage](https://apidoc.client.fo/messaging/contacts/move-a-contacts-pipeline-stage.md): Sets (or clears, with null) the contact's stage and fires contact.stage_changed with the previous stage.
- [List conversations](https://apidoc.client.fo/messaging/conversations-&-messages/list-conversations.md): The unified inbox, newest activity first. A conversation IS a contact, so the id here is the contact id and can be passed straight back as `contact_id` when sending. Archived threads are excluded unless asked for.
- [Get a conversation](https://apidoc.client.fo/messaging/conversations-&-messages/get-a-conversation.md): Returns one conversation with its rollup fields and current assignee.
- [List a conversation's messages](https://apidoc.client.fo/messaging/conversations-&-messages/list-a-conversations-messages.md): The thread, oldest first, paginated — so a client appends pages instead of reversing them.
- [Mark a conversation read](https://apidoc.client.fo/messaging/conversations-&-messages/mark-a-conversation-read.md): Clears the unread counter.
- [Open or close a conversation](https://apidoc.client.fo/messaging/conversations-&-messages/open-or-close-a-conversation.md): Closing stamps the reopen window and settles any automation a human takeover parked. `parked_action` (resume | skip | keep | end) overrides the workspace resume policy for this close.
- [Assign a conversation](https://apidoc.client.fo/messaging/conversations-&-messages/assign-a-conversation.md): Assigns the conversation to a workspace member, or hands it back with a null user_id. Emits conversation.assigned and notifies the new owner. Non-members are rejected.
- [Pause or resume the bot](https://apidoc.client.fo/messaging/conversations-&-messages/pause-or-resume-the-bot.md): Pausing freezes any running automation on this conversation; resuming unfreezes it. Idempotent — retrying a request cannot flip the state back.
- [Block or unblock a contact](https://apidoc.client.fo/messaging/conversations-&-messages/block-or-unblock-a-contact.md): Blocking stops outbound messages and pauses the bot so no automation re-engages them.
- [Add an internal note](https://apidoc.client.fo/messaging/conversations-&-messages/add-an-internal-note.md): Records an internal note on the conversation. Never sent to the customer.
- [Send a message](https://apidoc.client.fo/messaging/conversations-&-messages/send-a-message.md): Sends on the channel the customer last used (or the identity or channel uuid in `channel`), records it in the thread and fires the same message.* webhooks a dashboard reply does. Counted as a BOT send: it needs the workspace in good standing, never takes the conversation over, and gets the bot's mes…
- [List media](https://apidoc.client.fo/messaging/media/list-media.md): Paginated list of the workspace media library, newest first.
- [Upload a file](https://apidoc.client.fo/messaging/media/upload-a-file.md): multipart/form-data with a `file` field. Runs the same upload pipeline as the dashboard, so the file gets its thumbnail conversions and the workspace storage path. Allowed mime types and the per-type size cap come from the install's file config.
- [Get a media item](https://apidoc.client.fo/messaging/media/get-a-media-item.md): Returns a single item with a resolved URL.
- [Delete a media item](https://apidoc.client.fo/messaging/media/delete-a-media-item.md): Detaches the item from any post version that referenced it, then deletes the files and the record.
- [List segments](https://apidoc.client.fo/messaging/segments/list-segments.md): Paginated list of saved contact filters. Counts are opt-in — evaluating a grouped-conditions segment is a real query, so it is not run once per row unless asked for.
- [Create a segment](https://apidoc.client.fo/messaging/segments/create-a-segment.md): Creates a saved filter. Tags are referenced by tag id. `conditions` is an optional grouped rule tree; unknown fields and operators are stripped by the shared sanitiser, so an invalid rule is dropped rather than silently matching everything.
- [Get a segment](https://apidoc.client.fo/messaging/segments/get-a-segment.md): Returns a single segment plus its live contact count.
- [Update a segment](https://apidoc.client.fo/messaging/segments/update-a-segment.md): Partial update — an omitted key keeps its stored value, so changing the name cannot erase the conditions.
- [Delete a segment](https://apidoc.client.fo/messaging/segments/delete-a-segment.md): Deletes the saved filter. Contacts are unaffected.
- [List a segment's contacts](https://apidoc.client.fo/messaging/segments/list-a-segments-contacts.md): Evaluates the segment live and returns the matching contacts, paginated. A segment stores a query, never a membership list, so results reflect the data at request time.
- [List tags](https://apidoc.client.fo/messaging/tags/list-tags.md): Paginated list of contact tags with contact counts.
- [Create a tag](https://apidoc.client.fo/messaging/tags/create-a-tag.md): Creates a tag, or returns the existing one with the same name (200 instead of 201).
- [Get a tag](https://apidoc.client.fo/messaging/tags/get-a-tag.md): Returns a single tag by id.
- [Update a tag](https://apidoc.client.fo/messaging/tags/update-a-tag.md): Renames or recolours a tag.
- [Delete a tag](https://apidoc.client.fo/messaging/tags/delete-a-tag.md): Deletes a tag and detaches it from every contact. The built-in Unsubscribe tag is refused — it is the opt-out marker the broadcast pipeline filters on.
- [Check your key](https://apidoc.client.fo/publishing/diagnostics/check-your-key.md): Returns `{"status":"ok"}` when the key is valid.
- [List accounts](https://apidoc.client.fo/publishing/accounts/list-accounts.md): Every connected social account in the workspace.
- [Get an account](https://apidoc.client.fo/publishing/accounts/get-an-account.md): **Required permission:** `publishing:accounts:read`
- [List posts](https://apidoc.client.fo/publishing/posts/list-posts.md): 20 posts per page.
- [Create a post](https://apidoc.client.fo/publishing/posts/create-a-post.md): Creates a draft, or schedules it if you set `schedule`, `schedule_now` or `queue` (which also needs at least one account). Each line of `body` becomes a paragraph.
- [Delete several posts](https://apidoc.client.fo/publishing/posts/delete-several-posts.md): **Required permission:** `publishing:posts:write`
- [Get a post](https://apidoc.client.fo/publishing/posts/get-a-post.md): **Required permission:** `publishing:posts:read`
- [Update a post](https://apidoc.client.fo/publishing/posts/update-a-post.md): Replaces the post's accounts, tags, date, time and versions. `date` and `time` use the workspace's timezone. To schedule, call [Schedule a post](/publishing/posts/schedule-a-post) afterwards. A non-draft post with no accounts or no date and time goes back to draft.
- [Delete a post](https://apidoc.client.fo/publishing/posts/delete-a-post.md): **Required permission:** `publishing:posts:write`
- [Schedule a post](https://apidoc.client.fo/publishing/posts/schedule-a-post.md): Schedules the post for its saved date and time, or publishes it now with `postNow: true`. The post may need approval first.
- [Reschedule a post](https://apidoc.client.fo/publishing/posts/reschedule-a-post.md): **Required permission:** `publishing:posts:publish`
- [Add a post to the queue](https://apidoc.client.fo/publishing/posts/add-a-post-to-the-queue.md): Schedules the post into the next free slot of the posting schedule.
- [Approve a post](https://apidoc.client.fo/publishing/posts/approve-a-post.md): The key's admin must be allowed to approve posts.
- [List media](https://apidoc.client.fo/publishing/media/list-media.md): **Required permission:** `publishing:media:read`
- [Upload a file](https://apidoc.client.fo/publishing/media/upload-a-file.md): Uploads an image, GIF or video in one request. For large files use the chunked upload.
- [Delete media](https://apidoc.client.fo/publishing/media/delete-media.md): **Required permission:** `publishing:media:write`
- [Get a media item](https://apidoc.client.fo/publishing/media/get-a-media-item.md): **Required permission:** `publishing:media:read`
- [Update a media item](https://apidoc.client.fo/publishing/media/update-a-media-item.md): **Required permission:** `publishing:media:write`
- [Start a chunked upload](https://apidoc.client.fo/publishing/media/start-a-chunked-upload.md): Step 1 of 3. Returns the chunk size and how many chunks to send.
- [Upload a chunk](https://apidoc.client.fo/publishing/media/upload-a-chunk.md): Step 2 of 3. Send each chunk, numbered from 0.
- [Finish a chunked upload](https://apidoc.client.fo/publishing/media/finish-a-chunked-upload.md): Step 3 of 3. Returns the new media item.
- [Cancel a chunked upload](https://apidoc.client.fo/publishing/media/cancel-a-chunked-upload.md): **Required permission:** `publishing:media:write`
- [Import from a URL](https://apidoc.client.fo/publishing/media/import-from-a-url.md): Small files (under 10 MB) are imported straight away and return `status: "completed"` with the `media`. Larger files return a `download_id` with `status: "pending"`; poll [Check a URL import](/publishing/media/check-a-url-import).
- [Check a URL import](https://apidoc.client.fo/publishing/media/check-a-url-import.md): **Required permission:** `publishing:media:read`
- [List tags](https://apidoc.client.fo/publishing/tags/list-tags.md): **Required permission:** `publishing:tags:read`
- [Create a tag](https://apidoc.client.fo/publishing/tags/create-a-tag.md): **Required permission:** `publishing:tags:write`
- [Get a tag](https://apidoc.client.fo/publishing/tags/get-a-tag.md): **Required permission:** `publishing:tags:read`
- [Update a tag](https://apidoc.client.fo/publishing/tags/update-a-tag.md): **Required permission:** `publishing:tags:write`
- [Delete a tag](https://apidoc.client.fo/publishing/tags/delete-a-tag.md): **Required permission:** `publishing:tags:write`
- [Link in Bio API overview](https://apidoc.client.fo/biolinks/overview.md): How pages, short links and domains work through the API, and the rules every write follows.
- [List pages](https://apidoc.client.fo/biolinks/pages/list-pages.md): **Required permission:** `biolinks:pages:read`
- [Create a page](https://apidoc.client.fo/biolinks/pages/create-a-page.md): New pages are created **paused**, with the same starter blocks as the dashboard. Activate with Set page status.
- [Get a page](https://apidoc.client.fo/biolinks/pages/get-a-page.md): The `ETag` header carries the revision.
- [Delete a page](https://apidoc.client.fo/biolinks/pages/delete-a-page.md): **Required permission:** `biolinks:pages:delete`
- [Update a page](https://apidoc.client.fo/biolinks/pages/update-a-page.md): Fields you leave out keep their values. `status` and `blocks` are refused here: use Set page status and the block endpoints.
- [Set page status](https://apidoc.client.fo/biolinks/pages/set-page-status.md): **Required permission:** `biolinks:pages:publish`
- [Duplicate a page](https://apidoc.client.fo/biolinks/pages/duplicate-a-page.md): Creates a **paused** copy with new block IDs and reset counters.
- [Change a page theme](https://apidoc.client.fo/biolinks/pages/change-a-page-theme.md): **Required permission:** `biolinks:pages:write`
- [List blocks](https://apidoc.client.fo/biolinks/blocks/list-blocks.md): **Required permission:** `biolinks:pages:read`
- [Add a block](https://apidoc.client.fo/biolinks/blocks/add-a-block.md): Adds a block at the end of the page. A page can have up to 200 blocks. Commerce and embed blocks cannot be created through the API.
- [Reorder blocks](https://apidoc.client.fo/biolinks/blocks/reorder-blocks.md): Send every block ID of the page exactly once, in the new order.
- [Get a block](https://apidoc.client.fo/biolinks/blocks/get-a-block.md): **Required permission:** `biolinks:pages:read`
- [Delete a block](https://apidoc.client.fo/biolinks/blocks/delete-a-block.md): The `ETag` header carries the page's new revision.
- [Update a block](https://apidoc.client.fo/biolinks/blocks/update-a-block.md): Merges the top-level `content` fields you send. A list you send replaces that whole list. `type` cannot change.
- [List short links](https://apidoc.client.fo/biolinks/short-links/list-short-links.md): **Required permission:** `biolinks:links:read`
- [Create a short link](https://apidoc.client.fo/biolinks/short-links/create-a-short-link.md): New links are created **paused**.
- [Get a short link](https://apidoc.client.fo/biolinks/short-links/get-a-short-link.md): **Required permission:** `biolinks:links:read`
- [Delete a short link](https://apidoc.client.fo/biolinks/short-links/delete-a-short-link.md): **Required permission:** `biolinks:links:delete`
- [Update a short link](https://apidoc.client.fo/biolinks/short-links/update-a-short-link.md): Fields you leave out keep their values.
- [Set short link status](https://apidoc.client.fo/biolinks/short-links/set-short-link-status.md): **Required permission:** `biolinks:links:publish`
- [Get the catalogue](https://apidoc.client.fo/biolinks/catalogue/get-the-catalogue.md): Themes, fonts, block types with their defaults, and `read_schema` / `write_schema` for each block type, plus which ones are `writable` on your workspace.
- [Get page analytics](https://apidoc.client.fo/biolinks/analytics/get-page-analytics.md): Lifetime totals, a 7-day trend (today and the 6 days before) and 30-day breakdowns, with timezone and as-of time.
- [Get short link analytics](https://apidoc.client.fo/biolinks/analytics/get-short-link-analytics.md): Same shape as page analytics. Links record clicks, not views.
- [List form submissions](https://apidoc.client.fo/biolinks/submissions/list-form-submissions.md): Newest first, with cursor pagination: pass `next_cursor` back as `cursor`.
- [Get a submission](https://apidoc.client.fo/biolinks/submissions/get-a-submission.md): **Required permission:** `biolinks:submissions:read`
- [Delete a submission](https://apidoc.client.fo/biolinks/submissions/delete-a-submission.md): **Required permission:** `biolinks:submissions:delete`
- [List QR codes](https://apidoc.client.fo/biolinks/qr-codes/list-qr-codes.md): **Required permission:** `biolinks:qr:read`
- [Create a QR code](https://apidoc.client.fo/biolinks/qr-codes/create-a-qr-code.md): Stores the QR code. Render it from Get a QR code matrix; no image file is generated.
- [Get a QR code](https://apidoc.client.fo/biolinks/qr-codes/get-a-qr-code.md): **Required permission:** `biolinks:qr:read`
- [Delete a QR code](https://apidoc.client.fo/biolinks/qr-codes/delete-a-qr-code.md): **Required permission:** `biolinks:qr:write`
- [Get a QR code matrix](https://apidoc.client.fo/biolinks/qr-codes/get-a-qr-code-matrix.md): The grid of modules (rows of on/off cells) to draw the code yourself.
- [List pixels](https://apidoc.client.fo/biolinks/pixels/list-pixels.md): **Required permission:** `biolinks:pixels:read`
- [Create a pixel](https://apidoc.client.fo/biolinks/pixels/create-a-pixel.md): **Required permission:** `biolinks:pixels:write`
- [Delete a pixel](https://apidoc.client.fo/biolinks/pixels/delete-a-pixel.md): If active pages or links use the pixel, the matching publish permission is also needed.
- [List usable domains](https://apidoc.client.fo/biolinks/domains/list-usable-domains.md): Domains you can assign to a page or link.
- [List domains](https://apidoc.client.fo/biolinks/domains/list-domains.md): **Required permission:** `biolinks:domains:read`
- [Connect a domain](https://apidoc.client.fo/biolinks/domains/connect-a-domain.md): Adds the domain as `pending`. Point its DNS at the platform, then call Verify a domain. Plan limits apply.
- [Get a domain](https://apidoc.client.fo/biolinks/domains/get-a-domain.md): **Required permission:** `biolinks:domains:read`
- [Remove a domain](https://apidoc.client.fo/biolinks/domains/remove-a-domain.md): Queued: returns `202` with an operation to poll. Domains still used by pages or links cannot be removed.
- [Verify a domain](https://apidoc.client.fo/biolinks/domains/verify-a-domain.md): Queued: returns `202` with an operation to poll. Verification does not mean SSL is ready; check `ssl_active` on the domain.
- [Get a domain operation](https://apidoc.client.fo/biolinks/domains/get-a-domain-operation.md): Poll this until `status` is final.

## OpenAPI Specs

- [biolinks.openapi](/api-reference/biolinks.openapi.json)
- [messaging.openapi](/api-reference/messaging.openapi.json)
- [publishing.openapi](/api-reference/publishing.openapi.json)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.