Aveiro API
Authentication
Sites
List Sites
List Templates
Create Site
Pages
Create a Page
Delete a Page
List Pages
Reorder Pages
Update a Page
Site Media
Publish Site
Audience
Newsletter API Overview
Newsletter Campaigns
Social
Social API Overview
Social Accounts
Social Media
Social Posts
Social Performance
Website Mockup Video
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
Site Media
Publish Site
Audience
Newsletter API Overview
Newsletter Campaigns
Social
Social API Overview
Social Accounts
Social Media
Social Posts
Social Performance
Website Mockup Video

Authentication

Bearer tokens, scopes, site restrictions, and error responses for /api/v1.
Updated 2d ago
Aveiro API
Sponsored
Aveiro
aveiro.app
Sponsored
Aveiro
aveiro.app
TrademarkTrademark
AveiroBlogContact
© Aveiro. All rights reserved.
Built with Aveiro
In short
Create an org-scoped API token in Organization → API tokens. Send it as Authorization: Bearer av_live_… on every request. Scopes control what the token can do; site limits optionally restrict access to specific sites.

Creating a token

  • Open Organization → API tokens
  • Click Create token
  • Choose a recognizable name (for example CI docs sync)
  • Select scopes — destructive scopes are off by default
  • Optionally limit to specific sites (required for delete and publish unless you are an admin)
  • Copy the secret when shown — it is displayed only once
Store the token in your password manager or CI secrets (for example AVEIRO_API_TOKEN).

Request header

Scopes

Scope
Allows
sites:readList sites and read site metadata (default)
sites:writeCreate new sites
collections:writeCreate collections (folders)
content:readList and read draft pages (default)
content:writeCreate and update draft pages (default)
content:deleteDelete pages and collections
publish:writePublish or unpublish site content
audience:writeAdd subscribers via POST /api/v1/audience/subscribers
social:writeDraft and revise social posts; list accounts and media (no approve/publish)
newsletter:readList email campaigns, read their content and analytics
newsletter:writeCreate and revise draft email campaigns (no send/schedule)
Default token: sites:read, content:read, content:write. Delete and publish scopes require limiting the token to specific sites (non-admins).

Who can grant which scopes

Token creators can only include scopes their member permissions allow:
Scope
Requires capability
content:writeDocs update
audience:writeAudience manage
social:writeAudience manage
newsletter:readAudience manage
newsletter:writeCampaign create
Owners and admins can grant every scope. Members without the matching capability receive 403 when creating a token with a scope they cannot grant.

Check your token

Example response: When site_ids is null, the token can access every site you can edit. Otherwise only the listed site IDs are allowed.

Error responses

Failed requests return JSON with a stable error.code: Common codes:
Code
HTTP
Meaning
UNAUTHORIZED401Missing, invalid, or revoked token
FORBIDDEN403Token lacks scope or site access
NOT_FOUND404Site or page does not exist
VALIDATION_ERROR400Invalid request body or query
ALREADY_EXISTS409Page path already taken
IDEMPOTENCY_CONFLICT409Idempotency-Key reused with different body
REVISION_CONFLICT409If-Match revision is stale
INVALID_MDX422MDX content failed validation
BROKEN_BLOCKS422Page has invalid blocks — fix before publish
LIMIT_EXCEEDED403Organization limit reached
FILE_TOO_LARGE400Declared or measured file exceeds per-file cap
VIDEO_UPLOAD_NOT_ON_PLAN403Plan does not include video upload (free tier)
STORAGE_LIMIT_EXCEEDED403Organization storage quota full
PUBLISH_QUOTA_FULL403Plan site publish quota reached
CONFLICT409Post or campaign status cannot be edited by agents (social / newsletter routes)
GENERATION_FAILED502AI image generation failed (social media/generate)

Related

  • Aveiro API overview
  • List sites
Authorization: Bearer av_live_xxxxxxxxxxxxxxxx
Content-Type: application/json
GET /api/v1/me
Authorization: Bearer av_live_…
{
  "token": {
    "id": "3d308df4-8c1b-4cbd-af17-b124b6ec7b73",
    "name": "CI docs sync",
    "scopes": ["sites:read", "content:read", "content:write"],
    "site_ids": null
  },
  "organization": {
    "id": "org-uuid"
  },
  "created_by": "user-uuid"
}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API token"
  }
}