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
Film a public URL into a 3D mockup video in the social library
Read engagement performance — first (~1h) and latest snapshots for published posts
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}
Get performance
GET
/api/v1/social/performance
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
List website renders
GET
/api/v1/social/video
Film a website
POST
/api/v1/social/video
Poll website render
GET
/api/v1/social/video/{renderId}
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_*, aveiro_video_*) that call these routes — including aveiro_social_get_performance for cross-post engagement reads and aveiro_video_create_mockup for website mockup videos. OAuth MCP connections can include social:write when social drafting is authorized.
