A number of endpoints require authentication in order to be called. Authenticating also allows the retrieval of unpublished components.
Authentication using API Key is via the following HTTP header.
X-CHAUTEC-API-KEY: exampleapikey123
As with any API key, be careful not to expose this key in untrusted or publicly visible environments.
Each API key is linked to a user account and they must be generated before becoming available. The easiest way to do this is under user settings inside the Admin panel.
Alternatively it is possible to call the PUT /user/key/{id} regeneration endpoint directly. To do that however, you will need an existing API key or authenticate via login session described in the next section.
It is recommended that you use a separate API key for each app you need to integrate with.
Authenticating via API key is tidier in general but if you really wish to open a login session you can.
This method is not actually part of our API specification. It uses a different base URL and takes in the form POST values.
POST https://{api_domain}}/auth/login
email: {login_email}
password: {login_password}
The API endpoints all begin with: https://{api_domain}/api/{version}
Currently the only available version is v1. Please note that the response examples for each of the endpoints is not the exhaustive list.
| POST | /space | Create a space |
| GET | /space/{id} | Fetch a space by ID |
| GET | /space/all | Fetch a list of all spaces |
| PUT | /space/{id} | Update a space by ID |
| DELETE | /space/{id} | Delete a space by ID |
| POST | /component | Create a component |
| GET | /component/{id} | Fetch a component by ID |
| GET | /component/{space_id}/{key} | Fetch a component inside a space by key |
| PUT | /component/{id} | Update a component by ID |
| DELETE | /component/{id} | Delete a component by ID |
| POST | /component/search | Search for components matching a criteria |
| PUT | /component/sequence | Update the sequence for one or more components |
| GET | /component/text/{id} | Retrieve a component by ID as a text file for different MIME types |
| GET | /component/text/{space_id}/{key} | Retrieve a component inside a space by key as a text file for different MIME types |
| POST | /component/file/{id} | Upload a file to a component by ID |
| GET | /component/file/{id} | Retrieve a component by ID as a file |
| GET | /component/file/{spaceId}/{key} | Retrieve a component inside a space by key as a file |
| GET | /component/file/check/{id} | Check whether any file has been uploaded for a component by ID |
| DELETE | /component/file/{id} | Delete the file linked to a component by ID |
| POST | /user | Create a user |
| GET | /user/{id} | Fetch a user by ID |
| GET | /user/all | Fetch a list of all users |
| PUT | /user/{id} | Update a user by ID |
| DELETE | /user/{id} | Delete a user by ID |
| PUT | /user/key/{id} | Generate a new API key for a user by ID |
| DELETE | /user/key/{id} | Remove any existing API key for a user by ID |
Spaces are a virtual separation for serving different purposes.
This endpoint allows you to create a space.
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string (JSON) | Yes | Name of the space to be created. |
* Authentication Required
Request example:
| { name: "Monkeys" } |
Response example:
201 CREATED
Generic Response
This endpoint allows you to fetch a particular space by its ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | integer (path) | Yes | ID of the space to retrieve. |
* Authentication Required
Response examples:
200 OK
| { id: 1, name: "Monkeys" } |
401 UNAUTHORIZED
| { code: "chautec.not.logged.in", message: "User is not logged in.", success: false } |
This endpoint allows you to fetch all the spaces in your Chautec CMS instance.
* Authentication Required
Response example:
200 OK
| { spaces: [ { id: 1, name: "Monkeys" }, … ] } |
This endpoint allows you to update a space with the specified ID. If a field is not included in your request, it will not be removed or modified.
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | integer (path) | Yes | ID of the space to be updated. |
| id | integer (JSON) | Yes | Must be the same value as the ID in the path. |
| name | string (JSON) | No | New name of the space. |
* Authentication Required
Request example:
| { id: 1, name: "Animals" } |
Response examples:
200 OK
Generic Response
400 BAD REQUEST
| { code: "chautec.field.wrong.type", message: "The field ‘name’ was not of type string.", success: false } |
This endpoint allows you to delete a space with the specified ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | integer (path) | Yes | ID of the space to be deleted. |
* Authentication Required
Response example:
200 OK
Generic Response
Components are the core of API. Everything from a Page to a CSS file is composed of components.
The component ID must be unique across all spaces whereas the key must only be unique inside its own space.
Each space when created will have a root component which all of the space's components must fall under.
This endpoint allows you to create a component.
| Parameter | Type | Required | Description |
|---|---|---|---|
| key | string (JSON) | Yes | A unique key within the space which you will be able to use to retrieve and differentiate this component. |
| spaceId | integer (JSON) | Yes | The space ID for each this component should be created in. |
| parentId | integer (JSON) | Yes | The ID of the parent component to link to. |
| componentType | string (JSON) | Yes | A type indicating what this component represents (can be arbitrary or a pre-defined Site type). |
| name | string (JSON) | No | Name of the component. |
| content | string (JSON) | No | The component's content. |
| metadata | object (JSON) | No | An arbitrary object used to store any custom data. |
| tags | array (JSON) | No | An array of strings representing tags to be associated with this component. |
| published | boolean (JSON) | No | Whether the component should be published. Defaults to false. |
| visible | boolean (JSON) | No | A visibility flag indicating whether apps should display the record. This does not affect whether the component will be visible in the API. Defaults to true. |
| sequence | integer (JSON) | No | The order of this component amongst other components. Defaults to 1000. |
| date | datetime (JSON) | No | A date to attach to this component (e.g. 2021-12-10T13:49:51.141Z). Defaults to the time at creation. |
* Authentication Required
Request example:
| { key: "sample-block", name: "Sample Block", spaceId: 1, parentId: 17, content: "<p>This is an example of a block.</p>", metadata: { customField: "Sample custom field data" }, tags: [ "example", "new" ], componentType: "block", published: true, visible: true, sequence: 5, date: "2021-03-30T11:17:53.942Z" } |
Response examples:
201 CREATED
Generic Response
400 BAD REQUEST
| { code: "chautec.component.duplicate.key", message: "The key sample-block' is currently used by another component (ID 82).", success: false } |
This endpoint allows you to fetch a particular component by its ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | integer (path) | Yes | ID of the component to retrieve. |
| children | string (query) | No | The detail to be included for any child components. Valid options include: summary - include child components without their content field content - include child components with their content field If no valid option is specified, child components will not be included at all. |
| levels | integer (query) | No | The depth of child components to return starting from the retrieved component. Currently the maximum number of levels is 7. The default is 0. |
| limit | integer (query) | No | The maximum number of child components to be returned at each level. |
| order | string (query) | No | The order in which child components are returned in. Valid options include: id, date, sequence (default) |
| direction | string (query) | No | The direction to order child components in. Valid options include: asc (default) for ascending, desc for descending |
| parents | string (query) | No | Whether to return the full chain of parents up to the space's root or just the closest. Valid options include: all, closest (default) |
| contentLength | integer (query) | No | The maximum number of characters to allow in the content field before truncating. This applies to child components as well. |
Response examples:
200 OK
| { id: 17, key: "sample-page", name: "Sample Page", spaceId: 1, content: "<p>This is an example of page.</p>", metadata: { customField: "Sample custom field data", … }, parents: [ { id: 9, key: "sample-menu", name: "Sample Menu" }, … ], componentType: "page", published: true, visible: true, sequence: 7, date: "2021-03-30T11:17:53.942Z", children: [ { id: 53, key: "sample-html", name: "Sample HTML", metadata: { }, componentType: "html", published: true, visible: true, sequence: 1, date: "2021-03-30T11:19:43.193Z", tags: [ "sample" ] }, … ], tags: [ "example", "new" ] } |
404 NOT FOUND
| { code: "chautec.component.not.found.id", message: "Component with ID 312 could not be found.", success: false } |
This endpoint is the same as the GET /component/{id} endpoint except you specify the component by space ID and key instead.
| Parameter | Type | Required | Description |
|---|---|---|---|
| space_id | integer (path) | Yes | ID of the space that the component belongs in. |
| key | string (path) | Yes | The component key which is unique within the space. |
| children | string (query) | No | The detail to be included for any child components. Valid options include: summary - include child components without their content field content - include child components with their content field If no valid option is specified, child components will not be included at all. |
| levels | integer (query) | No | The depth of child components to return starting from the retrieved component. |
| limit | integer (query) | No | The maximum number of child components to be returned at each level. |
| order | string (query) | No | The order in which child components are returned in. Valid options include: id, date, sequence (default) |
| direction | string (query) | No | The direction to order child components in. Valid options include: asc (default) for ascending, desc for descending |
| parents | string (query) | No | Whether to return the full chain of parents up to the space's root or just the closest. Valid options include: all, closest (default) |
| contentLength | integer (query) | No | The maximum number of characters to allow in the content field before truncating. This applies to child components as well. |
This endpoint allows you to update a component with the specified ID. If a field is not included in your request, it will not be removed or modified.
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | integer (path) | Yes | ID of the component to be updated. |
| id | string (JSON) | Yes | Must be the same value as the ID in the path. |
| key | string (JSON) | No | A unique key within the space which you will be able to use to retrieve and differentiate this component. |
| componentType | string (JSON) | No | A type indicating what this component represents (can be arbitrary or a pre-defined Site type). |
| parentId | integer (JSON) | No | The ID of the parent component to move this component under. |
| name | string (JSON) | No | Name of the component. |
| content | string (JSON) | No | The component's content. |
| metadata | object (JSON) | No | An arbitrary object used to store any custom data. |
| tags | array (JSON) | No | An array of strings representing tags to be associated with this component. |
| published | boolean (JSON) | No | Whether the component should be published. Defaults to false. |
| visible | boolean (JSON) | No | A visibility flag indicating whether apps should display the record. This does not affect whether the component will be visible in the API. Defaults to true. |
| sequence | integer (JSON) | No | The order of this component amongst other components. Defaults to 1000. |
| date | datetime (JSON) | No | A date to attach to this component (e.g. 2021-12-10T13:49:51.141Z). Defaults to the time at creation. |
* Authentication Required
Request example:
| { id: 3, key: "sample-block", name: "Sample Block", content: "<p>This is an example of a block.</p>", metadata: { customField: "Sample custom field data" }, tags: [ "old" ], componentType: "block", parentId: 34, published: true, visible: true, sequence: 17, date: "2021-03-30T11:17:53.942Z" } |
Response examples:
200 OK
Generic Response
400 BAD REQUEST
| { code: "chautec.component.reserved.key", message: "Sorry, 'root' is a reserved key.", success: false } |
400 BAD REQUEST
| { code: "chautec.component.invalid.key", message: "Keys can only be lowercase letters, numbers and hyphens(-).", success: false } |
400 BAD REQUEST
| { code: "chautec.component.space.change", message: "You cannot move component with ID 3 out of its current space (ID 1).", success: false } |
400 BAD REQUEST
| { code: "chautec.component.parent.self", message: "You cannot set component with ID 3 to be its own parent.", success: false } |
This endpoint allows you to delete a component with the specified ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | integer (path) | Yes | ID of the component to be deleted. |
* Authentication Required
Response example:
200 OK
Generic Response
This endpoint allows you to search for components with matching terms.
| Parameter | Type | Required | Description |
|---|---|---|---|
| terms | string (JSON) | No | The terms to search for. Currently only the key and name of the components are searched. |
| tags | array (JSON) | No | Tags which the matching components must have at least one of. Defaults to 50. |
| spaceId | integer (JSON) | No | The space ID which matching components must belong to. |
| componentType | string (JSON) | No | The component type which matching components must be. |
| limit | integer (JSON) | No | The maximum number of results to return. |
| order | string (JSON) | No | The order in which child components are returned in. Valid options include: id, date, sequence (default) |
| direction | string (JSON) | No | The direction to order child components in. Valid options include: asc (default) for ascending, desc for descending |
| offset | integer (JSON) | No | Offset to start from when limiting search results. |
Request example:
| { terms: "sample", tags: [ "old" ], spaceId: 2, limit: 2, componentType: "page", order: "date", direction: "desc" offset: 1 } |
| Response | Type | Guaranteed | Description |
|---|---|---|---|
| components | array | Yes | Array of matching component results. |
| total | integer | Yes | The total number of components which match the search if there were no limits. |
| more | boolean | Yes | Whether there would be more results if the limit or offset was higher. |
Response example:
200 OK
| { components: [ { id: 13, key: "test-page", name: "Sample Page", spaceId: 1, content: "<p>This is an example of page.</p>", metadata: { }, parents: [ { id: 9, key: "sample-menu", name: "Sample Menu" } ], componentType: "page", published: true, visible: true, sequence: 5, date: "2021-03-30T11:17:53.942Z", tags: [ "example", "old" ], }, … ], total: 6, more: true } |
This endpoint allows you to update the sequence for multiple components at once.
| Parameter | Type | Required | Description |
|---|---|---|---|
| sequences | array (JSON) | Yes | An array of objects which contain the component id and sequence to update to. |
* Authentication Required
Request example:
| { sequences: [ { id: 13, sequence: 1 }, { id: 5, sequence: 2 }, … ] } |
| Response | Type | Guaranteed | Description |
|---|---|---|---|
| components | array | Yes | Array of matching component results. |
| total | integer | Yes | The total number of components which match the search if there were no limits. |
| more | boolean | Yes | Whether there would be more results if the limit or offset was higher. |
Response example:
200 OK
Generic Response
This endpoint allows you to fetch a particular component by its ID as a dynamic text file.
The mime type of the returned file will be based on the componentType field. Current supported formats include css, js, xml and text (default).
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | integer (path) | Yes | ID of the component to retrieve. |
Response example:
200 OK
Content-Type: text/xml; charset=utf-8
This endpoint is the same as the GET /component/text/{id} endpoint except you specify the component by space ID and key instead.
| Parameter | Type | Required | Description |
|---|---|---|---|
| space_id | integer (path) | Yes | ID of the space that the component belongs in. |
| key | string (path) | Yes | The component key which is unique within the space. |
This endpoint allows you to upload a file attaching it to the component with the specified ID. The MIME type of the uploaded file is detected and automatically placed inside the component's metadata under the key “mimeType”.
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | integer (path) | Yes | ID of the component to attach the file to. |
* Authentication Required
Content-Type: multipart/form-data
Content-Disposition: form-data; name="fileUpload"
Response example:
200 OK
Generic Response
This endpoint allows you to fetch the file linked to a particular component by its ID. The response Content-Type will be whatever is set in the component's metadata mimeType which is automatically populated when the file is uploaded. If this mimeType field is removed, it will default to use “application/octet-stream”.
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | integer (path) | Yes | ID of the component linked to the file to be retrieved. |
Response examples:
200 OK
Content-Disposition: attachment; filename="{component_name}"
Content-Type: application/octet-stream
404 NOT FOUND
| { code: "chautec.component.not.found.file", message: "No file was found for component with ID 4.", success: false } |
This endpoint is the same as the GET /component/file/{id} endpoint except you specify the component by space ID and key instead.
| Parameter | Type | Required | Description |
|---|---|---|---|
| space_id | integer (path) | Yes | ID of the space that the component belongs in. |
| key | string (path) | Yes | The component key which is unique within the space. |
This endpoint allows you to check whether a file has been linked to a particular component by its ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | integer (path) | Yes | ID of the component to check. |
* Authentication Required
Response example:
200 OK
Generic Response
This endpoint allows you to delete a file attached to the component with the specified ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | integer (path) | Yes | ID of the component linked to the file to be deleted. |
* Authentication Required
Response example:
200 OK
Generic Response
You must authenticate as a user in order to call certain endpoints.
This endpoint allows you to create a user.
| Parameter | Type | Required | Description |
|---|---|---|---|
| string (JSON) | Yes | Unique email address for the new user. | |
| password | string (JSON) | Yes | Password for the new user. |
| active | boolean (JSON) | No | Whether this user's account should be activated. Defaults to true. |
* Authentication Required
Request example:
| { email: "andrew@chautec.com", password: "doHY[af2ODt_", active: false } |
Response examples:
201 CREATED
Generic Response
400 BAD REQUEST
| { code: "chautec.user.password.insecure", message: "Password must be at least 8 characters containing a minimum of 2 letters and 2 numbers.", success: false } |
This endpoint allows you to fetch a particular user by its ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | integer (path) | Yes | ID of the user to retrieve. |
* Authentication Required
| Response | Type | Guaranteed | Description |
|---|---|---|---|
| id | integer | Yes | ID of the user. |
| string | Yes | Email address of the user. | |
| apiKeyEnabled | boolean | Yes | Whether there is currently an active API key enabled for this user. |
| active | boolean | Yes | Whether this user's account is activated. |
Response example:
200 OK
| { id: 1, email: "andrew@chautec.com", apiKeyEnabled: true, active: true } |
This endpoint allows you to fetch all the users in your Chautec CMS instance.
* Authentication Required
Response example:
200 OK
| { users: [ { id: 1, email: "andrew@chautec.com", apiKeyEnabled: true, active: true }, … ] } |
This endpoint allows you to create a component.
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | integer (path) | Yes | ID of the user to be updated. |
| id | string (JSON) | Yes | Must be the same value as the ID in the path. |
| string (JSON) | No | A new email address for the user. | |
| password | string (JSON) | No | A new password for the user. |
| active | boolean (JSON) | No | Whether the user should be activated or not. |
* Authentication Required
Request example:
| { id: 1, email: "andrew1@chautec.com", active: true } |
Response examples:
200 OK
Generic Response
400 BAD REQUEST
| { code: "chautec.user.duplicate.email", message: "The email ‘andrew1@chautec.com’ is currently used by another user (ID 2).", success: false } |
This endpoint allows you to delete a user with the specified ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | integer (path) | Yes | ID of the user to be deleted. |
* Authentication Required
Response examples:
200 OK
Generic Response
400 BAD REQUEST
| { code: "chautec.user.minimum.active", message: "There needs to be at least 1 active user.", success: false } |
This endpoint allows you to generate a new API key for a user.
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | integer (path) | Yes | ID of the user to generate the key for. |
* Authentication Required
| Response | Type | Guaranteed | Description |
|---|---|---|---|
| key | string | Yes | The newly generated API key. This is the only time you will be able to retrieve the key. |
| success | boolean | Yes | Whether the key generation was successful. |
Response example:
200 OK
| { key: "E2ZHF1U787GULQFQWU0V3U3AZTCLSZAT5H1YAN6N1UCKBNUIKYOJ1UXQRI8EI0", success: true } |
This endpoint allows you to remove any API key linked to the user with the specified ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | integer (path) | Yes | ID of the user to remove the key from. |
* Authentication Required
Response example:
200 OK
Generic Response
| Response | Type | Guaranteed | Description |
|---|---|---|---|
| id | integer | No | ID relating to the request (e.g. newly created document). |
| message | string | Yes | General explanation of the request's result. |
| success | boolean | Yes | Whether the request was successful or not. |
| code | string | No | Code relating to a particular type of error. |
Response examples:
| { id: 23, message: "Your request was successful.", success: true } |
| { code: "chautec.component.not.found.key", message: "Component with key 'test' could not be found.", success: false } |