Aveiro API
Authentication
Sites
List Sites
List Templates
Create Site
Pages
Create a Page
Delete a Page
List Pages
Reorder Pages
Update a Page
Audience
Newsletter API Overview
Newsletter Campaigns
Social
Social API Overview
Social Accounts
Social Media
Social Posts
TrademarkTrademark
Ctrl k
Search...
Sign up
Aveiro API
Authentication
Sites
List Sites
List Templates
Create Site
Pages
Create a Page
Delete a Page
List Pages
Reorder Pages
Update a Page
Audience
Newsletter API Overview
Newsletter Campaigns
Social
Social API Overview
Social Accounts
Social Media
Social Posts
TrademarkTrademark
AveiroBlogContact
© Aveiro. All rights reserved.
Built with Aveiro
Social

Social Posts

GET/POST /api/v1/social/posts and GET/PATCH /api/v1/social/posts/{postId} — list, create, read, and revise social drafts.
Updated 3d ago
Social Media
In short
List posts with optional status filter, create drafts for human review, fetch one post with its event timeline, or PATCH to revise after rejection. Agents cannot edit approved or published posts.

List posts

GET /api/v1/social/posts?status=&limit=&offset=
Authorization: Bearer av_live_…
Required scope: social:write

Query parameters

Param
Description
statusOptional filter: draft, pending_approval, approved, scheduled, publishing, published, failed, rejected
limitMax rows (default 50)
offsetPagination offset (default 0)

Example response

{
  "posts": [
    {
      "id": "post-uuid",
      "status": "pending_approval",
      "content": "Base caption text",
      "platformOverrides": { "threads": "Shorter Threads copy" },
      "firstComment": "Full link: https://example.com/article",
      "platformCommentOverrides": { "threads": "https://example.com/article" },
      "targets": [{ "platform": "instagram", "accountId": "acct-uuid" }],
      "proposedScheduleAt": "2026-07-28T18:00:00+00:00",
      "source": "mcp",
      "events": [
        {
          "type": "ai_revision",
          "body": "Draft created by agent",
          "actor": "agent"
        }
      ]
    }
  ]
}

Create draft

POST /api/v1/social/posts Authorization: Bearer av_live_… Content-Type: application/json { "content": "Base caption", "platformOverrides": { "threads": "Threads-specific copy" }, "firstComment": "https://example.com/post", "targets": [{ "platform": "instagram", "accountId": "acct-uuid" }], "proposedScheduleAt": "2026-07-28T18:00:00+00:00", "mediaAssignments": [ { "assetId": "asset-uuid", "platform": "instagram", "sortOrder": 0 } ], "submitForReview": true, "note": "Weekly product update — please review tone" }
Required scope: social:write

Body fields

Field
Required
Description
contentnoBase caption (max 10,000 chars). Defaults to empty string.
platformOverridesnoPer-platform captions. Keys: instagram, threads, x, linkedin.
firstCommentnoFirst comment posted from the author's account right after publish — link-in-comments pattern (max 2,200 chars). Published with the post after approval; failures appear in the event timeline.
platformCommentOverridesnoPer-platform first comments. Keys: instagram, threads, x, linkedin. Blank platforms use firstComment. Comment limits: instagram 2,200, threads 500, linkedin 1,250.
targetsnoArray of { platform, accountId } — max 10. IDs from GET /social/accounts.
proposedScheduleAtnoISO 8601 datetime with offset. Suggestion only — human approval sets the real schedule.
mediaAssignmentsnoArray of { assetId, platform, sortOrder } — max 20.
submitForReviewnoDefault true — moves draft to pending_approval. false keeps draft status.
notenoShown in the event timeline (max 5,000 chars).
Creates with source: "mcp". Returns 201 with { post }.
Targeting X on a free plan returns 402 PLAN_LIMIT — X is a paid-plan entitlement, separate from the publishing-credits balance.
Caption limits at validation: instagram 2,200, threads 500, linkedin 3,000 characters (REST may still accept legacy x keys on existing rows). Comment limits: instagram 2,200, threads 500, linkedin 1,250. At publish, Aveiro resolves each target's comment (override when set, else firstComment) before sending it to Chirio.

MCP tools

aveiro_social_create_draft and aveiro_social_update_draft accept the same body fields with snake_case names (first_comment, platform_comment_overrides, platform_overrides, proposed_schedule_at, and so on). MCP platform keys are instagram, threads, and linkedin — X is not available for new MCP drafts. The stdio proxy in mcp/aveiro matches the hosted MCP server for these fields.

Get post

GET /api/v1/social/posts/{postId}
Authorization: Bearer av_live_…
Required scope: social:write
Returns { post } including the full events timeline. Use this to read rejection comments before revising.

Update draft

PATCH /api/v1/social/posts/{postId}
Authorization: Bearer av_live_…
Content-Type: application/json

{
  "content": "Revised caption after feedback",
  "submitForReview": true,
  "note": "Shortened per rejection comment"
}
Required scope: social:write
Only posts in draft, pending_approval, or rejected status can be patched. Revising a rejected post re-submits to pending_approval by default.
Returns 409 CONFLICT if the post is approved, scheduled, publishing, published, or failed.

Errors

HTTP
Code
When
400VALIDATION_ERRORInvalid body or caption too long for platform
401UNAUTHORIZEDMissing or invalid token
403FORBIDDENToken lacks social:write
404NOT_FOUNDPost not found
402PLAN_LIMITTargets include X on a plan that does not include social_x_publishing
409CONFLICTPost status cannot be edited by agents

Related

  • Social API overview
  • Social accounts
  • Social media