API Documentation


Authentication

A number of endpoints require authentication in order to be called. Authenticating also allows the retrieval of unpublished components.
 

API Key

Authentication using API Key is via the following HTTP header.

X-OMNI-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 Omni-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. 

Login Session

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}

 

Endpoints

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/spaceCreate a space
GET/space/{id}Fetch a space by ID
GET/space/allFetch a list of all spaces
PUT/space/{id}Update a space by ID
DELETE/space/{id}Delete a space by ID
POST/componentCreate 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/searchSearch for components matching a criteria
PUT/component/sequenceUpdate 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/userCreate a user
GET/user/{id}Fetch a user by ID
GET/user/allFetch 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

Spaces are a virtual separation for serving different purposes. 
 

POST /space

This endpoint allows you to create a space.

ParameterTypeRequiredDescription
namestring (JSON)YesName of the space to be created.


* Authentication Required

Request example:

{
       name: "Monkeys"
}

 

Response example:

201 CREATED
Generic Response

GET /space/{id}

This endpoint allows you to fetch a particular space by its ID.

ParameterTypeRequiredDescription
idinteger (path)YesID of the space to retrieve.


* Authentication Required

Response examples:

200 OK

{
       id: 1,
       name: "Monkeys"
}


401 UNAUTHORIZED

{
       code: "omni.not.logged.in",
       message: "User is not logged in.",
       success: false
}
GET /space/all

This endpoint allows you to fetch all the spaces in your Omni-CMS instance.

* Authentication Required

Response example:

200 OK

{
       spaces: [
              {
                     id: 1,
                     name: "Monkeys"
              },
              …
       ]
}
PUT /space/{id}

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.

ParameterTypeRequiredDescription
idinteger (path)YesID of the space to be updated.
idinteger (JSON)YesMust be the same value as the ID in the path.
namestring (JSON)NoNew name of the space.


* Authentication Required

Request example:

{
       id: 1,
       name: "Animals"
}

 

Response examples:

200 OK
Generic Response

400 BAD REQUEST

{
       code: "omni.field.wrong.type",
       message: "The field ‘name’ was not of type string.",
       success: false
}
DELETE /space/{id}

This endpoint allows you to delete a space with the specified ID.

ParameterTypeRequiredDescription
idinteger (path)YesID of the space to be deleted.


* Authentication Required

Response example:

200 OK
Generic Response

 

Components

Components are the core of Omni-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.
 

POST /component

This endpoint allows you to create a component.

ParameterTypeRequiredDescription
keystring (JSON)YesA unique key within the space which you will be able to use to retrieve and differentiate this component.
spaceIdinteger (JSON)YesThe space ID for each this component should be created in.
parentIdinteger (JSON)YesThe ID of the parent component to link to.
componentTypestring (JSON)YesA type indicating what this component represents (can be arbitrary or a pre-defined Omni-Site type).
namestring (JSON)NoName of the component.
contentstring (JSON)NoThe component's content.
metadataobject (JSON)NoAn arbitrary object used to store any custom data.
tagsarray (JSON)NoAn array of strings representing tags to be associated with this component.
publishedboolean (JSON)NoWhether the component should be published.
Defaults to false.
visibleboolean (JSON)NoA 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.
sequenceinteger (JSON)NoThe order of this component amongst other components. Defaults to 1000.
datedatetime (JSON)NoA 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: "omni.component.duplicate.key",
       message: "The key sample-block' is currently used by another component (ID 82).",
       success: false
}
GET /component/{id}

This endpoint allows you to fetch a particular component by its ID.

ParameterTypeRequiredDescription
idinteger (path)YesID of the component to retrieve.
childrenstring (query)NoThe 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.
levelsinteger (query)NoThe depth of child components to return starting from the retrieved component.
Currently the maximum number of levels is 7. The default is 0.
limitinteger (query)NoThe maximum number of child components to be returned at each level.
orderstring (query)NoThe order in which child components are returned in.
Valid options include: id, date, sequence (default)
directionstring (query)NoThe direction to order child components in.
Valid options include: asc (default) for ascending, desc for descending
parentsstring (query)NoWhether to return the full chain of parents up to the space's root or just the closest.
Valid options include: all, closest (default)
contentLengthinteger (query)NoThe 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: "omni.component.not.found.id",
       message: "Component with ID 312 could not be found.",
       success: false
}
GET /component/{space_id}/{key}

This endpoint is the same as the GET /component/{id} endpoint except you specify the component by space ID and key instead.

ParameterTypeRequiredDescription
space_idinteger (path)YesID of the space that the component belongs in.
keystring (path)YesThe component key which is unique within the space.
childrenstring (query)NoThe 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.
levelsinteger (query)NoThe depth of child components to return starting from the retrieved component.
limitinteger (query)NoThe maximum number of child components to be returned at each level.
orderstring (query)NoThe order in which child components are returned in.
Valid options include: id, date, sequence (default)
directionstring (query)NoThe direction to order child components in.
Valid options include: asc (default) for ascending, desc for descending
parentsstring (query)NoWhether to return the full chain of parents up to the space's root or just the closest.
Valid options include: all, closest (default)
contentLengthinteger (query)NoThe maximum number of characters to allow in the content field before truncating.
This applies to child components as well.
PUT /component/{id}

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.

ParameterTypeRequiredDescription
idinteger (path)YesID of the component to be updated.
idstring (JSON)YesMust be the same value as the ID in the path.
keystring (JSON)NoA unique key within the space which you will be able to use to retrieve and differentiate this component.
componentTypestring (JSON)NoA type indicating what this component represents (can be arbitrary or a pre-defined Omni-Site type).
parentIdinteger (JSON)NoThe ID of the parent component to move this component under.
namestring (JSON)NoName of the component.
contentstring (JSON)NoThe component's content.
metadataobject (JSON)NoAn arbitrary object used to store any custom data.
tagsarray (JSON)NoAn array of strings representing tags to be associated with this component.
publishedboolean (JSON)NoWhether the component should be published.
Defaults to false.
visibleboolean (JSON)NoA 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.
sequenceinteger (JSON)NoThe order of this component amongst other components. Defaults to 1000.
datedatetime (JSON)NoA 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: "omni.component.reserved.key",
       message: "Sorry, 'root' is a reserved key.",
       success: false
}


400 BAD REQUEST

{
       code: "omni.component.invalid.key",
       message: "Keys can only be lowercase letters, numbers and hyphens(-).",
       success: false
}


400 BAD REQUEST

{
       code: "omni.component.space.change",
       message: "You cannot move component with ID 3 out of its current space (ID 1).",
       success: false
}


400 BAD REQUEST

{
       code: "omni.component.parent.self",
       message: "You cannot set component with ID 3 to be its own parent.",
       success: false
}
DELETE /component/{id}

This endpoint allows you to delete a component with the specified ID.

ParameterTypeRequiredDescription
idinteger (path)YesID of the component to be deleted.


* Authentication Required

Response example:

200 OK
Generic Response

POST /component/search

This endpoint allows you to search for components with matching terms.

ParameterTypeRequiredDescription
termsstring (JSON)NoThe terms to search for. Currently only the key and name of the components are searched.
tagsarray (JSON)NoTags which the matching components must have at least one of. Defaults to 50.
spaceIdinteger (JSON)NoThe space ID which matching components must belong to.
componentTypestring (JSON)NoThe component type which matching components must be.
limitinteger (JSON)NoThe maximum number of results to return.
orderstring (JSON)NoThe order in which child components are returned in.
Valid options include: id, date, sequence (default)
directionstring (JSON)NoThe direction to order child components in.
Valid options include: asc (default) for ascending, desc for descending
offsetinteger (JSON)NoOffset 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
}

 

ResponseTypeGuaranteedDescription
componentsarrayYesArray of matching component results.
totalintegerYesThe total number of components which match the search if there were no limits.
morebooleanYesWhether 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
}
PUT /component/sequence

This endpoint allows you to update the sequence for multiple components at once.

ParameterTypeRequiredDescription
sequencesarray (JSON)YesAn 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
              },
              …
       ]
}

 

ResponseTypeGuaranteedDescription
componentsarrayYesArray of matching component results.
totalintegerYesThe total number of components which match the search if there were no limits.
morebooleanYesWhether there would be more results if the limit or offset was higher.


Response example:

200 OK
Generic Response

GET /component/text/{id}

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).

ParameterTypeRequiredDescription
idinteger (path)YesID of the component to retrieve.


Response example:

200 OK
Content-Type: text/xml; charset=utf-8

GET /component/text/{space_id}/{key}

This endpoint is the same as the GET /component/text/{id} endpoint except you specify the component by space ID and key instead.

ParameterTypeRequiredDescription
space_idinteger (path)YesID of the space that the component belongs in.
keystring (path)YesThe component key which is unique within the space.
POST /component/file/{id}

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”.

ParameterTypeRequiredDescription
idinteger (path)YesID 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

GET /component/file/{id}

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”.

ParameterTypeRequiredDescription
idinteger (path)YesID 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: "omni.component.not.found.file",
       message: "No file was found for component with ID 4.",
       success: false
}
GET /component/file/{space_id}/{key}

This endpoint is the same as the GET /component/file/{id} endpoint except you specify the component by space ID and key instead.

ParameterTypeRequiredDescription
space_idinteger (path)YesID of the space that the component belongs in.
keystring (path)YesThe component key which is unique within the space.
GET /component/file/check/{id}

This endpoint allows you to check whether a file has been linked to a particular component by its ID.

ParameterTypeRequiredDescription
idinteger (path)YesID of the component to check.


* Authentication Required

Response example:

200 OK
Generic Response

DELETE /component/file/{id}

This endpoint allows you to delete a file attached to the component with the specified ID.

ParameterTypeRequiredDescription
idinteger (path)YesID of the component linked to the file to be deleted.


* Authentication Required

Response example:

200 OK
Generic Response

 

Users

You must authenticate as a user in order to call certain endpoints.
 

POST /user

This endpoint allows you to create a user.

ParameterTypeRequiredDescription
emailstring (JSON)YesUnique email address for the new user.
passwordstring (JSON)YesPassword for the new user.
activeboolean (JSON)NoWhether this user's account should be activated.
Defaults to true.


* Authentication Required

Request example:

{
       email: "andrew@omni-cms.com",
       password: "doHY[af2ODt_",
       active: false
}

 

Response examples:

201 CREATED
Generic Response

400 BAD REQUEST

{
       code: "omni.user.password.insecure",
       message: "Password must be at least 8 characters containing a minimum of 2 letters and 2 numbers.",
       success: false
}
GET /user/{id}

This endpoint allows you to fetch a particular user by its ID.

ParameterTypeRequiredDescription
idinteger (path)YesID of the user to retrieve.


* Authentication Required

ResponseTypeGuaranteedDescription
idintegerYesID of the user.
emailstringYesEmail address of the user.
apiKeyEnabledbooleanYesWhether there is currently an active API key enabled for this user.
activebooleanYesWhether this user's account is activated.


Response example:

200 OK

{
       id: 1,
       email: "andrew@omni-cms.com",
       apiKeyEnabled: true,
       active: true
}
GET /user/all

This endpoint allows you to fetch all the users in your Omni-CMS instance.

* Authentication Required

Response example:

200 OK

{
       users: [
              {
                     id: 1,
                     email: "andrew@omni-cms.com",
                     apiKeyEnabled: true,
                     active: true
              },
              …
       ]
}
PUT /user/{id}

This endpoint allows you to create a component.

ParameterTypeRequiredDescription
idinteger (path)YesID of the user to be updated.
idstring (JSON)YesMust be the same value as the ID in the path.
emailstring (JSON)NoA new email address for the user.
passwordstring (JSON)NoA new password for the user.
activeboolean (JSON)NoWhether the user should be activated or not.


* Authentication Required

Request example:

{
       id: 1,
       email: "andrew1@omni-cms.com",
       active: true
}

 

Response examples:

200 OK
Generic Response

400 BAD REQUEST

{
       code: "omni.user.duplicate.email",
       message: "The email ‘andrew1@omni-cms.com’ is currently used by another user (ID 2).",
       success: false
}
DELETE /user/{id}

This endpoint allows you to delete a user with the specified ID.

ParameterTypeRequiredDescription
idinteger (path)YesID of the user to be deleted.


* Authentication Required

Response examples:

200 OK
Generic Response

400 BAD REQUEST

{
       code: "omni.user.minimum.active",
       message: "There needs to be at least 1 active user.",
       success: false
}
PUT /user/key/{id}

This endpoint allows you to generate a new API key for a user.

ParameterTypeRequiredDescription
idinteger (path)YesID of the user to generate the key for.


* Authentication Required

ResponseTypeGuaranteedDescription
keystringYesThe newly generated API key. This is the only time you will be able to retrieve the key.
successbooleanYesWhether the key generation was successful.


Response example:

200 OK

{
       key: "E2ZHF1U787GULQFQWU0V3U3AZTCLSZAT5H1YAN6N1UCKBNUIKYOJ1UXQRI8EI0",
       success: true
}
DELETE /user/key/{id}

This endpoint allows you to remove any API key linked to the user with the specified ID.

ParameterTypeRequiredDescription
idinteger (path)YesID of the user to remove the key from.


* Authentication Required

Response example:

200 OK
Generic Response

Generic Response
ResponseTypeGuaranteedDescription
idintegerNoID relating to the request (e.g. newly created document).
messagestringYesGeneral explanation of the request's result.
successbooleanYesWhether the request was successful or not.
codestringNoCode relating to a particular type of error.


Response examples:

{
       id: 23,
       message: "Your request was successful.",
       success: true
}

 

{
       code: "omni.component.not.found.key",
       message: "Component with key 'test' could not be found.",
       success: false
}