Tools reference

These are the tools an agent sees once staqly is connected over MCP. You rarely call them by hand (the agent picks them from your request), but this page tells you what each one can do, which inputs it takes, and which scope an API key needs for it in cloud mode.

Example: draft, preview, scheduleCopy Anchor Link

The most common sequence, with the arguments an agent sends:

{ "collection": "Product updates", "content": "v1.4 is out: schedules, channels and a calendar.", "targets": [{ "channel_id": "ch_7h2kq9xw3nbvd5yhzm6a" }, { "channel_id": "ch_q2w8n5k7r3t9y4u6i1o0", "content": "v1.4 is out." }] }

{ "post_id": "post_oalirbz67y4m4cqxq5dw" }

{ "post_id": "post_oalirbz67y4m4cqxq5dw", "publish_at": "2026-11-03T09:00:00Z" }

A full walkthrough: Let an agent fill a collection.

ConventionsCopy Anchor Link

• Scopes only matter in cloud mode (with an API key); in Staqly Community Edition the access token gives every tool.
• Tools marked read-only are annotated as such for clients that care; tools marked destructive delete or invalidate something (data, a key, a secret).
• Collection inputs accept an ID (col_qjuybkx6355nz4no6pqk) or the exact name.
• Tools and REST go through the same authorization checks. Most REST operations have a tool; these have none: the browser flows (sign-in, sign-out, setup, redeeming a device link or a connect link, the OAuth start and callback of a channel), cloud accounts (sign-in methods, members and invitations: people are managed by people), the local access token, recovery key rotation (dashboard session only), developer app registration (PUT /v1/providers/{id}/app), the agent list (/v1/agents), the list of workspace exports (GET /v1/workspace/exports), job details (GET /v1/jobs/{id}, /stats, /cancel), the media editor (/v1/media-projects, /v1/ai, POST /v1/media/{id}/replace) and the billing extras (details, add-ons, X post bundles).
• A suspended workspace (trial or paid period ended unpaid) can call read-only tools plus revoke_session, revoke_api_key, create_device_link, start_workspace_export, start_billing_checkout, open_billing_portal, delete_workspace and purge_post; other tools answer with plan_expired, like REST.

CollectionsCopy Anchor Link

list_collectionsCopy Anchor Link

List collections with post counts per status. Read-only · collections:read

get_collectionCopy Anchor Link

Get a collection by ID or name, with its post counts. Read-only · collections:read

create_collectionCopy Anchor Link

Create a collection (e.g. "Instagram Avatar"): a group of posts with its own publishing schedules. · collections:write

update_collectionCopy Anchor Link

Update a collection: name, description, icon, colour, the wait for your own automation's result (processing_timeout_seconds), or archive/unarchive it (archiving an archived collection, or unarchiving an active one, is a conflict). · collections:write

delete_collectionCopy Anchor Link

Permanently delete a collection with its posts and schedules. confirm must equal the collection name. Destructive · collections:delete (the :write scope alone is not enough)

PostsCopy Anchor Link

list_postsCopy Anchor Link

List posts, optionally by collection, status, channel or tag. Default order is by publish time (unscheduled last); publish_after/publish_before make it the calendar; sort created_desc lists the newest first. Read-only · posts:read

search_postsCopy Anchor Link

Find posts whose content contains a text, with the same filters as list_posts. Read-only · posts:read

get_postCopy Anchor Link

Get one post with its targets (status, link, error per channel). Read-only · posts:read

create_postCopy Anchor Link

Create a post in a collection: content, media (ids from upload_media), targets (one per channel, each with an optional content override and settings: the provider's settings_fields from list_providers, as strings, e.g. X reply_settings, made_with_ai, thread_finisher, reposters as comma-separated channel ids), tags, metadata. status draft (default) or scheduled (needs publish_at, RFC3339 in the future, and a target); publish_now true publishes at once. repeat_every (1d to 6d, 1w, 2w, 1mo) schedules a copy that long after each time the post is published. thread: follow-up parts (content, media, delay_seconds) published as replies under the post on platforms that take replies (X); your own automation receives them with the request. · posts:write

update_postCopy Anchor Link

Edit a draft, scheduled or failed post: content, media, targets (the full list replaces the current one), publish_at (null clears), tags, metadata, collection, repeat_every (an empty string stops repeating; edit the next scheduled copy of a repeating post to stop the chain), thread (replaces the replies; [] clears them). A published post is refused (duplicate it). Pass expected_version to refuse the edit when someone changed it meanwhile. · posts:write

schedule_postCopy Anchor Link

Set when a post goes out (RFC3339, in the future) and make it scheduled; the post needs at least one target. · posts:publish

publish_postCopy Anchor Link

Publish a draft, scheduled or failed post now. · posts:publish

cancel_postCopy Anchor Link

Take a scheduled post off the schedule; it becomes a draft again. · posts:publish

duplicate_postCopy Anchor Link

Copy a post (content, media, tags, metadata, targets) into a new draft. · posts:write

delete_postCopy Anchor Link

Delete a post (its event history is kept). Destructive · posts:delete (the :write scope alone is not enough)

delete_postsCopy Anchor Link

Delete several posts at once (up to 200; their event history is kept). Returns the deleted ids and the ids not found; what already went out stays on the platforms. Destructive · posts:delete

purge_postCopy Anchor Link

Delete a post together with its whole history: every event about it (and their webhook deliveries), its media when no other post uses them. For removing personal data; one content-free post.purged event remains. Destructive · admin

preview_postCopy Anchor Link

How each target will carry the post: the text per channel (with the channel's links mode applied), the links it removes or defangs (links_found, with a warning naming the channel) and what its provider objects to (too long, missing title...). Read-only · posts:read

get_post_metricsCopy Anchor Link

A post's numbers per channel (views, likes, reposts, replies, quotes, bookmarks, link clicks where the platform gives them), read from the platform when older than ten minutes or with refresh true. available false: the platform reports none. Read-only · posts:read

report_post_metricsCopy Anchor Link

Your own automation (provider custom) sends the numbers of a post it published, replacing the stored ones. · posts:publish

create_preview_linkCopy Anchor Link

A link to a read-only preview page of the post (as each channel shows it) where anyone with the link can comment without signing in. The url is returned once; expires_in_days 0 never expires. · posts:write

list_preview_linksCopy Anchor Link

A post's preview links (active, expiry, revoked); the links themselves are not shown again. Read-only · posts:read

revoke_preview_linkCopy Anchor Link

Stop a preview link from working. Destructive · posts:write

list_post_commentsCopy Anchor Link

A post's feedback threads, oldest first: comments reviewers left on its preview pages (name, email) and the team's replies. A thread's first comment has parent_id empty and may mark a passage: quote, the channel's version (channel_id, empty: the shared text), part (0 the post's text, n its n-th comment), where the words are now (anchor_start/anchor_end, -1 when gone: text_changed) and resolved_at once resolved. Read-only · posts:read

reply_to_post_commentCopy Anchor Link

Reply to a feedback thread of a post as the team. · posts:write

resolve_post_commentCopy Anchor Link

Resolve a feedback thread by its first comment (resolved false reopens it). · posts:write

get_post_historyCopy Anchor Link

The events of a post, newest first: created, edited, scheduled, published or failed per channel. Read-only · posts:read

retry_targetCopy Anchor Link

Try a failed target once more, now. · posts:publish

list_tagsCopy Anchor Link

List the workspace's post tags with how many posts carry each, most used first. Read-only · posts:read

No inputs.

Your own automationCopy Anchor Link

list_requested_workCopy Anchor Link

What people's setup asks your automation for: targets on your own automation waiting for report_publish_result (kind target, with the post and the channel) and schedules that found nothing to publish and ask for posts (kind posts; answer by creating draft posts in that collection). Oldest first. Read-only · posts:read

No inputs.

report_publish_resultCopy Anchor Link

Close a target on your own automation (provider custom) that waits for a result: status published with the url (and external_id), or failed with the error. Only for work you did yourself. · posts:publish

ChannelsCopy Anchor Link

list_providersCopy Anchor Link

The platform catalog: every provider staqly can publish to, whether it is available in this build, how it connects (oauth2 in the dashboard, token here with connect_channel, none for your own automation), its limits (characters, media) and the per-post settings it takes. Read-only · channels:read

No inputs.

list_channelsCopy Anchor Link

List connected channels (accounts) with provider, handle, status (connected, needs_reconnect, disabled), group_id (its channel group) and activity (last published post and time, next scheduled post time, posts published in the last 30 days). Read-only · channels:read

get_channelCopy Anchor Link

Get one channel with its group and activity. Credentials are never returned. Read-only · channels:read

connect_channelCopy Anchor Link

Connect your own automation (provider custom, no fields). X (OAuth) is connected in the dashboard. Platforms with status soon in list_providers can't be connected yet. · channels:manage

update_channelCopy Anchor Link

Rename a channel, change its default settings (settings replaces them; settings.links = keep, remove or defang sets what the channel does with links in a post, within its provider's link_modes: X allows only remove and defang), turn it off (status disabled) or on (connected), or reconnect a token channel with fresh fields; group_id moves it to another channel group. · channels:manage

list_channel_groupsCopy Anchor Link

List the workspace's channel groups (every channel is in exactly one; the Default group always exists) with how many channels each holds. Move a channel with update_channel group_id. Read-only · channels:read

No inputs.

create_channel_groupCopy Anchor Link

Create a channel group (name, unique in the workspace; optional color #rrggbb and position). · channels:manage

update_channel_groupCopy Anchor Link

Rename a channel group, or change its color or position. · channels:manage

delete_channel_groupCopy Anchor Link

Delete a channel group; its channels move to the Default group, which can't be deleted. Destructive · channels:manage

delete_channelCopy Anchor Link

Remove a channel; targets on it go with it. Destructive · channels:manage

test_channelCopy Anchor Link

Check a channel's stored credentials against its platform. Rate-limited. · channels:manage

SchedulesCopy Anchor Link

create_channel_linkCopy Anchor Link

A connect link: someone without access to Staqly (a client) opens it and connects a channel to this workspace by signing in at the platform; nothing else is reachable through it. The url is returned once. · channels:manage

list_channel_linksCopy Anchor Link

The workspace's connect links (status open, used, expired or revoked; uses; expiry); the links themselves are not shown again. Read-only · channels:manage

No inputs.

revoke_channel_linkCopy Anchor Link

Stop a connect link from working; channels already connected through it stay. Destructive · channels:manage

list_schedulesCopy Anchor Link

List a collection's (or every) publishing schedules with their next run. Read-only · schedules:manage

create_scheduleCopy Anchor Link

Create a publishing schedule for a collection: kind once (run_at) or recurring (rule: times like ["09:00","17:00"] with optional weekdays 0-6 and tz, or every_minutes), the channels it publishes to, pick (next waiting post, selected post_ids, or all), and what to do when nothing waits (source none, agent = emit schedule.posts_requested, endpoint = POST a signed request to endpoint_url and create the posts it returns; the response carries endpoint_secret in full once, so the endpoint can verify X-Staqly-Signature). · schedules:manage

update_scheduleCopy Anchor Link

Change a schedule (any field of create_schedule, enabled true/false); next_run_at is recomputed. · schedules:manage

delete_scheduleCopy Anchor Link

Delete a schedule. Destructive · schedules:manage

run_scheduleCopy Anchor Link

Run a schedule now (its regular next run is unchanged). · schedules:manage

QueueCopy Anchor Link

list_jobsCopy Anchor Link

The background queue: publish runs, schedule runs and token refreshes with status (queued, running, done, failed, cancelled), attempts and the last error. Newest first; filter by status or kind. Read-only · posts:read

retry_jobCopy Anchor Link

Queue a failed job again, now. · posts:publish

MediaCopy Anchor Link

upload_mediaCopy Anchor Link

Upload a file (base64); returns a media ID to put in a post's media list. · media:write

get_mediaCopy Anchor Link

Get a media file's metadata (type, size, name, SHA-256, URL, alt text, pixels, length); with include_content=true also its base64 content (files up to 4 MiB). Read-only · media:read

list_mediaCopy Anchor Link

The media library: uploaded pictures, videos and audio, newest first, with how many posts use each (uses). Filter by name (q), kind (image, video, audio), used (used or unused), folder (a folder id or root) and tag (deleted=true lists Deleted, duplicates=true identical files); sort created_desc, created_asc, size_desc or name_asc; page with offset and limit (next_offset). Read-only · media:read

update_mediaCopy Anchor Link

Rename a media file, set its alt text (a description for people who can't see it; platforms that take alt text receive it), or set a video's width, height and duration_ms. · media:write

get_media_usageCopy Anchor Link

The posts that use a media file (in their files or a comment), newest first, at most 50, with each post's title, status and publish time. Check it before deleting a file. Read-only · media:read and posts:read

list_media_foldersCopy Anchor Link

The media library's virtual folders (id, parent_id, name, files directly in it), the number of files at the top level and in total, and every file tag with its count. Read-only · media:read

create_media_folderCopy Anchor Link

Create a media library folder at the top level or inside another (parent_id). Names are unique among a folder's subfolders, ignoring case. · media:write

update_media_folderCopy Anchor Link

Rename a media library folder or move it under another folder (parent_id; empty = the top level). A folder can't go inside itself. · media:write

delete_media_folderCopy Anchor Link

Delete a media library folder. Its files and subfolders move up to its parent; no file is deleted. Destructive · media:write

organize_mediaCopy Anchor Link

Move up to 200 media files to a folder (folder_id; empty = the top level) and/or add and remove tags on them. · media:write

delete_mediaCopy Anchor Link

Move a media file to Deleted, where it can be restored for 30 days before it is deleted for good (refused while a scheduled post uses it); with permanent=true delete it for good now, and posts that reference it lose that file. Destructive · posts:delete (the :write scope alone is not enough)

restore_mediaCopy Anchor Link

Take a media file out of Deleted, back where it was. · posts:delete

keep_mediaCopy Anchor Link

Keep this media file of a set of identical ones (list_media with duplicates=true): posts that use a copy use this file instead, and the copies move to Deleted. Destructive · posts:delete and posts:write

Activity logCopy Anchor Link

list_eventsCopy Anchor Link

List the activity log (posts created, scheduled, published or failed, channels connected, schedules run, settings changes), newest first, with optional filters. Read-only · events:read

export_eventsCopy Anchor Link

Export the activity log as NDJSON or CSV text, oldest first; events is the number of events (lines) in this call. Output is capped at 32 KiB per call: when truncated=true, call again with the same filters and after_seq=next_after_seq for the rest (the whole log is the sum of all calls). Read-only · events:read

WebhooksCopy Anchor Link

list_webhooksCopy Anchor Link

List webhooks with their URL, events, filters and state. Read-only · webhooks:manage

No inputs.

get_webhookCopy Anchor Link

Get one webhook. Read-only · webhooks:manage

create_webhookCopy Anchor Link

Create a webhook that receives signed event POSTs. The response contains the signing secret once. · webhooks:manage

update_webhookCopy Anchor Link

Update a webhook's URL, description, events, collection filter, active flag, timeout or retry count. Setting only active to its current value is a conflict. · webhooks:manage

delete_webhookCopy Anchor Link

Delete a webhook and stop its deliveries. Destructive · webhooks:manage

rotate_webhook_secretCopy Anchor Link

Replace a webhook's signing secret; the new secret is returned once and the old one stops working. Destructive · webhooks:manage

test_webhookCopy Anchor Link

Queue a webhook.test delivery to this webhook only. Rate-limited. · webhooks:manage

list_webhook_deliveriesCopy Anchor Link

List webhook delivery attempts (status, response code, error), newest first. Read-only · webhooks:manage

retry_webhook_deliveryCopy Anchor Link

Re-queue a finished (succeeded or failed) webhook delivery. · webhooks:manage

AlertsCopy Anchor Link

list_alertsCopy Anchor Link

List alerts: where staqly tells people what happened (Telegram, Slack, Discord, ntfy, email). Secrets are masked. Read-only · alerts:manage

No inputs.

get_alertCopy Anchor Link

Get one alert. Secrets are masked. Read-only · alerts:manage

create_alertCopy Anchor Link

Create an alert that tells people when posts go out or fail and when a channel needs reconnecting. · alerts:manage

update_alertCopy Anchor Link

Update an alert's name, config, events, collection filter, digest window or enabled flag. Setting only enabled to its current value is a conflict. · alerts:manage

delete_alertCopy Anchor Link

Delete an alert. Destructive · alerts:manage

test_alertCopy Anchor Link

Send a test message through an alert right away. Rate-limited. · alerts:manage

list_alert_deliveriesCopy Anchor Link

List recent messages sent (or failed) through an alert, newest first. Read-only · alerts:manage

API keys and sessionsCopy Anchor Link

list_api_keysCopy Anchor Link

List API keys (prefix, scopes, last use, expiry, revocation) and the available scopes. Read-only · admin

No inputs.

create_api_keyCopy Anchor Link

Create an API key with the given scopes (cloud only: the Community Edition has no API keys, it uses its access token). The raw key is returned once. · admin

revoke_api_keyCopy Anchor Link

Revoke an API key; it stops working immediately. Revoking a revoked key is a conflict. Destructive · admin

rotate_api_keyCopy Anchor Link

Replace an API key with a new one (same name and scopes); the old key stops working and the new raw key is returned once. Destructive · admin

list_sessionsCopy Anchor Link

List signed-in dashboard sessions (browser, created, last seen, expiry). Read-only · admin

No inputs.

revoke_sessionCopy Anchor Link

Sign out a dashboard session. Revoking a revoked session is a conflict. Destructive · admin

Workspace and planCopy Anchor Link

get_workspaceCopy Anchor Link

Get the workspace name, ID, plan and time zone. Read-only · no scope needed

No inputs.

rename_workspaceCopy Anchor Link

Rename the workspace and/or set its time zone (IANA name: post repeats and schedule rules without tz use it). · admin

delete_workspaceCopy Anchor Link

Permanently delete the workspace and everything in it (cloud only). confirm must equal the workspace name. Like REST, this needs a signed-in dashboard session, so API keys get a forbidden error. Destructive · dashboard session only (API keys get forbidden)

start_workspace_exportCopy Anchor Link

Start a ZIP export of the whole workspace (posts, channels, schedules, media, events). Poll get_workspace_export until status is ready. · admin

No inputs.

get_workspace_exportCopy Anchor Link

Get a workspace export's status (pending, running, ready, failed, expired) and, once ready, its download URL. Read-only · admin

list_plansCopy Anchor Link

List the cloud plans with their limits and prices. Read-only · no scope needed

No inputs.

get_usageCopy Anchor Link

Get the workspace's plan, usage this period against its limits, and whether it is suspended. Read-only · no scope needed

No inputs.

get_billingCopy Anchor Link

Get billing status: whether Stripe billing is enabled, the plan, the subscription status and the end of the trial or paid period. Read-only · admin

No inputs.

start_billing_checkoutCopy Anchor Link

Start a Stripe Checkout for a plan billed monthly or yearly and return its URL for a person to open and pay; a workspace that already pays is switched to that plan instead (prorated). Cloud with billing enabled. · admin

open_billing_portalCopy Anchor Link

Return a Stripe customer portal URL (payment method, invoices, cancel). · admin

No inputs.

create_device_linkCopy Anchor Link

Create a one-time link (valid 5 minutes) that signs another browser into the dashboard. Only for Community Edition callers (its access token, or MCP over stdio) and dashboard sessions; API keys get a forbidden error. · the Community Edition or a dashboard session (API keys get forbidden)

No inputs.

Next stepsCopy Anchor Link