YARRAPOST GUIDES · UPDATED 14 SEPTEMBER 2026

Connect agents through API and MCP

Agents are named workspace users in YarraPost. The HTTP API and MCP tools use the same operations, permissions and approval rules as the human workspace. YarraPost does not provide AI writing assistance; you choose and authorize the agent that prepares your content.

Choose an integration path

HTTP clients call https://yarrapost.com/api/v1/operations/{operation} using POST with a JSON body and bearer authorization. The OpenAPI reference describes the current operations and schemas.

MCP clients connect to https://yarrapost.com/mcp using Streamable HTTP. Clients that support OAuth discovery with hosted client metadata or dynamic registration open YarraPost for sign-in and a permission review. A workspace administrator chooses the access to grant; the client receives its own named agent identity. Revoke it in People & agents at any time.

Clients can also use a manually issued Authorization: Bearer … credential. OAuth uses PKCE, short-lived access tokens and rotating refresh tokens. Hosted metadata supports public clients using PKCE; confidential clients can use dynamic registration. Social-channel consent is a separate flow completed by a person.

Give each agent its own permissions

A workspace administrator can issue a named agent credential. Grant only the scopes needed for its role: read, write, publish, approve, connect and admin. For an agent that prepares drafts for human review, start with read and write. Publishing permission does not include approval permission.

Store credentials in a secret manager and send them only to the intended service. Do not embed them in public pages, browser-delivered code or logs.

Discover before creating content

Start with workspace_get, capabilities_list and connections_list. These identify the workspace, available formats and connected destinations. Use connection_instructions if a person needs to authorize a channel. Provider access restrictions still apply to agents.

Check storage before uploading

Use workspace_get or media_list to check remaining file slots and bytes. Reuse a media ID when its file is unchanged. Replacing media on a post keeps the old file as historical evidence and does not free its capacity.

For an upload that has never been attached to a post, call media_delete_check first. Uploads are protected for at least 24 hours. References, incomplete history and unresolved work can keep a file protected beyond that period; a blocked check frees no space.

If the check is eligible and the user explicitly asks to remove that file, call media_delete with its media_id, confirmation: "DELETE UNUSED MEDIA" and an idempotency key. Read and write permissions are required. Retry an uncertain result with the identical input and key. Pending deletion remains charged until cleanup is confirmed. Scheduled, delivered and previously used media cannot be deleted through this tool.

Prepare a draft through the HTTP API

Call post_create with an internal title and variants keyed by connection ID. For example, this is a request body for a text draft; replace the connection placeholder with an ID returned for your workspace:

{
  "title": "September product update",
  "variants": [{
    "connection_id": "<connected-destination-uuid>",
    "text": "Our September product update is ready.",
    "media_ids": []
  }]
}

Send mutations with an Idempotency-Key header of 8–128 characters. Reuse the same key and body for a transport retry of the same operation; use a new key for a new operation. MCP operation mutations use the idempotency_key input field instead.

For media, call media_upload_instructions, upload the binary through authenticated HTTP, and retain the returned media ID for the variant’s media_ids.

Validate, approve and schedule

Check workspace_get.storage or media_list.storage before uploading. Both bytes and file slots count. Reuse an existing media ID when the video is unchanged, including across destinations. Replacing media on a post keeps the previous revision's original; it does not automatically free a slot.

1. Call post_validate. Correct issues with post_edit, using the current version.
2. Call post_request_approval. When approval is required, an identity with the approve scope calls post_approve for the exact revision. Content edits invalidate approval.
3. Call post_schedule with the current version, an explicit-offset ISO timestamp in scheduled_at, and an IANA timezone such as Australia/Melbourne.

Version conflicts mean the post has changed. Fetch it again with post_get and review the current content before deciding what to do next. Do not blindly overwrite another user’s changes.

Track the outcome, not just the request

You can replace a video's media or caption with post_edit before publishing begins. Read the current version first, then validate, approve and schedule the new revision. The old approval and schedule are cleared. Once any destination starts publishing or has an uncertain outcome, preserve the post and use its recovery guidance.

Poll post_get for per-destination delivery status and the available published link. Use events_list for cursor-based event polling. A queued or processing result is not successful publication. An unknown outcome needs inspection before another publish attempt; idempotent API requests alone cannot resolve an uncertain external provider response.

Use the returned progress and recovery guidance to distinguish automatic recovery from manual inspection. Keep the original post and delivery identifiers when reporting failures.

After restoring account access, a publisher can call delivery_retry with the original post_id, delivery_id, current post version and an idempotency_key. It only accepts a failed delivery with one media file whose intact checkpoint proves nothing was published or allocated at the destination, on the current approved revision. Each destination decides from its own checkpoint, and destinations without that proof (such as YouTube) are refused. It preserves the original delivery, checkpoint and approval, and leaves published destinations alone. Text-only deliveries, later-stage failures and unknown outcomes require inspection; do not replace the post to bypass a refused retry.

For the reviewer’s view of the process, read how to approve and schedule social posts.

YouTube playlists and reports

Check channel capabilities before requesting optional consent. Analytics and playlist management are currently an approved pilot; broader Google verification is pending. An eligible channel owner enables the optional feature in Channels and completes Google consent. Ordinary upload permissions remain separate.

Use playlists_list to discover owned playlists and post_analytics for a delivered video's metrics, retention bins and traffic sources. Missing data is not zero; Shorts “stayed to watch” is not available. To add playlists to a scheduled, never-attempted YouTube delivery, call post_youtube_add_to_playlists with its current version. This preserves approval, schedule and media. Delivered playlist changes reuse the existing YouTube video.

Published title, description and category updates remain unavailable while concurrency protection is being validated. A temporary youtube_auth_retry response means follow Retry-After and retry the same input and idempotency key; it does not by itself mean the channel needs reconnecting.

Find posts needing attention with posts_list and delivery_status: "failed" or delivery_status: "unknown". These filters inspect the current revision, including a failed destination on a partially published post. Use youtube_action_status: "failed" or youtube_action_status: "unknown" for playlist actions, then inspect post_get.youtube_actions. Action filters include retained history, so a failure may have a later successful correction. Multiple filters combine with AND; keep the same filters when following pagination cursors. These lists make no YouTube API calls.

Accepted playlist actions retry temporary authorization failures for up to eight attempts, with minimum waits of 1, 2, 4, 8, 15, 15 and 15 minutes. A later provider retry time takes precedence. Uncertain writes are retained for inspection and are never automatically repeated. Check the action receipt separately from the video's publication receipt.

Questions about early access or an integration? Contact support@yarrapost.com.