Using the API

Owned by Chris Hopkins
Last updated: Oct 19, 2023 by Cyril Doussin
11 min read



For clarification of anything below, please contact Liquid State Support.

On This Page


Getting Started

This article details using the Carbon Editor API, including authentication, available views and actions and the hierarchy of information.


The Carbon Editor API is a restful representation of the information presented through the Carbon Editor User Interface (UI).

The API primarily uses JSON to respond to requests.


Some features available in the Carbon Editor UI are not yet supported by the API.

Currently, the API includes the basic information required to navigate the information hierarchy of Carbon Editor, and to import and export content.

The API does not yet include functionality for administrative configuration, or the editing of page content.


Identifiers

Each object in Carbon Editor and the API has a number of identifiers which are visible either in the Carbon Editor UI or the Carbon Editor API. These identifiers each have different uses and properties as detailed below.

IdentifierUnique?Use
NameNoThe human friendly name that is displayed throughout the Carbon Editor UI.
SlugYes*

An identifier generated from the object name.

Slugs are used throughout the Carbon Editor UI to generate URLs. If a conflict occurs between slugs, a numerical suffix will be generated for the new slug.

Example

A user creates two documents within their space, both of which are named Test Document.

The slug generated for the document that was created first will be test-document.

The slug generated for the document that was created second will be test-document-1.


UUIDYes

A global identifier for this object, which is unique throughout the entire system. Uses UUID Version 4.

All identifiers used within the API URLs use the UUID identifier.

Embedding IDYesAn identifier that allows a page, section, or field to be embedded within other documents. Can be set as a custom value, or will otherwise be automatically generated based on the object's title.

* Slugs are unique within their parent object - not throughout the entire Carbon Editor system. For example, Space slugs are unique per Organisation, while Document slugs are unique per Space. If you require a globally unique identifier use the relevant UUID.

Authentication

The Carbon Editor API supports token-based authentication when making requests via HTTPS.

Each API request is authenticated against a single user using your API token, which should be passed in the Authorization header of your request.

Your API token is available by navigating to the import document page. For more information, see Importing Content with the API.

Example Authorization Header

Authorization: Token {Your API Token}

Example Request using cURL

curl --header "Authorization: Token 52a1e6a5-9a18-4905-9d39-d31133c9c2dc" https://carbon.example.com/api/v1/organisations/


Organisation Endpoints

The following endpoints are used to list and view information about Organisations.

GET /api/v1/organisations/

  • Purpose: returns a list of Organisations.
  •  Response Type: application/JSON.

 Example Response:

[
  {
    "name": "My organisation",
    "url": "https://carbon.example.com/api/v1/organisations/bfc90580-e436-4cdb-a3d2-38340bb1ed57/",
    "uuid": "bfc90580-e436-4cdb-a3d2-38340bb1ed57",
    "slug": "my-organisation",
    "spaces": "https://carbon.example.com/api/v1/organisations/bfc90580-e436-4cdb-a3d2-38340bb1ed57/spaces/"
  }
]

GET /api/v1/organisations/{organisation}/

  • Purpose: returns the detail view for a single Organisation.
  • Response Type: application/JSON.

Example Response:

{
  "slug": "my-organisation",
  "name": "My organisation",
  "url": "https://carbon.example.com/api/v1/organisations/bfc90580-e436-4cdb-a3d2-38340bb1ed57/",
  "spaces": "https://carbon.example.com/api/v1/organisations/bfc90580-e436-4cdb-a3d2-38340bb1ed57/spaces/",
  "uuid": "bfc90580-e436-4cdb-a3d2-38340bb1ed57"
}


Space Endpoints

The following endpoints are used to list and view information about Spaces.

GET /api/v1/organisations/{organisation}/spaces/

  • Purpose: returns a list of the Spaces within this Organisation.
  • Response Type: application/JSON.

Example Response:

[
 {
 "slug": "default-space",
 "documents": "https://carbon.example.com/api/v1/organisations/bfc90580-e436-4cdb-a3d2-38340bb1ed57/spaces/af145166-b079-4cab-b140-b34d60c52a84/documents/",
 "uuid": "af145166-b079-4cab-b140-b34d60c52a84",
 "categories": "https://carbon.example.com/api/v1/organisations/bfc90580-e436-4cdb-a3d2-38340bb1ed57/spaces/af145166-b079-4cab-b140-b34d60c52a84/categories/",
 "name": "Default Space",
 "url": "https://carbon.example.com/api/v1/organisations/bfc90580-e436-4cdb-a3d2-38340bb1ed57/spaces/af145166-b079-4cab-b140-b34d60c52a84/",
 "automated_documents": "https://carbon.example.com/api/v1/organisations/bfc90580-e436-4cdb-a3d2-38340bb1ed57/spaces/af145166-b079-4cab-b140-b34d60c52a84/automated_documents/"
 },
 {
 "slug": "this-is-a-new-space",
 "documents": "https://carbon.example.com/api/v1/organisations/bfc90580-e436-4cdb-a3d2-38340bb1ed57/spaces/cae75d2c-1212-46da-b98d-22f444dae7de/documents/",
 "uuid": "cae75d2c-1212-46da-b98d-22f444dae7de",
 "categories": "https://carbon.example.com/api/v1/organisations/bfc90580-e436-4cdb-a3d2-38340bb1ed57/spaces/cae75d2c-1212-46da-b98d-22f444dae7de/categories/",
 "name": "This is a new space",
 "url": "https://carbon.example.com/api/v1/organisations/bfc90580-e436-4cdb-a3d2-38340bb1ed57/spaces/cae75d2c-1212-46da-b98d-22f444dae7de/",
 "automated_documents": "https://carbon.example.com/api/v1/organisations/bfc90580-e436-4cdb-a3d2-38340bb1ed57/spaces/cae75d2c-1212-46da-b98d-22f444dae7de/automated_documents/"
 }
]

GET /api/v1/organisations/{organisation}/spaces/{space}/

  • Purpose: returns the detail view for a particular Space.
  • Response Type: application/JSON.

Example Response:

{
 "slug": "default-space",
 "documents": "https://carbon.example.com/api/v1/organisations/bfc90580-e436-4cdb-a3d2-38340bb1ed57/spaces/af145166-b079-4cab-b140-b34d60c52a84/documents/",
 "uuid": "af145166-b079-4cab-b140-b34d60c52a84",
 "categories": "https://carbon.example.com/api/v1/organisations/bfc90580-e436-4cdb-a3d2-38340bb1ed57/spaces/af145166-b079-4cab-b140-b34d60c52a84/categories/",
 "name": "Default Space",
 "url": "https://carbon.example.com/api/v1/organisations/bfc90580-e436-4cdb-a3d2-38340bb1ed57/spaces/af145166-b079-4cab-b140-b34d60c52a84/",
 "automated_documents": "https://carbon.example.com/api/v1/organisations/bfc90580-e436-4cdb-a3d2-38340bb1ed57/spaces/af145166-b079-4cab-b140-b34d60c52a84/automated_documents/"
}


Category Endpoints

GET /api/v1/organisations/{organisation}/spaces/{space}/categories/

  • Purpose: returns a list of document categories within this space.
  • Response Type: application/JSON

Example Response:

[
	{
		"url": "https://carbon.example.com/api/v1/organisations/cc4dbb87-3e6a-4aeb-b194-60083a2f6cb2/spaces/d7cfb0ff-899c-47f0-976e-e018647b098a/categories/f92b8018-e819-48cc-a914-58e994ec83a4/",
		"slug": "all-documents",
		"name": "All Documents",
		"uuid": "f92b8018-e819-48cc-a914-58e994ec83a4",
		"documents": "https://carbon.example.com/api/v1/organisations/cc4dbb87-3e6a-4aeb-b194-60083a2f6cb2/spaces/d7cfb0ff-899c-47f0-976e-e018647b098a/categories/f92b8018-e819-48cc-a914-58e994ec83a4/documents/"
	}
]

GET /api/v1/organisations/{organisation}/spaces/{space}/categories/{category}/

  • Purpose: Retrieve the details of a single document category.
  • Response Type: application/JSON

Example Response

{
	"url": "https://carbon.example.com/api/v1/organisations/cc4dbb87-3e6a-4aeb-b194-60083a2f6cb2/spaces/d7cfb0ff-899c-47f0-976e-e018647b098a/categories/f92b8018-e819-48cc-a914-58e994ec83a4/",
	"slug": "all-documents",
	"name": "All Documents",
	"uuid": "f92b8018-e819-48cc-a914-58e994ec83a4",
	"documents": "https://carbon.example.com/api/v1/organisations/cc4dbb87-3e6a-4aeb-b194-60083a2f6cb2/spaces/d7cfb0ff-899c-47f0-976e-e018647b098a/categories/f92b8018-e819-48cc-a914-58e994ec83a4/documents/"
}

GET /api/v1/organisations/{organisation}/spaces/{space}/categories/{categories}/documents/

  • Purpose: Get the list of documents in this category
  • Response Type: application/JSON

Example Response

[
  {
    "url": "https://carbon.example.com/api/v1/organisations/bfc90580-e436-4cdb-a3d2-38340bb1ed57/spaces/af145166-b079-4cab-b140-b34d60c52a84/documents/be347cca-b682-4e04-b6ca-1740792445b2/",
    "uuid": "be347cca-b682-4e04-b6ca-1740792445b2",
	"name": "My Api Test Document",
	"slug": "my-api-test-document"
  }
]

POST /api/v1/organisations/{organisation}/spaces/{space}/categories/{categories}/documents/

  • Purpose: Add a document to this category
  • Request Type: application/x-www-form-urlencoded
  • Response Type: application/JSON
  • Required Parameters:
    • document: the UUID of the document you want to add to this category
  • Possible Errors:
    • HTTP 400: The document UUID does not exist in this space.

Example Response:

{
	"url": "https://carbon.example.com/api/v1/organisations/bfc90580-e436-4cdb-a3d2-38340bb1ed57/spaces/af145166-b079-4cab-b140-b34d60c52a84/documents/be347cca-b682-4e04-b6ca-1740792445b2/",
	"uuid": "be347cca-b682-4e04-b6ca-1740792445b2",
	"name": "My Api Test Document",
	"slug": "my-api-test-document"
}

DELETE /api/v1/organisations/{organisation}/spaces/{space}/categories/{categories}/documents/{document}/

  • Purpose: Remove a document from this category
  • Possible Errors: 
    • HTTP 404: The category or document UUID does not exist in this space
    • HTTP 400: This category cannot be removed (all-documents category)
  • Note: If the document is not currently in this category, this endpoint will still return successfully.

Example Response:

HTTP 204 No Content

Automated Document Endpoints

GET /api/v1/organisations/{organisation}/spaces/{space}/automated_documents/

  • Purpose: returns the list of automated documents in the space
  • Response Type: application/JSON
  • Notes: If the automated document is using a custom search, the search field will be populated with the json representation of that search, if a saved search is being used, the  saved search field will be a link to the saved search.

Example Response

[{
    "last_run_started": "2017-03-28T03:23:21Z",
    "is_automated": false,
    "search": null,
    "saved_search": "https://carbon.example.com/api/v1/organisations/bcadc4e7-211c-41ed-a1e9-3740d55e4269/spaces/be764da9-f81c-45be-ac1b-d9c1397d903f/saved_searches/1de6bb09-dd92-486f-b069-ea3403835775/",
    "last_run_ended": "2017-03-28T03:23:32Z",
    "ordering": "original_order",
    "slug": "test-2",
    "name": "Test",
    "status": "ready",
    "uuid": "aa46b2e1-c726-4852-bf90-cac1abeb257c",
    "url": "https://carbon.example.com/api/v1/organisations/bcadc4e7-211c-41ed-a1e9-3740d55e4269/spaces/be764da9-f81c-45be-ac1b-d9c1397d903f/automated_documents/aa46b2e1-c726-4852-bf90-cac1abeb257c/",
    "document": "https://carbon.example.com/api/v1/organisations/bcadc4e7-211c-41ed-a1e9-3740d55e4269/spaces/be764da9-f81c-45be-ac1b-d9c1397d903f/documents/2921caa1-2dd6-4d5f-9e1b-63f676158b9e/"
}]

POST /api/v1/organisations/{organisation}/spaces/{space}/automated_documents/

  • Purpose: Creates a new automated document configuration in this space.
  • Request Type: application/x-www-form-urlencoded
  • Response Type: application/JSON
  • Required Parameters:
    • name: The name of the Automated Document Configuration
    • ordering_strategy: How the included pages should be ordered in the resulting document, can be one of: 
      • original_order
      • alphanumerical
  • Optional Parameters:
    • custom_search: A JSON encoded advanced search query which will be used as the search for the automated document configuration
    • saved_search: The uuid of a saved search which will be used for the automated document configuration

Example Response:

{
    "last_run_started": "2017-03-28T03:23:21Z",
    "is_automated": false,
    "search": null,
    "saved_search": "https://carbon.example.com/api/v1/organisations/bcadc4e7-211c-41ed-a1e9-3740d55e4269/spaces/be764da9-f81c-45be-ac1b-d9c1397d903f/saved_searches/1de6bb09-dd92-486f-b069-ea3403835775/",
    "last_run_ended": "2017-03-28T03:23:32Z",
    "ordering": "original_order",
    "slug": "test-2",
    "name": "Test",
    "status": "ready",
    "uuid": "aa46b2e1-c726-4852-bf90-cac1abeb257c",
    "url": "https://carbon.example.com/api/v1/organisations/bcadc4e7-211c-41ed-a1e9-3740d55e4269/spaces/be764da9-f81c-45be-ac1b-d9c1397d903f/automated_documents/aa46b2e1-c726-4852-bf90-cac1abeb257c/",
    "document": "https://carbon.example.com/api/v1/organisations/bcadc4e7-211c-41ed-a1e9-3740d55e4269/spaces/be764da9-f81c-45be-ac1b-d9c1397d903f/documents/2921caa1-2dd6-4d5f-9e1b-63f676158b9e/"
}

DELETE /api/v1/organisations/{organisation}/spaces/{space}/documents/{automated_document}/

  • Purpose: delete this Automated Document Configuration
  • Example Response: 204 No Content

Document Endpoints

GET /api/v1/organisations/{organisation}/spaces/{space}/documents/

  • Purpose: returns a list of Documents within this Space
  • Response Type: application/JSON

Example Response:

[
  {
    "categories": "https://carbon.example.com/api/v1/organisations/bfc90580-e436-4cdb-a3d2-38340bb1ed57/spaces/af145166-b079-4cab-b140-b34d60c52a84/documents/dc96cff6-6538-490c-8357-e8392e7f1e08/categories/",
    "slug": "test-doc",
    "uuid": "dc96cff6-6538-490c-8357-e8392e7f1e08",
    "language": "en-gb",
    "imports": "https://carbon.example.com/api/v1/organisations/bfc90580-e436-4cdb-a3d2-38340bb1ed57/spaces/af145166-b079-4cab-b140-b34d60c52a84/documents/dc96cff6-6538-490c-8357-e8392e7f1e08/imports/",
    "name": "Test Doc",
    "url": "https://carbon.example.com/api/v1/organisations/bfc90580-e436-4cdb-a3d2-38340bb1ed57/spaces/af145166-b079-4cab-b140-b34d60c52a84/documents/dc96cff6-6538-490c-8357-e8392e7f1e08/",
    "versions": "https://carbon.example.com/api/v1/organisations/bfc90580-e436-4cdb-a3d2-38340bb1ed57/spaces/af145166-b079-4cab-b140-b34d60c52a84/documents/dc96cff6-6538-490c-8357-e8392e7f1e08/versions/",
	"pages": "https://carbon.example.com/api/v1/organisations/bfc90580-e436-4cdb-a3d2-38340bb1ed57/spaces/af145166-b079-4cab-b140-b34d60c52a84/documents/dc96cff6-6538-490c-8357-e8392e7f1e08/pages/",
	"embedding_id": "my-embedding-id"
  }
]

POST /api/v1/organisations/{organisation}/spaces/{space}/documents/

  • Purpose: creates a new Document within this Space
  • Request Type: application/x-www-form-urlencoded
  • Response Type: application/JSON
  • Required Parameters:
    • Name: string containing the name of the Document to be created.
  • Optional Parameters:
    • Language: The ISO-639-1 language code for the content of this document, used when rendering html. Only a limited subset of codes are supported, defaults to en-gb.
      • Supported codes:
        • da - Danish
        • de - German
        • en - English
        • en-gb - English (UK)
        • es - Spanish
        • fr - French
        • it - Italian
        • nb-no Norwegian
        • pt - Portuguese
        • sv - Swedish
    • Embedding ID: an identifier, unique to the object, that can be used to embed the document in another document. Should be set if pages, sections, or fields within the document will be embedded elsewhere. Otherwise, it will be automatically generated based on the Document title.

Example Response:

{
	"categories": "https://carbon.example.com/api/v1/organisations/bfc90580-e436-4cdb-a3d2-38340bb1ed57/spaces/af145166-b079-4cab-b140-b34d60c52a84/documents/0491e992-2de8-4da3-a8da-c0f95f624bf0/categories/",
	"slug": "test-new-doc-name",
	"uuid": "0491e992-2de8-4da3-a8da-c0f95f624bf0",
	"language": "en-gb",
	"imports": "https://carbon.example.com/api/v1/organisations/bfc90580-e436-4cdb-a3d2-38340bb1ed57/spaces/af145166-b079-4cab-b140-b34d60c52a84/documents/0491e992-2de8-4da3-a8da-c0f95f624bf0/imports/",
	"name": "Test New Doc Name",
	"url": "https://carbon.example.com/api/v1/organisations/bfc90580-e436-4cdb-a3d2-38340bb1ed57/spaces/af145166-b079-4cab-b140-b34d60c52a84/documents/0491e992-2de8-4da3-a8da-c0f95f624bf0/",
	"versions": "https://carbon.example.com/api/v1/organisations/bfc90580-e436-4cdb-a3d2-38340bb1ed57/spaces/af145166-b079-4cab-b140-b34d60c52a84/documents/0491e992-2de8-4da3-a8da-c0f95f624bf0/versions/",
	"pages": "https://carbon.example.com/api/v1/organisations/bfc90580-e436-4cdb-a3d2-38340bb1ed57/spaces/af145166-b079-4cab-b140-b34d60c52a84/documents/0491e992-2de8-4da3-a8da-c0f95f624bf0/pages/",
	"embedding_id": "my-embedding-id"
}

GET /api/v1/organisations/{organisation}/spaces/{space}/documents/{document}/

  • Purpose: view details about this Document.
  • Response Type: application/JSON

Example Response:

{
	"categories": "https://carbon.example.com/api/v1/organisations/bfc90580-e436-4cdb-a3d2-38340bb1ed57/spaces/af145166-b079-4cab-b140-b34d60c52a84/documents/0491e992-2de8-4da3-a8da-c0f95f624bf0/categories/",
	"slug": "test-new-doc-name",
	"uuid": "0491e992-2de8-4da3-a8da-c0f95f624bf0",
	"language": "en-gb",
	"imports": "https://carbon.example.com/api/v1/organisations/bfc90580-e436-4cdb-a3d2-38340bb1ed57/spaces/af145166-b079-4cab-b140-b34d60c52a84/documents/0491e992-2de8-4da3-a8da-c0f95f624bf0/imports/",
	"name": "Test New Doc Name",
	"url": "https://carbon.example.com/api/v1/organisations/bfc90580-e436-4cdb-a3d2-38340bb1ed57/spaces/af145166-b079-4cab-b140-b34d60c52a84/documents/0491e992-2de8-4da3-a8da-c0f95f624bf0/",
	"versions": "https://carbon.example.com/api/v1/organisations/bfc90580-e436-4cdb-a3d2-38340bb1ed57/spaces/af145166-b079-4cab-b140-b34d60c52a84/documents/0491e992-2de8-4da3-a8da-c0f95f624bf0/versions/",
	"pages": "https://carbon.example.com/api/v1/organisations/bfc90580-e436-4cdb-a3d2-38340bb1ed57/spaces/af145166-b079-4cab-b140-b34d60c52a84/documents/0491e992-2de8-4da3-a8da-c0f95f624bf0/pages/",
	"embedding_id": "my-embedding-id"
}

DELETE /api/v1/organisations/{organisation}/spaces/{space}/documents/{document}/

  • Purpose: delete this Document
  • Example Response: 204 No Content

GET /api/v1/organisations/{organisation}/spaces/{space}/documents/{document}/lock/

  • Purpose: get the locking status of a Document
  • Response Type: application/JSON

Example Response:

{
    "is_locked": false
}

POST /api/v1/organisations/{organisation}/spaces/{space}/documents/{document}/lock/

  • Purpose: lock a Document to prevent new import/export processes for this Document from starting.
  • Response Type: application/JSON

Example Response:

{
    "is_locked": true
}

DELETE /api/v1/organisations/{organisation}/spaces/{space}/documents/{document}/lock/

  • Purpose: remove any existing lock on a Document to allow new import/export processes for this Document to start.
  • Response Type: application/JSON

Example Response:

{
    "is_locked": false
}

GET /api/v1/organisations/{organisation}/spaces/{space}/documents/{document}/categories/

  • Purpose: view a list of the Document Categories in which this Document sits
  • Response Type: application/JSON

Example Response:

[
  {
    "url": "https://carbon.example.com/api/v1/organisations/bfc90580-e436-4cdb-a3d2-38340bb1ed57/spaces/af145166-b079-4cab-b140-b34d60c52a84/categories/be347cca-b682-4e04-b6ca-1740792445b2/",
    "uuid": "be347cca-b682-4e04-b6ca-1740792445b2"
  }
]

POST /api/v1/organisations/{organisation}/spaces/{space}/documents/{document}/categories/

  • Purpose: Add this document to an existing category in this space.
  • Request Type: application/x-www-form-urlencoded
  • Response Type: application/JSON
  • Required Parameters:
    • category: the UUID of the category you want to add this document to
  • Possible Errors:
    • HTTP 400: The category UUID does not exist in this space.

Example Response:

{
	"url": "https://carbon.example.com/api/v1/organisations/bfc90580-e436-4cdb-a3d2-38340bb1ed57/spaces/af145166-b079-4cab-b140-b34d60c52a84/categories/be347cca-b682-4e04-b6ca-1740792445b2/", 
	"uuid": "be347cca-b682-4e04-b6ca-1740792445b2"
}

DELETE /api/v1/organisations/{organisation}/spaces/{space}/documents/{document}/categories/{category}/

  • Purpose: Remove this document from category
  • Request Type: application/x-www-form-urlencoded
  • Response Type: application/JSON
  • Possible Errors: 
    • HTTP 404: The category UUID does not exist in this space
    • HTTP 400: This category cannot be removed (all-documents category)
  • Note: It is not an error to try and remove a valid category for the space from a document which is not in that category, this is because the end result is the same, the document is not in the category.

Example Response:

HTTP 204 No Content


Document Import Endpoints

GET /api/v1/organisations/{organisation}/spaces/{space}/documents/{document}/imports/

  • Purpose: List the imports which have been performed on this document
  • Response Type: application/JSON

Example Response:

[
	{
		"total_pages": 253, 
	 	"failure_message": null, 
		"modified_at": "2015-08-28T05:11:06.872Z", 
		"created_pages": 1, 
		"status": "complete", 
		"uuid": "056df238-4041-4aed-b558-f5e75808748b", 
		"url": "https://carbon.example.com/api/v1/organisations/bfc90580-e436-4cdb-a3d2-38340bb1ed57/spaces/af145166-b079-4cab-b140-b34d60c52a84/documents/ab6ffc3a-08fe-4e66-9aee-c13452a1c14e/imports/056df238-4041-4aed-b558-f5e75808748b/"
	}
]

POST /api/v1/organisations/{organisation}/spaces/{space}/documents/{document}/imports/

  • Purpose: Import new content into this document. Imports files can contain hundreds of pages and many asset files (for example images). Please try to keep images to the smallest possible file size to ensure your import will work.
  • Request Type: multipart/form-data
  • Response Type: application/JSON
  • Parameters:
    • import_file: An .xml or .zip file containing Liquid State Editor xml format. The zip file can also contain any assets required.
    • xml: A raw xml string in Liquid State Editor xml format.
  • Notes:
    • You should only send one of either import_file or xml not both.
    • You can update existing pages by specifying the id attribute onto page XML elements. See "id Attributes" in the Carbon Editor XML Format documentation.
  • See: Carbon Editor XML Format

Example Response: 

{
		"total_pages": 253, 
	 	"failure_message": null, 
		"modified_at": "2015-08-28T05:11:06.872Z", 
		"created_pages": 1, 
		"status": "complete", 
		"uuid": "056df238-4041-4aed-b558-f5e75808748b", 
		"url": "https://carbon.example.com/api/v1/organisations/bfc90580-e436-4cdb-a3d2-38340bb1ed57/spaces/af145166-b079-4cab-b140-b34d60c52a84/documents/ab6ffc3a-08fe-4e66-9aee-c13452a1c14e/imports/056df238-4041-4aed-b558-f5e75808748b/"
}

POST /api/v1/organisations/{organisation}/spaces/{space}/documents/{document}/simple_imports/

  • Purpose: Simple Imports let you import new content into this document, processing the import as part of the request, and returning preview URLs for each imported Page. This API endpoint is faster but has limitations:
    • it is reserved for import files with a very low number of pages. We recommend less than 10 pages, although more might work.
    • it must not be used for imports which would trigger a validation confirmation regarding conflicting system types. This means you should first perform one or more imports using the system types you will be using for Simple Imports, using the regular endpoint (see above) or the UI, and resolve any validation conflict.
    • the import zip file can contain asset files (for example images), but these must be small in size to keep the processing fast.
    • the API request's connection might be interrupted after 30 seconds. If this is the case you will obviously not get a response and there is no guarantee that the import worked. Please perform tests to ensure your content is small enough so the Simple Import API yields a response within 30 seconds.
    • Note
  • Request Type: multipart/form-data
  • Response Type: application/JSON
  • Parameters:
    • import_file: A .zip file containing pages in Liquid State Editor xml format. The zip file can also contain any assets required.
  • Notes:
    • You should only send one of either import_file or xml not both.
    • You can update existing pages by specifying the id attribute onto page XML elements. See "id Attributes" in the Carbon Editor XML Format documentation.
  • See: Carbon Editor XML Format

Example Response: 

{
		"total_pages": 2, 
	 	"failure_message": null, 
		"modified_at": "2015-08-28T05:11:06.872Z", 
		"created_pages": 1, 
		"status": "complete", 
		"uuid": "056df238-4041-4aed-b558-f5e75808748b", 
		"url": "http://carbon.example.com/api/v1/organisations/bfc90580-e436-4cdb-a3d2-38340bb1ed57/spaces/af145166-b079-4cab-b140-b34d60c52a84/documents/ab6ffc3a-08fe-4e66-9aee-c13452a1c14e/imports/056df238-4041-4aed-b558-f5e75808748b/",
		"page_previews": [
			"https://editor-example-com.s3.amazonaws.com/organisations/.../pages/page-1-uuid/index.html",
			"https://editor-example-com.s3.amazonaws.com/organisations/.../pages/page-2-uuid/index.html"
		],
		"import_data": []
}

GET /api/v1/organisations/{organisation}/spaces/{space}/documents/{document}/imports/{import}/

  • Purpose: View the details of this particular import
  • Response Type: application/JSON
  • Note: This view should be used to monitor an ongoing import session.

Example Response:

{
		"total_pages": 1, 
	 	"failure_message": null, 
		"modified_at": "2015-08-28T05:11:06.872Z", 
		"created_pages": 1, 
		"status": "complete", 
		"uuid": "056df238-4041-4aed-b558-f5e75808748b", 
		"url": "https://carbon.example.com/api/v1/organisations/bfc90580-e436-4cdb-a3d2-38340bb1ed57/spaces/af145166-b079-4cab-b140-b34d60c52a84/documents/ab6ffc3a-08fe-4e66-9aee-c13452a1c14e/imports/056df238-4041-4aed-b558-f5e75808748b/"
}


Document Version Endpoints

Document versions are permanent frozen versions of a document as it was at the time they were created. They are used to create document exports.

GET /api/v1/organisations/{organisation}/spaces/{space}/documents/{document}/versions/

  • Purpose: List the versions in this document
  • Response Type: application/JSON

Example Response:

[
  {
    "uuid": "19a0405d-59ae-490c-a386-11c80d6ff236",
    "created_at": "2015-12-09T00:29:42.705Z",
    "url": "https://carbon.example.com/api/v1/organisations/9887a8f6-4d84-41d6-b72e-1df94d465120/spaces/470b237e-2bea-4124-9358-a17647a12eac/documents/98141531-f2cf-4a75-8310-c24d0b88f811/versions/19a0405d-59ae-490c-a386-11c80d6ff236/",
    "exports": "https://carbon.example.com/api/v1/organisations/9887a8f6-4d84-41d6-b72e-1df94d465120/spaces/470b237e-2bea-4124-9358-a17647a12eac/documents/98141531-f2cf-4a75-8310-c24d0b88f811/versions/19a0405d-59ae-490c-a386-11c80d6ff236/exports/",
    "version": 1,
    "status": "ready"
  }
]

POST /api/v1/organisations/{organisation}/spaces/{space}/documents/{document}/versions/

  • Purpose: Create a new version with the next available version number for this document
  • Response Type: application/JSON

Example Response:

{
    "uuid": "19a0405d-59ae-490c-a386-11c80d6ff236",
    "created_at": "2015-12-09T00:29:42.705Z",
    "url": "https://carbon.example.com/api/v1/organisations/9887a8f6-4d84-41d6-b72e-1df94d465120/spaces/470b237e-2bea-4124-9358-a17647a12eac/documents/98141531-f2cf-4a75-8310-c24d0b88f811/versions/19a0405d-59ae-490c-a386-11c80d6ff236/",
    "exports": "https://carbon.example.com/api/v1/organisations/9887a8f6-4d84-41d6-b72e-1df94d465120/spaces/470b237e-2bea-4124-9358-a17647a12eac/documents/98141531-f2cf-4a75-8310-c24d0b88f811/versions/19a0405d-59ae-490c-a386-11c80d6ff236/exports/",
    "version": 1,
    "status": "ready"
}

GET /api/v1/organisations/{organisation}/spaces/{space}/documents/{document}/versions/{version}/

  • Purpose: View the details of a particular version
  • Response Type: application/JSON

Example Response:

{
    "uuid": "19a0405d-59ae-490c-a386-11c80d6ff236",
    "created_at": "2015-12-09T00:29:42.705Z",
    "url": "https://carbon.example.com/api/v1/organisations/9887a8f6-4d84-41d6-b72e-1df94d465120/spaces/470b237e-2bea-4124-9358-a17647a12eac/documents/98141531-f2cf-4a75-8310-c24d0b88f811/versions/19a0405d-59ae-490c-a386-11c80d6ff236/",
    "exports": "https://carbon.example.com/api/v1/organisations/9887a8f6-4d84-41d6-b72e-1df94d465120/spaces/470b237e-2bea-4124-9358-a17647a12eac/documents/98141531-f2cf-4a75-8310-c24d0b88f811/versions/19a0405d-59ae-490c-a386-11c80d6ff236/exports/",
    "version": 1,
    "status": "ready"
}


Document Export Endpoints

GET /api/v1/organisations/{organisation}/spaces/{space}/documents/{document}/versions/{version}/exports/

  • Purpose: List the exports of this document version
  • Response Type: application/JSON
  • Notes: 
    • failure message is a human readable message if the export was not successful, otherwise it is null
    • file is a link to the export.zip file which you can use to download the exported document. This will be null until the status field is "complete"

Example Response:

[
  {
    "modified_at": "2015-12-09T00:46:47.146Z",
    "pages_exported": 1,
    "failure_message": null,
    "uuid": "7ae7fa77-22f7-416a-90ef-590721b22865",
    "total_pages": 1,
    "url": "https://carbon.example.com/api/v1/organisations/9887a8f6-4d84-41d6-b72e-1df94d465120/spaces/470b237e-2bea-4124-9358-a17647a12eac/documents/98141531-f2cf-4a75-8310-c24d0b88f811/versions/19a0405d-59ae-490c-a386-11c80d6ff236/exports/7ae7fa77-22f7-416a-90ef-590721b22865/",
    "export_type": "xml",
    "theme": "",
    "file": "https://editor-example-com.s3.amazonaws.com/organisations/....",
    "status": "complete"
  }
]

POST /api/v1/organisations/{organisation}/spaces/{space}/documents/{document}/versions/{version}/exports/

  • Purpose: Create an export from this document version
  • Request Type: application/x-www-form-urlencoded
  • Response Type: application/JSON
  • Parameters: 
    • export_type: The export format you would like to create. Valid options are:
      • html - a single html document per page, similar to the preview in Carbon Editor
      • ubiquity - import directly into Liquid State Ubiquity this requires a Ubiquity API Key to be preconfigured in this Space.
      • xml - Liquid State XML format. See: Carbon Editor XML Format
      • indesign - Indesign XML format.
    • export_options: a JSON string containing options for this export. These vary depending on the export format.
      • HTML:
        • theme: the theme slug to render the html with. Currently theme slugs are not viewable in the API they are available by browsing to "Themes" in the Space Admin and looking at the URL.
          For example: https://editor.liquid-state.com/my-organisation/default-space/admin/design/document-theme/{theme-slug}/styles-layouts/. Ensure your theme format matches the format you are trying to export (HTML)
      • Ubiquity:
        • theme: as above.
        • company: The id of the company you are exporting to in ubiquity
        • app: The id of the app you are exporting to in ubiquity
        • use_existing_document: (true, false) indicate if you want to export as a new version of an existing Ubiquity document, or create a new Ubiquity document.
        • If you select to use an existing document you also need to provide:
          • document: The id of the document you want to create a new version of.
        • If you select to create a new document you also need to provide:
          • name_source: Where the name of the issue being imported should be sourced from. Valid options are:
            • document: Use the name of the current document as the Ubiquity document name
            • custom: Use a custom document name
          • name: If custom is selected above supply the desired issue name here
          • categories: a json list of the ubiquity category ids which the new issue should be placed in. This is only included if the app chosen supports categories, an empty list is valid.
        • publish_after_import: (true, false) indicate if you wish to publish immediately after importing. This is only recommended if you are creating a new version of an existing document.
      • XML and Indesign: These formats do not currently require options.

Example Response:

{
    "modified_at": "2015-12-09T00:46:47.146Z",
    "pages_exported": 1,
    "failure_message": null,
    "uuid": "7ae7fa77-22f7-416a-90ef-590721b22865",
    "total_pages": 1,
    "url": "https://carbon.example.com/api/v1/organisations/9887a8f6-4d84-41d6-b72e-1df94d465120/spaces/470b237e-2bea-4124-9358-a17647a12eac/documents/98141531-f2cf-4a75-8310-c24d0b88f811/versions/19a0405d-59ae-490c-a386-11c80d6ff236/exports/7ae7fa77-22f7-416a-90ef-590721b22865/",
    "format": "xml",
    "theme": "",
    "file": "https://editor-example-com.s3.amazonaws.com/organisations/....",
    "status": "complete"
}

GET /api/v1/organisations/{organisation}/spaces/{space}/documents/{document}/versions/{version}/exports/{export}/

  • Purpose: View the details of this particular export.
  • Response Type: application/JSON
  • Notes: 
    • failure message is a human readable message if the export was not successful, otherwise it is null
    • file is a link to the export.zip file which you can use to download the exported document. This will be null until the status field is "complete"

Example Response:

{
    "modified_at": "2015-12-09T00:46:47.146Z",
    "pages_exported": 1,
    "failure_message": null,
    "uuid": "7ae7fa77-22f7-416a-90ef-590721b22865",
    "total_pages": 1,
    "url": "https://carbon.example.com/api/v1/organisations/9887a8f6-4d84-41d6-b72e-1df94d465120/spaces/470b237e-2bea-4124-9358-a17647a12eac/documents/98141531-f2cf-4a75-8310-c24d0b88f811/versions/19a0405d-59ae-490c-a386-11c80d6ff236/exports/7ae7fa77-22f7-416a-90ef-590721b22865/",
    "format": "xml",
    "theme": "",
    "file": "https://editor-example-com.s3.amazonaws.com/organisations/....",
    "status": "complete"
}


Page Endpoints

GET /api/v1/organisations/{organisation}/spaces/{space}/documents/{document}/pages/

  • Purpose: List the pages in this document
  • Response Type: application/JSON

Example Response:

[
  {
    "url": "https://carbon.example.com/api/v1/organisations/9887a8f6-4d84-41d6-b72e-1df94d465120/spaces/470b237e-2bea-4124-9358-a17647a12eac/documents/f2d66edd-eb8f-4caf-a57e-8f080af5dfbd/pages/d2097867-bf93-4e99-b257-43f9e86470a9/",
    "name": "Procalcitonin",
    "uuid": "d2097867-bf93-4e99-b257-43f9e86470a9",
    "slug": "procalcitonin",
	"embedding_id": "procalcitonin"
  },
  {
    "url": "https://carbon.example.com/api/v1/organisations/9887a8f6-4d84-41d6-b72e-1df94d465120/spaces/470b237e-2bea-4124-9358-a17647a12eac/documents/f2d66edd-eb8f-4caf-a57e-8f080af5dfbd/pages/b26a7986-e370-440c-ad4e-9091bfd8879e/",
    "name": "Iron deficiency",
    "uuid": "b26a7986-e370-440c-ad4e-9091bfd8879e",
    "slug": "iron-deficiency",
	"embedding_id": "iron-deficiency"
  }
]

DELETE /api/v1/organisations/{organisation}/spaces/{space}/documents/{document}/pages/

  • Purpose: Remove all pages from a document
  • Response Type: application/JSON

Example Response:

HTTP 204 No Content


GET /api/v1/organisations/{organisation}/spaces/{space}/documents/{document}/pages/{page}/

  • Purpose: Show the details of this particular page
  • Response Type: application/JSON
  • Notes:
    • If preview_url is null no preview has been created yet. Calling generate_preview (GET) will create a new preview, redirect to it and populate this field next time the page is accessed.
    • generate_preview accepts theme as a get parameter. Theme should be:
      • one of the theme slugs available in this space. These slugs can be viewed in the space admin in the UI, API endpoint is still in development.
      • must be a theme with the HTML format.
      • If theme is not provided the default theme for the document is used.

Example Response:

{
    "url": "https://carbon.example.com/api/v1/organisations/9887a8f6-4d84-41d6-b72e-1df94d465120/spaces/470b237e-2bea-4124-9358-a17647a12eac/documents/f2d66edd-eb8f-4caf-a57e-8f080af5dfbd/pages/d2097867-bf93-4e99-b257-43f9e86470a9/",
    "name": "Procalcitonin",
    "uuid": "d2097867-bf93-4e99-b257-43f9e86470a9",
    "slug": "procalcitonin",
    "preview_url": "https://editor-example-com.s3.amazonaws.com/organisations/9887a8f6-4d84-41d6-b72e-1df94d465120/spaces/470b237e-2bea-4124-9358-a17647a12eac/documents/f2d66edd-eb8f-4caf-a57e-8f080af5dfbd/pages/d2097867-bf93-4e99-b257-43f9e86470a9/index.html",
    "generate_preview": "https://carbon.example.com/api/v1/organisations/9887a8f6-4d84-41d6-b72e-1df94d465120/spaces/470b237e-2bea-4124-9358-a17647a12eac/documents/f2d66edd-eb8f-4caf-a57e-8f080af5dfbd/pages/d2097867-bf93-4e99-b257-43f9e86470a9/generate_preview/",
	"embedding_id": "procalcitonin"
}

DELETE /api/v1/organisations/{organisation}/spaces/{space}/documents/{document}/pages/{page}/

  • Purpose: Remove this page from the document
  • Response Type: application/JSON

Example Response:

HTTP 204 No Content

Unless otherwise indicated in the Overview page of this WIKI the information contained within this space is Classified according to the /wiki/spaces/ISMS/pages/739344530 as

INTERNAL