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 and a custom Authorization: Bearer … header. Clients must support that header. MCP OAuth discovery and dynamic client registration are not currently supported. 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.

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

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

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.

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

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