REST API

The agencms REST API lets you manage your content from outside the dashboard. You can list and create websites, work with posts and pages, manage forms, and upload media. Everything is served under the /api/cms path and protected by a personal API key.

Get an API key

You authenticate with a personal API key (a bearer token) that you create in the dashboard.

Go to Settings > API keys at /settings/api.
Enter a Key name so you can recognize it later.
Submit the form. Your new key is shown once at the top of the page.
Copy it right away. It will not be shown again.

The number of keys you can create depends on your plan. If you hit your limit, you will see an upgrade prompt instead of the create form.

You can delete a key any time from the same page to revoke access.

Authenticate requests

Send your key as a bearer token in the Authorization header, and ask for JSON:

curl https://your-domain.example/api/user \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

All /api/cms endpoints (except the public icon and font lookups) require a valid key tied to an active account.

What you can do

Most CMS endpoints are scoped to a single website, so the path includes the website ID: /api/cms/websites/{website}/....

Websites

GET /api/cms/websites — list the websites you can access
POST /api/cms/websites — create a website
GET /api/cms/websites/{website} — view one website
PUT /api/cms/websites/{website} — update a website
DELETE /api/cms/websites/{website} — delete a website

Posts

GET /api/cms/websites/{website}/posts — list posts
POST /api/cms/websites/{website}/posts — create a post
GET /api/cms/websites/{website}/posts/{post} — view a post
PUT /api/cms/websites/{website}/posts/{post} — update a post
POST /api/cms/websites/{website}/posts/{post}/publish — publish a post
POST /api/cms/websites/{website}/posts/{post}/unpublish — unpublish a post

Post types are managed under the same website prefix at /post-types.

Forms

GET /api/cms/websites/{website}/forms — list forms
POST /api/cms/websites/{website}/forms — create a form
GET /api/cms/websites/{website}/forms/{form} — view a form
PUT /api/cms/websites/{website}/forms/{form} — update a form
PUT /api/cms/websites/{website}/forms/{form}/fields — replace the form's fields
POST /api/cms/websites/{website}/forms/{form}/activate — activate a form
POST /api/cms/websites/{website}/forms/{form}/deactivate — deactivate a form

Media and other resources

The resource library endpoints, under /api/cms/websites/{website}/library/..., return data you can reuse while building. This includes media, posts, pages, products, templates, themes, forms, users, and post-types.

For example, to list a website's media:

curl "https://your-domain.example/api/cms/websites/12/library/media" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Example: list and create

List the websites your key can see:

curl https://your-domain.example/api/cms/websites \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Create a website for yourself:

curl -X POST https://your-domain.example/api/cms/websites \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "owner_type": "user",
    "owner_id": 1,
    "name": "My New Site"
  }'

A successful create returns the new website as JSON with a 201 status. If you have reached your plan's website limit, the API returns a 403 with an error_code of feature_limit_reached and details about your quota.

For background on the concepts behind these endpoints, see Websites and Themes.

REST API

#Get an API key

#Authenticate requests

#What you can do

#Websites

#Posts

#Pages

#Forms

#Media and other resources

#Example: list and create