Tools and errors

This page is for developers. A tool is one action an AI app can take in UniFeeds, such as creating a post. You don't need this page to use UniFeeds: your AI app reads this list on its own. It calls whoami first to learn which workspace it's connected to and whether it can make changes. See How your AI app works.

whoami · Check the UniFeeds connection
list_accounts · List connected accounts
list_posts · List posts
get_post · Get post
create_post · Create post
update_post · Update post
reschedule_post · Reschedule post
retry_failed_targets · Retry failed deliveries
delete_post · Delete post
remove_from_platform · Remove from platform
import_media_from_url · Import media from a URL
list_media · List media
get_overview · Get analytics overview
get_post_analytics · Get post analytics

How tools behave

Each tool works for one workspace. Read tools need social:read. Tools that create, schedule, publish, edit or delete posts, or import media, also need social:write.
Every tool that makes a change takes a requestId (a UUID). If you repeat a call with the same requestId, you get the first result back, so retries are safe.
Times use ISO 8601 with an offset, like 2026-10-01T09:30:00-04:00.
Publishing happens in the background. Call get_post to see the result for each account.
Arguments that don't match a tool's schema come back as an Input validation error text that names each field. Fix those fields and call again.
When a tool fails for another reason, it sets isError and returns a code and a message as JSON text:

Error result

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Post not found"
  }
}

Error codes

Code	What to do
`401 Unauthorized`	The app isn't signed in, or the sign-in or key expired or was removed. Connect again from the app. With an API key, the header must read `Authorization: Bearer ufk_…`; ask a workspace admin for a new key.
`403 insufficient_scope`	A write tool on a read-only sign-in by an admin who can allow changes. The app asks you to sign in again: tick the option to allow changes.
`FORBIDDEN`	The connection can't do this, and the message says why. If only workspace admins can let an AI app make changes, ask a workspace admin. With a read-only API key, ask an admin for a read and write key. Don't retry.
`403` origin not allowed	A browser request from a site UniFeeds doesn't accept. See Troubleshooting.
`429 Too many requests`	More than 120 requests, or 20 connects, in a minute for one sign-in or key. Wait for the `Retry-After` time (one minute), then retry with the same `requestId`.
`503`	UniFeeds can't check your sign-in right now. Try again in a minute.
`PLAN_LIMIT_REACHED`	The plan doesn't allow it, or the workspace already has 25 active keys. Upgrade in Billing, or revoke keys you don't use.
`RATE_LIMITED`	More than 30 calls in a minute that publish, schedule, retry, add media or reach a platform. Wait a minute, then retry with the same `requestId`.
`CONFLICT`	The post's status changed, or a retry could post it twice. Read it with `get_post` and check the platform before you retry.
`INVALID_INPUT`	UniFeeds refused a value, and the message says which. If times are off, tell the app your time zone.
`NOT_FOUND`	That id doesn't exist in this workspace. List the posts or accounts again.
`INTERNAL_ERROR`	Something went wrong on our side. Try again. If it keeps happening, email support@unifeeds.io.

A post that fails on a platform isn't a tool error. Read the reason with get_post, reconnect the account if needed, then retry.

Workspace

whoami

No scope needed

Check the UniFeeds connection

Read-only

Says which UniFeeds workspace this connection uses, whether it can only read or can also make changes, how it connected (sign-in or API key), when it expires, and how to switch workspace. Call it first to confirm the connection. It works on any connection.

No arguments.

Accounts

list_accounts

social:read

List connected accounts

Read-only

Lists the social accounts connected to this UniFeeds workspace: platform, handle, status, whether UniFeeds can publish to it (canPublish) and which analytics features it supports. Call it before create_post to get the account ids to use as targets and to check each account is active. Not for connecting or reconnecting accounts; the user does that in the UniFeeds web app under Connections.

No arguments.

Posts

list_posts

social:read

List posts

Read-only

Lists the workspace's posts, newest first, with each post's status and per-account delivery status. Filter by status and/or a scheduled-time range (from, to). Returns at most limit posts and has no paging, so narrow the time range to reach older posts. Not for one post's failure reasons, permalinks or metrics; use get_post for that.

status?draft | scheduled | publishing | published | failed: Only posts in this status. Leave out for all.
limit?integer: How many posts to return, newest first. Default 50, max 100.
from?string: Only posts scheduled at or after this time. ISO-8601, e.g. 2026-10-01T09:30:00-04:00 or 2026-10-01T13:30:00Z. A plain date (2026-10-01) means midnight UTC.
to?string: Only posts scheduled at or before this time. ISO-8601, e.g. 2026-10-01T09:30:00-04:00 or 2026-10-01T13:30:00Z. A plain date (2026-10-01) means midnight UTC.

get_post

social:read

Get post

Read-only

Returns one post in full: body, media, schedule and timezone, and for each destination account (target) its delivery status, permalink, failure code and message, and latest metrics. Call it after create_post, update_post or retry_failed_targets to check how publishing went, and to find the targetId for remove_from_platform. Not for metric history; use get_post_analytics.

postIdstring: The post id, as returned by another UniFeeds tool.

create_post

social:write

Create post

Needs confirmationTalks to platforms

Creates a post for one or more connected accounts and saves it as a draft (mode draft), schedules it (mode schedule with scheduledFor) or starts publishing it now (mode publish_now). Scheduling and publishing make content public, so confirm the text, accounts, media and time with the user first. Publishing runs in the background: call get_post afterwards for each account's result. Not for changing an existing post; use update_post or reschedule_post.

bodystring: The shared caption or text.
kindtext | image | video | story: text: no media. image: one or more images. video: exactly one video. story: an Instagram or Facebook story with one image or video.
targetsobject[]: Destination accounts (ids from list_accounts). May be empty only for drafts.
mediaIds?string[]: Media ids from import_media_from_url or list_media, in display order.
title?string: Internal title shown in UniFeeds, never published.
timezonestring: IANA time zone the post is planned in, e.g. America/New_York or Europe/Berlin. Ask the user if unsure.
modedraft | schedule | publish_now: draft: save only. schedule: publish at scheduledFor. publish_now: start publishing immediately. Publishing is asynchronous; check get_post for per-account results.
scheduledFor?string: When to publish; required when mode is schedule and must be in the future. ISO-8601, e.g. 2026-10-01T09:30:00-04:00 or 2026-10-01T13:30:00Z. A plain date (2026-10-01) means midnight UTC.
requestIdUUID: A fresh UUID for this operation. If the call fails or times out, retry with the SAME requestId: UniFeeds then returns the first result instead of acting twice. Use a new UUID only for a new operation.

update_post

social:write

Update post

Needs confirmationTalks to platforms

Edits a draft or scheduled post inside UniFeeds. Omitted fields keep their value; targets and mediaIds replace the whole list when given; mode can also schedule or publish it. Posts that are publishing or published cannot be edited, and nothing already on a platform changes. Not for only moving the time; use reschedule_post. To take a live post down, use remove_from_platform.

postIdstring: The post id, as returned by another UniFeeds tool.
body?string: Optional.
kind?text | image | video | story: text: no media. image: one or more images. video: exactly one video. story: an Instagram or Facebook story with one image or video.
targets?object[]: Replaces all destination accounts when given.
mediaIds?string[]: Media ids from import_media_from_url or list_media, in display order.
title?string: Optional.
timezone?string: IANA time zone the post is planned in, e.g. America/New_York or Europe/Berlin. Ask the user if unsure.
mode?draft | schedule | publish_now: draft: save only. schedule: publish at scheduledFor. publish_now: start publishing immediately. Publishing is asynchronous; check get_post for per-account results.
scheduledFor?string: New publish time. ISO-8601, e.g. 2026-10-01T09:30:00-04:00 or 2026-10-01T13:30:00Z. A plain date (2026-10-01) means midnight UTC.
clearSchedule?boolean: Remove the planned time (drafts only).
requestIdUUID: A fresh UUID for this operation. If the call fails or times out, retry with the SAME requestId: UniFeeds then returns the first result instead of acting twice. Use a new UUID only for a new operation.

reschedule_post

social:write

Reschedule post

Makes changesTalks to platforms

Moves a draft or scheduled post to a new publish time and marks it scheduled; destination accounts that already published are left alone. The time must be in the future and should carry the user's UTC offset. Confirm the new time with the user. Not for editing text, media or accounts; use update_post. Not for failed deliveries; use retry_failed_targets.

postIdstring: The post id, as returned by another UniFeeds tool.
scheduledForstring: New publish time, in the future. ISO-8601, e.g. 2026-10-01T09:30:00-04:00 or 2026-10-01T13:30:00Z. A plain date (2026-10-01) means midnight UTC.
requestIdUUID: A fresh UUID for this operation. If the call fails or times out, retry with the SAME requestId: UniFeeds then returns the first result instead of acting twice. Use a new UUID only for a new operation.

retry_failed_targets

social:write

Retry failed deliveries

Needs confirmationTalks to platforms

Re-queues the failed destination accounts of a post for publishing now; call get_post first to read each failure reason and again afterwards for the new result. Refuses with CONFLICT when a failure is publish_unconfirmed, stale_publish or publish_attempts_exceeded, because the platform may already have published it: check the permalink or the platform with the user, and only then pass force: true. Not for drafts or scheduled posts; use update_post.

postIdstring: The post id, as returned by another UniFeeds tool.
force?boolean: Retry even deliveries that may already be live. Only after confirming they are not.
requestIdUUID: A fresh UUID for this operation. If the call fails or times out, retry with the SAME requestId: UniFeeds then returns the first result instead of acting twice. Use a new UUID only for a new operation.

delete_post

social:write

Delete post

Needs confirmation

Deletes a post from UniFeeds, whether draft, scheduled, failed or published. It does not remove anything from the social platforms, so a published post stays live there. Posts with analytics history, or that are publishing right now, cannot be deleted. Confirm with the user first. Not for taking a live post down; use remove_from_platform for each published account.

postIdstring: The post id, as returned by another UniFeeds tool.
requestIdUUID: A fresh UUID for this operation. If the call fails or times out, retry with the SAME requestId: UniFeeds then returns the first result instead of acting twice. Use a new UUID only for a new operation.

remove_from_platform

social:write

Remove from platform

Needs confirmationTalks to platforms

DESTRUCTIVE and irreversible: permanently deletes one published delivery (a targetId from get_post) from its social platform, including its likes, comments and views there. The post stays in UniFeeds, marked as removed. Always confirm the exact post and account with the user first. The result state is done (removed, or it was already gone), failed (nothing was deleted; the message says why) or unknown (the platform's answer was ambiguous). An unknown result is never re-sent: check the post on the platform before trying again with a new requestId. Supported for X, Threads, LinkedIn, YouTube, Bluesky and Instagram; other platforms are refused. Not for deleting the post inside UniFeeds; use delete_post.

targetIdstring: The post target id, as returned by another UniFeeds tool.
requestIdUUID: A fresh UUID for this operation. If the call fails or times out, retry with the SAME requestId: UniFeeds then returns the first result instead of acting twice. Use a new UUID only for a new operation.

Media

import_media_from_url

social:write

Import media from a URL

Makes changesTalks to platforms

Downloads a public https image or video (up to 100 MB) into the workspace's media library and returns its mediaId for create_post or update_post. The URL must point straight at the file, not at a web page that embeds it; private-network, localhost and non-media URLs are rejected. Not for files on the user's computer: MCP cannot upload them, so ask the user to upload in the UniFeeds web app, then use list_media.

urlURL: Public https URL of the image or video file.
filename?string: File name to store, e.g. launch-teaser.mp4.
requestIdUUID: A fresh UUID for this operation. If the call fails or times out, retry with the SAME requestId: UniFeeds then returns the first result instead of acting twice. Use a new UUID only for a new operation.

list_media

social:read

List media

Read-only

Lists the workspace's ready images and videos in the UniFeeds media library, newest first, with kind, file name, size, dimensions and the mediaId to pass as mediaIds in create_post or update_post. Returns at most limit items and has no paging. Not for adding media; use import_media_from_url.

limit?integer: How many media items to return, newest first. Default 50, max 100.

Analytics

get_overview

social:read

Get analytics overview

Read-only

Returns workspace analytics for a period: posts published, engagement, reach and follower changes, in total, per platform and per day, plus top posts. Numbers come from the last metrics sync and can lag a few hours, and the period is clamped to the history the workspace's plan allows (range.clamped says so). After that clamp the period can be at most 92 days; ask for longer spans in several calls. Not for a single post's numbers; use get_post_analytics.

fromstring: Start of the period. ISO-8601, e.g. 2026-10-01T09:30:00-04:00 or 2026-10-01T13:30:00Z. A plain date (2026-10-01) means midnight UTC.
tostring: End of the period (a plain date includes that day). ISO-8601, e.g. 2026-10-01T09:30:00-04:00 or 2026-10-01T13:30:00Z. A plain date (2026-10-01) means midnight UTC.

get_post_analytics

social:read

Get post analytics

Read-onlyTalks to platforms

Returns the latest metrics (likes, comments, shares, views and more) of one post on each account, plus up to 30 recent snapshots. Set refresh to re-read them from the platforms first; that is slower and rate limited, and if it fails the stored numbers come back with refreshError. Not for workspace-wide totals; use get_overview.

postIdstring: The post id, as returned by another UniFeeds tool.
refresh?boolean: Fetch fresh numbers from the platforms before answering.

How tools behaveCopy Anchor Link

Error codesCopy Anchor Link

WorkspaceCopy Anchor Link

AccountsCopy Anchor Link

PostsCopy Anchor Link

MediaCopy Anchor Link

AnalyticsCopy Anchor Link

On this page

How tools behave

Error codes

Workspace

Accounts

Posts

Media

Analytics