Let AI agents draft Instagram, Threads, and LinkedIn posts via /api/v1/social and aveiro_social_* MCP tools. Requires social:write — approval stays in the dashboard.
Grant social:write on an API token or MCP OAuth connection. Agents list accounts, create and revise drafts, generate media, and read rejection feedback. Approve, reject, and publish remain dashboard-only — there is no scope that grants them.
What agents can and cannot do
Action
Agent (API / MCP)
Human (dashboard)
List connected accounts
Yes
Yes
Create and revise drafts
Yes — draft, pending_approval, rejected only
Yes
Generate or register media
Yes
Yes
Read feedback timeline
Yes
Yes
Approve, reject, post now
No — not exposed
Yes
Publish autonomously
No — structural guardrail
No without approval
This split is intentional. Social posts go to public profiles — Aveiro keeps approval in session-authenticated UI actions only.
Token setup
Ensure Social publishing is on (default) or enable it under Organization → Features
Open Organization → API tokens → Create token
Add the social:write scope (requires Audience manage capability)
Copy the av_live_… secret — shown once
For MCP in Cursor or Claude, connect via the hosted MCP server at https://www.aveiro.app/api/mcp/mcp. OAuth grants include social:write when you authorize social drafting tools.Default content tokens (sites:read, content:read, content:write) do not include social access — add social:write explicitly.See API tokens for the full scope list.
REST API
All routes live under /api/v1/social on your platform host. Full reference: Social API overview.
Method
Route
Purpose
GET
/api/v1/social/accounts
Connected Instagram, Threads, and LinkedIn accounts and IDs for targets
GET
/api/v1/social/posts
List posts — filter by status (e.g. rejected, pending_approval)
POST
/api/v1/social/posts
Create a draft (source=mcp); optional submitForReview
GET
/api/v1/social/posts/{postId}
One post with full event timeline
PATCH
/api/v1/social/posts/{postId}
Revise draft, pending, or rejected post
GET
/api/v1/social/media
Social media library (registered and generated assets)
GET
/api/v1/social/org-media
Browse org media storage (dashboard uploads — not yet in the social library)
POST
/api/v1/social/media
Register a public URL into the social library
POST
/api/v1/social/media/generate
AI image generation — up to 4 aspectRatios per call (plan + credits per ratio)
Send Authorization: Bearer av_live_… on every request.
Typical agent loop
GET /api/v1/social/accounts — pick target account IDs
GET /api/v1/social/org-media (optional — use type=video for hosted videos) — find an existing dashboard upload, then POST /api/v1/social/media to register its URL (pass host: true for external videos)
POST /api/v1/social/media/generate or POST /api/v1/social/media — attach media
POST /api/v1/social/posts with targets, content, platformOverrides, firstComment, platformCommentOverrides, proposedScheduleAt, and a note explaining the draft
Human approves in Dashboard → Social
If rejected, GET /api/v1/social/posts/{id} — read events, then PATCH with fixes and submitForReview: true
Caption limits enforced at validation: Instagram 2,200, Threads 500, LinkedIn 3,000. MCP draft tools accept instagram, threads, and linkedin as platform keys — X is not available for new MCP drafts because it cannot be connected.
First comments — set a base firstComment on the post, or per-platform strings in platformCommentOverrides (MCP: platform_comment_overrides). After approval, the dispatcher publishes each platform's resolved comment right after the post goes live — the link-in-comments pattern. Comment limits: Instagram 2,200, Threads 500, LinkedIn 1,250. A comment that fails does not fail the post; check the event timeline for First comment not posted notes. The hosted MCP server and the stdio proxy in mcp/aveiro expose the same draft fields — including per-platform first comments.
Multi-aspect generation and auto crop
POST /api/v1/social/media/generate accepts aspectRatios — an array of up to four supported ratios (1:1, 4:5, 5:4, 3:4, 4:3, 2:3, 3:2, 9:16, 16:9). Default is ["16:9"]. Each ratio is generated independently with the same prompt and billed as one AI image generation.
The response is { assets, failures } — partial success is normal when one ratio fails quota or provider limits.
aveiro_social_generate_media accepts the same aspect_ratios parameter (max four).
When you attach multiple generic assets to a draft (no per-platform assignment), the publish dispatcher auto-picks each platform's preferred crop — Instagram 4:5 then 1:1; Threads 1:1 then 4:5. Explicit mediaAssignments with a platform field always win over auto-pick.
Org media storage — files uploaded through any dashboard dialog (brand assets, screenshots, AI images, and hosted videos). Browse with GET /api/v1/social/org-media (type=image default; type=video for dashboard video uploads and hosted ingests). Cursors are not interchangeable between the two types.
Social media library — assets registered or generated for social posts (GET /api/v1/social/media). Only these IDs attach to drafts.
To reuse an org upload on a social post, register its public URL with POST /api/v1/social/media (or aveiro_social_register_media). Registration is idempotent per URL. Use mediaType: "video" for Reels — the AI generator produces images only. For external video URLs, pass host: true to download and store a hosted copy on the platform CDN (recommended for scheduled posts so the post does not depend on the external URL staying alive until publish). On MCP, pass host: true with media_type: "video".
MCP tools
The Aveiro MCP server exposes thin wrappers around the same routes:
Tool
REST equivalent
aveiro_social_list_accounts
GET /api/v1/social/accounts
aveiro_social_list_posts
GET /api/v1/social/posts
aveiro_social_get_post
GET /api/v1/social/posts/{id}
aveiro_social_create_draft
POST /api/v1/social/posts
aveiro_social_update_draft
PATCH /api/v1/social/posts/{id}
aveiro_social_list_media
GET /api/v1/social/media
aveiro_social_list_org_media
GET /api/v1/social/org-media
aveiro_social_register_media
POST /api/v1/social/media
aveiro_social_generate_media
POST /api/v1/social/media/generate
Tools are available on the hosted MCP server and the stdio server in mcp/aveiro. See the Aveiro MCP README in the repo for local setup.
Proposed vs confirmed schedule
Agents set proposedScheduleAt on create or update. The dashboard row shows this as a proposed time. It never triggers publish.
When a human clicks Approve, the Set schedule calendar picker sets the confirmedscheduled_at. Only approved, scheduled posts reach Chirio via the dispatcher.
