The /api/v1/social routes let agents list accounts, create and revise drafts, manage media, and read rejection feedback. All routes require social:write. There is no API route to approve, reject, or publish — those are dashboard-only.
What this API is for
Use the social API when an automation or AI agent should:
List connected accounts and use their IDs as post targets
Create social post drafts with captions, per-platform overrides, media, and a proposed schedule
Revise drafts after human rejection — reading the event timeline for feedback
Generate or register media in the org's social library — including multi-aspect AI generation (up to four ratios per call)
Browse org media storage — discover dashboard uploads and register a public URL into the social library
Typical workflow: agent drafts → human approves in Dashboard → Social → dispatcher publishes through Chirio.Platform guide: Social agents and API.
Authentication
Every request requires a bearer token with the social:write scope:
Authorization: Bearer av_live_…
Create tokens in Organization → API tokens. Granting social:write requires the Audience manage capability. See Authentication.There is no scope that grants approve, reject, or publish — those actions exist only in session-authenticated dashboard routes.
Base URL
https://help.aveiro.app/api/v1/social
Replace the host with your own app URL when self-hosting.
Endpoints
Guide
Method
Route
List accounts
GET
/api/v1/social/accounts
List posts
GET
/api/v1/social/posts
Create draft
POST
/api/v1/social/posts
Get post
GET
/api/v1/social/posts/{postId}
Update draft
PATCH
/api/v1/social/posts/{postId}
List media
GET
/api/v1/social/media
Browse org media
GET
/api/v1/social/org-media
Register media
POST
/api/v1/social/media
Generate media
POST
/api/v1/social/media/generate
Plan entitlements
Some platforms have plan gates in addition to publishing credits:
X — POST and PATCH with targets that include platform: "x" return 402 PLAN_LIMIT on the free plan. Connect X in Dashboard → Social requires a paid plan too.
Instagram, Threads, LinkedIn — available on every plan that has social publishing enabled; only the credit balance limits volume.
A credit shortfall and a missing entitlement fail for different reasons — top-ups fix the former, upgrading fixes the latter.
Post statuses
Agents can create drafts in draft or pending_approval status. They can edit only draft, pending_approval, or rejected posts. Approved, scheduled, publishing, published, and failed posts return 409 CONFLICT on PATCH.
Filter GET /api/v1/social/posts?status=rejected or status=pending_approval to find posts awaiting human action or agent revision.
Event timeline
Each post includes an events array — comments, approvals, rejections, and ai_revision notes. Agents should read this before revising a rejected draft.
MCP tools
The Aveiro MCP server exposes matching tools (aveiro_social_*) that call these routes. OAuth MCP connections can include social:write when social drafting is authorized.
