Channels

A channel is an account staqly publishes to: an X account, or your own automation when staqly should hand the post to a script or n8n workflow instead. The other platforms (LinkedIn, Mastodon, Telegram and more) are in the catalog as Soon. Connect a channel once; from then on every post can target it, and a collection's schedules can publish to it.

Connect a channelCopy Anchor Link

From a terminal or a script, your own automation (and, once one is available, a token platform with its fields) connects with one request; OAuth platforms such as X only through the browser:

API=http://localhost:3333

# what each platform needs
curl -s -H "Authorization: Bearer $STAQLY_API_KEY" $API/v1/providers | jq '.data[] | {id, auth, status, credential_fields}'

# your own automation: staqly announces each post to your agents and webhooks
curl -s -H "Authorization: Bearer $STAQLY_API_KEY" -X POST $API/v1/channels -H 'Content-Type: application/json' \
  -d '{"provider":"custom","name":"My n8n publisher"}'

# your own automation that staqly calls itself (see Your own automation)
curl -s -H "Authorization: Bearer $STAQLY_API_KEY" -X POST $API/v1/channels -H 'Content-Type: application/json' \
  -d '{"provider":"custom","name":"My endpoint","fields":{"url":"https://n8n.example.com/webhook/staqly"}}'

Creating, changing and removing channels needs the channels:manage scope in cloud mode; listing them needs channels:read. Credentials are never returned by any call.

The catalogCopy Anchor Link

GET /v1/providers (MCP list_providers, CLI staqly channels providers) lists every provider with its auth, status, limits, credential_fields and settings_fields. In this release Your own automation and X are available (X once the server has its app keys); every other platform is in the catalog as soon, so the dashboard already shows the whole grid and a post's preview can check the platform's limits.

Platforms on a serverCopy Anchor Link

Every platform has a switch in the server's environment (.env), locally and in the cloud:

PROVIDER_X_ENABLED=true            # false: turned off on this server
PROVIDER_X_CLIENT_ID=...           # OAuth platforms: the developer app
PROVIDER_X_CLIENT_SECRET=...

• PROVIDER_<ID>_ENABLED=false hides the platform from the catalog and the dashboard and refuses connecting it and new posts on its channels (409 provider_disabled). Posts already scheduled on its channels still publish, and can still be edited.
• Enabled but without _CLIENT_ID and _CLIENT_SECRET, an OAuth platform is listed as soon.
• Restart the server after changing them. .env.example has a block for every platform.

All limits in one place: Limits.

"Media" means images and videos unless noted. The limits are the platforms' published ones and drive the composer's counters and GET /v1/posts/{id}/preview. Each platform gets its own page here when it becomes available, with what to register and which settings it takes.

Channel status and healthCopy Anchor Link

Test connection (POST /v1/channels/{id}/test, MCP test_channel, CLI staqly channels test) checks the stored credentials against the platform now; a failing test marks the channel Needs reconnect, a passing one clears it. It is rate-limited (burst 5, then 10 per minute). OAuth sign-ins are refreshed by a refresh_channel job before they expire. The channel.needs_reconnect event is one of the three an alert sends by default.

Managing channelsCopy Anchor Link

The Channels page lists every channel with its picture, name, handle, platform, status and activity (last post, next post, posts in the last 30 days). Each row's menu has Settings, Test connection, Edit connection (platforms connected with fields, such as your own automation), Move to group (once there is more than one group), Disable or Enable, Reconnect (when it needs one) and Remove. Settings renames the channel, picks its group and sets Links in posts, what the channel does with the links in a post's text when it publishes:

Platforms that charge more for links or show posts with them to fewer people offer only the last two: X removes them unless you choose plain text. The post keeps its text; the character limit counts what the channel receives, the composer says in red which channels change which links, and GET /v1/posts/{id}/preview lists them per target (links_found, plus a warning). Over the API it is the channel's settings.links (the channel's links field shows the mode in use; the catalog's limits.links and limits.link_modes give each platform's default and choices).

Channel groupsCopy Anchor Link

Every channel belongs to exactly one group, for example one group per client. A workspace always has a Default group, which can't be deleted; new channels land there unless you pick another. With more than one group, the Channels page lists the channels group by group (each one folds open and closed), the composer's channel picker shows them under their group's name, and a group filter keeps one group. New group creates one, a group's menu renames it, and deleting a group moves its channels to Default.

Over the API: GET /v1/channel-groups lists the groups (Default first) with how many channels each holds; POST /v1/channel-groups creates one (name, unique in the workspace; optional color #rrggbb and position), PATCH /v1/channel-groups/{id} renames it, and DELETE /v1/channel-groups/{id} deletes it (409 default_group for Default). A channel's group_id says where it is; POST /v1/channels takes a group_id, PATCH /v1/channels/{id} with group_id moves it, and GET /v1/channels?group=grp_... keeps one group.

GET /v1/channels and GET /v1/channels/{id} also return each channel's activity, read from its targets: last_published_at and last_post_id (the last post that went out on it), next_publish_at (its next scheduled post) and published_30d. Webhook payloads carry the channel without it.

Removing a channel removes the targets on it from every post; posts with no other target become drafts.

GET/v1/channels · POST/v1/channels · GET/v1/channels/{id} · PATCH/v1/channels/{id} · DELETE/v1/channels/{id} · POST/v1/channels/{id}/test ·

Plan limits (cloud): 5 channels on Starter, 15 on Plus, 40 on Pro, unlimited on Business. Over the limit, connecting a channel answers 402 plan_limit_exceeded with details.limit = "channels". See Plans.

SecurityCopy Anchor Link

• Credentials and developer app secrets are sealed with AES-256-GCM. The key is generated into DATA_DIR/secret.key on first use, or comes from STAQLY_SECRET_KEY (32 bytes, base64). Back it up with the database: without it every channel has to be reconnected.
• No response ever carries a credential or a client secret, not even to an admin.
• The OAuth state is signed and bound to the browser that started the flow with a short-lived cookie, so a callback cannot be replayed into another session.
• Publishing calls the platform from the server; your browser never holds a platform token.

Next stepsCopy Anchor Link