Aveiro API
Authentication
Sites
List Sites
List Templates
Create Site
Update Site Layout
Chrome Strings
Update Collection
Pages
Create a Page
Delete a Page
List Pages
Reorder Pages
Update a Page
Site Media
Publish Site
Link Translation
Import Media from URL
Audience
Newsletter API Overview
Newsletter Campaigns
Social
Social API Overview
Social Accounts
Social Media
Social Posts
Social Performance
Website Mockup Video
Social Post Review
TrademarkTrademark
Ctrl k
Search…
Sign up
Aveiro API
Authentication
Sites
List Sites
List Templates
Create Site
Update Site Layout
Chrome Strings
Update Collection
Pages
Create a Page
Delete a Page
List Pages
Reorder Pages
Update a Page
Site Media
Publish Site
Link Translation
Import Media from URL
Audience
Newsletter API Overview
Newsletter Campaigns
Social
Social API Overview
Social Accounts
Social Media
Social Posts
Social Performance
Website Mockup Video
Social Post Review

Social API Overview

Agent-facing REST routes for drafting Instagram and Threads posts. Requires social:write — approval and publish stay in the dashboard.
Updated 17 days ago
Social Accounts
TrademarkTrademark
AveiroBlogContact
© Aveiro. All rights reserved.
Built with Aveiro
In short
The /api/v1/social routes let agents list accounts, create and revise drafts, manage media, and read rejection feedback. All routes require social:write. Approving or rejecting a post needs the opt-in social:approve scope and works on one post at a time, after the user confirms it. There is no API route to publish immediately.

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
  • Approve or reject one post the user has just seen and confirmed — only with the opt-in social:approve scope
Typical workflow: agent drafts → human approves in Dashboard → Social, or confirms the post in their AI app → dispatcher publishes through Chirio at the scheduled time. 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. Approving and rejecting need a second scope, social:approve. It is opt-in: never part of a default or existing token, and an AI app connection has it only if the user ticked Allow approving and rejecting social posts when connecting. Approval is pinned to the post's revision, schedules the post (never publishes immediately), and runs the same checks as the dashboard. See Social post review. No scope grants Post now — publishing immediately exists only in the dashboard.

Base URL

Replace the host with your own app URL when self-hosting.

Endpoints

Guide
Method
Route
List accountsGET/api/v1/social/accounts
List postsGET/api/v1/social/posts
Create draftPOST/api/v1/social/posts
Get postGET/api/v1/social/posts/{postId}
Get performanceGET/api/v1/social/performance
Update draftPATCH/api/v1/social/posts/{postId}
Approve post (social:approve)POST/api/v1/social/posts/{postId}/approve
Reject post (social:approve)POST/api/v1/social/posts/{postId}/reject
List mediaGET/api/v1/social/media
Browse org mediaGET/api/v1/social/org-media
Register mediaPOST/api/v1/social/media
Generate mediaPOST/api/v1/social/media/generate
List website rendersGET/api/v1/social/video
Film a websitePOST/api/v1/social/video
Poll website renderGET/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. With social:approve, a confirmed post can be approved from draft, pending_approval, or rejected (it becomes scheduled), and rejected from any status except publishing and published — rejecting a scheduled post cancels its publish. 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 include social:write. They include social:approve (the aveiro_social_approve_post and aveiro_social_reject_post tools) only if the user ticked Allow approving and rejecting social posts on the consent screen; to add it to an existing connection, disconnect the app under Account settings → Security → Connected AI apps and connect it again.

Related

  • Authentication
  • Social performance
  • Social posts
  • Website mockup video
  • Social media
  • Social accounts
  • Platform docs: Social overview
https://help.aveiro.app/api/v1/social