API Routes

Developers can use the SnowCMS API to integrate the CMS into their website.

Caution

The API is intended to be accessed server-side. Do not attempt to access it client-side as doing so will allow anyone to use your API key to request all data for your website from the CMS.

Tip

If all you need to do is get Collection Entries, you can use the Node.js client which can be used with or without TypeScript.

example.ts

import { SnowCMSClient } from '@binaryfrost/snowcms-client';

// These are example values, replace them with your own
const cmsUrl = 'https://cms.example.com';
const websiteId = '019423b3-4185-7aac-b956-85fa3d0d7486';
const blogCollectionId = '019423b3-6ef2-7aac-b956-8bea5c18db17';
const apikey = 'a:0194134c-9634-70b3-84c5-a6349eb92273.cCtoXUrQ6TjL3OlHMcpa-oxmiDkJHUQBaF6XKyVxi3c';

const client = new SnowCMSClient(cmsUrl, websiteId, apiKey);

interface BlogPost {
  title: string
  slug: string
  draft: boolean
  content: string
}

const posts = await client.getCollectionEntries<BlogPost>(blogCollectionId);
const filteredPosts = posts.filter(post => !post.data.draft);
// ...

URL

The base URL for the API is https://{snowcms_instance}/api/.

Authorization

Send the API key in the Authorization header in the following format: Bearer {key}.

Note

The API will take the lowest role between your API key and user account. A similar rule applies for websites. This is to ensure that if your role is lowered, or websites are removed, that your API keys reflect this change.

example.js

const resp = await fetch('https://cms.example.com/api/users/me', {
  headers: {
    // This is an example API key, replace it with your own
    Authorization: 'Bearer a:0194134c-9634-70b3-84c5-a6349eb92273.cCtoXUrQ6TjL3OlHMcpa-oxmiDkJHUQBaF6XKyVxi3c'
  }
});

if (resp.status !== 200) {
  // Handle error
} else {
  // Use data
}

Data Format

All requests and responses use JSON.

If an error occurs, there may be a error property containing additional information.

Routes

Any API routes not documented here should be considered internal, and not used.

All types referenced below can be found on GitHub.

Websites

GET /websites

Required Role: VIEWER
Response: Website[]

Returns all websites the user has access to.

POST /websites

Required Role: ADMIN
Request Data: Omit<Website, 'id'>>
Response: { id: string, message: string }

Creates a new website.

GET /websites/:id

Required Role: VIEWER
Response: Website

Returns the requested website, if it exists.

PUT /websites/:id

Required Role: SUPERUSER
Request Data: Omit<Website, 'id'>>
Response: { message: string }

Updates a website.

DELETE /websites/:id

Required Role: ADMIN
Response: { message: string }

Deletes a website along with all related Media, Collections, and Collection Entries.

Accounts

GET /accounts

Required Role: ADMIN
Response: UserWithWebsites[]

Returns all users, along with the ID of websites that they have access to.

POST /accounts

Required Role: ADMIN
Request Data: Omit<(DatabaseUser & UserWithWebsites), 'id'>
Response: { id: string, message: string }

Creates a new account.

GET /accounts/me

Required Role: VIEWER
Response: UserWithWebsites

Returns information about the logged in user. For API keys, the email returned is apikey@snowcms and active is based on both the user and API key active state.

GET /accounts/:userId

Required Role: VIEWER*
Response: UserWithWebsites

Returns information about an account.

* Any authenticated user can view their own account information. Users with the ADMIN role can request any account.

PUT /accounts/:userId

Required Role: USER*
Request Data: Omit<(DatabaseUser & UserWithWebsites), 'id'>**
Response: { message: string }

Updates a user account.

* Users with the USER role can change the email and password for their own account. Users with the ADMIN role can change other properties for any user.

** The password field is optional, all other fields are required.

DELETE /:userId

Required Role: ADMIN
Response: { message: string }

Deletes an account and all associated API keys.

GET /:userId/keys

Required Role: VIEWER*
Response: ApiKeyWithWebsites[]

Returns all API keys for user.

* Any authenticated user can view their own API keys. Users with the ADMIN role can request any account’s API keys.

POST /:userId/keys

Required Role: USER*
Request Data: Omit<ApiKeyWithWebsites, 'id'>
Response: { id: string, key: string, message: string }

Creates an API key.

* User with the USER role or above can create their own API keys. Users with the ADMIN role can manage any account’s API keys.

GET /:userId/keys/:keyId

Required Role: VIEWER*
Response: ApiKeyWithWebsites

Returns an API key.

* Any authenticated user can view their own API keys. Users with the ADMIN role can request any account’s API keys.

PUT /:userId/keys/:keyId

Required Role: USER*
Request Data: ApiKeyWithWebsites
Response: { message: string }

Updates an API key.

* User with the USER role or above can manage their own API keys. Users with the ADMIN role can manage any account’s API keys.

POST /:userId/keys/:keyId/reset

Required Role: USER*
Response: { id: string, key: string, message: string }

Resets an API key.

* User with the USER role or above can reset their own API keys. Users with the ADMIN role can manage any account’s API keys.

DELETE /:userId/keys/:keyId

Required Role: USER*
Response: { message: string }

Deletes an API key.

* User with the USER role or above can delete their own API keys. Users with the ADMIN role can manage any account’s API keys.

Collections

GET /websites/:websiteId/collections

Required Role: VIEWER
Response: Collection[]

Returns all Collections for a website.

POST /websites/:websiteId/collections

Required Role: SUPERUSER
Request Data: Omit<Collection, 'id' | 'websiteId'>
Response: { id: string, message: string }

Creates a Collection.

GET /websites/:websiteId/collections/:id

Required Role: VIEWER
Response: Collection

Returns a Collection.

PUT /websites/:websiteId/collections/:id

Required Role: SUPERUSER
Request Data: Omit<Collection, 'id' | 'websiteId'>
Response: { message: string }

Updates a Collection.

DELETE /websites/:websiteId/collections/:id

Required Role: SUPERUSER
Response: { message: string }

Deletes a Collection and all Collection Entries it contains.

Collection Title

GET /wesbites/:websiteId/colletions/:collectionId/title

Required Role: VIEWER
Response: CollectionTitle

Returns the ID of the Collection Input used as the Collection’s title.

PUT /wesbites/:websiteId/colletions/:collectionId/title

Required Role: SUPERUSER
Response: Omit<CollectionTitle, 'collectionId'>

Updates the ID of the Collection Input used as the Collection’s title.

Collection Inputs

GET /websites/:websiteId/collections/:collectionId/inputs

Required Role: VIEWER
Response: DatabaseCollectionInput[]

Returns all Collection Inputs.

POST /websites/:websiteId/collections/:collectionId/inputs

Required Role: SUPERUSER
Request Data: Omit<CollectionInput, 'id'>
Response: { id: string, message: string }

Creates a Collection Input, ordering it after other Collection Inputs.

PUT /websites/:websiteId/collections/:collectionId/inputs/:id

Required Role: SUPERUSER
Request Data: Omit<DatabaseCollectionInput, 'id'>
Response: { message: string }

Updates a Collection Input.

PATCH /websites/:websiteId/collections/:collectionId/inputs/:id/order

Required Role: SUPERUSER
Request Data: { order: number }
Response: { message: string }

Changes a Collection Input’s order.

Caution

You should ensure that this change does not result in non-consecutive ordering. For example, don’t set the order to 10 if there are less than 10 inputs. Doing so may break future ordering operations.

DELETE /websites/:websiteId/collections/:collectionId/inputs/:id

Required Role: SUPERUSER
Response: { message: string }

Deletes a Collection Input.

Collection Entries

GET /websites/:websiteId/collections/:collectionId/entries

Required Role: VIEWER
Response: CollectionEntryWithTitle[]

Returns all Collection Entries, along with the rendered title.

GET /websites/:websiteId/collections/:collectionId/entries/:id

Required Role: VIEWER
Response: CollectionEntryWithData | CollectionEntryWithRenderedData

Returns the Collection Entry.

This route has two possible response types:

Serialized Data

Returns the Collection Entry as type CollectionEntryWithData.

This type returns the serialized data for Collection Entry Inputs, as stored in the database and makes no attempt to render this data.

This is the default.

Rendered Data

Returns the Collection Entry as type CollectionEntryWithRenderedData.

This type returns the rendered data for Collection Entry Inputs, rendered to either an HTML string, a non-HTML string, or JSON. The return type depends on the Input.

To get the rendered data, add the ?render=true query parameter to the URL.

POST /websites/:websiteId/collections/:collectionId/entries

Required Role: USER
Request Data: Record<string, string>
Response: { id: string, message: string }

Creates a Collection Entry.

The body should be an object where the key is the Field Name of the Collection Input, and the value is the serialized Input value.

PATCH /websites/:websiteId/collections/:collectionId/entries/:id

Required Role: USER
Request Data: Record<string, string>
Response: { message: string }

Updates a Collection Entry.

The body should be an object where the key is the Field Name of the Collection Input, and the value is the serialized Input value.

Note

The method for this API route does not accurately describe it’s function. All required Collection Inputs must be present even if their values are unchanged. The method may be changed to PUT in the future.

DELETE /websites/:websiteId/collections/:collectionId/entries/:id

Required Role: USER
Response: { message: string }

Deletes a Collection Input.

Media

GET /websites/:websiteId/media

Required Role: VIEWER
Response: MediaWithUrls[]

Returns all Media for a website, including the URL and thumbnail URL.

GET /websites/:websiteId/media/config

Required Role: VIEWER
Response: MediaConfig

Returns the Media config.

GET /websites/:websiteId/media/:id

Required Role: VIEWER
Response: MediaWithUrls

Returns a Media file, including the URL and thumbnail URL.

POST /websites/:websiteId/media/upload

Required Role: USER
Request Data: FileMetadata
Response: FileUploadResponse

Request a pre-signed S3 upload URL.

Caution

After uploading the file to S3, you must send a request to /websites/:websiteId/media/upload/confirm to add the file to the database. Failure to do so may result in the file being deleted from S3.

POST /websites/:websiteId/media/upload/confirm

Required Role: USER
Request Data: FileUploadConfirmation
Response: { id: string, message: string }

See POST /websites/:websiteId/media/upload above.

DELETE /websites/:websiteId/media/:id

Required Role: USER
Response: { message: string }

Deletes a Media file.