API Tokens

In short

Organization → API tokens creates bearer tokens for automation. Default scopes list sites and read or write draft pages. Opt in to delete, publish, social drafts, create sites, or manage collections when creating the token.

When to use API tokens

Use tokens when you want tools such as Cursor, GitHub Actions, or internal scripts to:

List sites and pages in your organization
Create or update draft MDX content
Optionally create sites, collections, publish, delete, or draft social posts — when you grant those scopes

Tokens are not a replacement for signing into the dashboard. They are for machine access with a narrow scope.

Creating a token

Open Organization → API tokens.
Click Create token.
Enter a name you will recognize later (for example CI docs sync).
Choose scopes (see below). Destructive scopes are off by default.
Optionally limit to specific sites — required for delete and publish scopes (unless you are an org 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).

Scopes

Scope	Allows
sites:read	List sites the token can access (default)
sites:write	Create new sites
collections:write	Create collections (folders)
content:read	Read draft page content and metadata (default)
content:write	Create and update draft pages (default)
content:delete	Delete pages and collections
publish:write	Publish or unpublish site content
audience:write	Add email subscribers via API
social:write	Draft and revise social posts; list accounts and media (no approve/publish)
newsletter:read	List past email campaigns and read their content and analytics
newsletter:write	Draft and revise email campaigns (no send/schedule)

Scope	Requires capability
content:write	Docs update
audience:write	Audience manage
social:write	Audience manage
newsletter:read	Audience manage
newsletter:write	Campaign create

Endpoint	Purpose
GET /api/v1/me	Token name, org, scopes, and allowed site IDs
GET /api/v1/sites	List accessible sites
POST /api/v1/sites	Create a site (sites:write)
GET /api/v1/sites/{siteId}/collections	List collections
POST /api/v1/sites/{siteId}/collections	Create a collection
DELETE /api/v1/sites/{siteId}/collections/{id}	Delete a collection (content:delete)
GET /api/v1/sites/{siteId}/pages	List draft pages
GET /api/v1/sites/{siteId}/pages/by-path?path=...	Fetch one page by path
POST /api/v1/sites/{siteId}/pages	Create a draft page
PATCH /api/v1/sites/{siteId}/pages/{contentId}	Update draft content
POST /api/v1/sites/{siteId}/reorder	Reorder, move, or sort pages (content:write)
DELETE /api/v1/sites/{siteId}/pages/{contentId}	Soft-delete a page (content:delete)
POST /api/v1/sites/{siteId}/publish	Publish dirty drafts (publish:write)
POST /api/v1/sites/{siteId}/unpublish	Hide site or unpublish pages (publish:write)
GET /api/v1/sites/{siteId}/changes	List dirty drafts awaiting review
GET /api/v1/social/accounts	List connected social accounts (social:write)
GET/POST /api/v1/social/posts	List or create social drafts (social:write)
GET/PATCH /api/v1/social/posts/{postId}	Read or revise a social draft (social:write)
GET/POST /api/v1/social/media	List or register social media assets (social:write)
GET /api/v1/social/org-media	Browse org media storage — dashboard uploads (social:write)
POST /api/v1/social/media/generate	AI-generate social images — up to four aspectRatios per call (social:write)
GET/POST /api/v1/campaigns	List or draft email campaigns (newsletter:read / newsletter:write)
GET/PATCH /api/v1/campaigns/{campaignId}	Read or revise a draft campaign (newsletter:read / newsletter:write)
GET /api/v1/campaigns/{campaignId}/analytics	Send, open, click, and unsubscribe metrics (newsletter:read)

When to use API tokens

Creating a token

Scopes

When to use API tokens

Creating a token

Scopes

Who can grant which scopes

API endpoints

Idempotency

Revoking tokens

Workflow with the editor

API Tokens

When to use API tokens

Creating a token

Scopes

When to use API tokens

Creating a token

Scopes

Who can grant which scopes

API endpoints

Idempotency

Revoking tokens

Workflow with the editor

Related guides