Content

BASE URL: https://api.umbraco.io

Table of Contents

Common Headers

Authentication

Authentication is required for this API. This means that you must supply a Bearer Token via an Authorization header. Alternatively, you can supply an API Key via an Authorization or Api-Key header.

Permissions

In addition to the specific permissions listed under each endpoint, all requests requires:

  • Access to the Content Section of the Umbraco Backoffice and

  • That the content being accessed is beneath the users start node configured in Umbraco

Errors

If an error occours you will receive a HTTP status code along with an API error code and an error message in the response body.

Status Code
Error Code
Message

400

BadRequest

Body cannot be empty.

401

Unauthorized

Authorization has been denied for this request.

403

Forbidden

You are not authorized to access the given resource.

404

NotFound

Content with id '{id}' could not be found.

422

ValidationFailed

Validation error occured when trying to save or update the content item.

500

InternalServerError

Internal server error.

JSON example:

Get root content

Get all content at the root of the tree, which the authorized user has access to according to the 'Start node'-permissions.

URL: /content

Method: GET

Permissions required : Browse Node

Success Response

Code: 200

Content Example:

Get by id

Get specific content item by GUID ID. Includes all language variations.

URL: /content/{id}

Method: GET

Permissions required : Browse Node

Success Response

Code: 200

Content Example:

Get children

Get a list of children (content items) by parent GUID ID. Includes all language variations per content item.

URL: /content/{id}/children

Method: GET

Query Strings

Permissions required : Browse Node

Success Response

Code: 200

Content Example:

Create content

Create a new content item with one or more language variations.

All newly created content will be DRAFT by default. If you want to publish it you will need to issue a publish request as well.

URL: /content

Method: POST

Permissions required : Create

Request

In this example only one language exists, so the properties are marked with $invariant in the create request. If multiple languages exists the culture for each of the languages would be defined for each of the properties - example: "name": { "en-US": "Another one", "da-DK": "Endnu en" }.

If a property uses a multinode treepicker editor, the value should be a comma-separated list of Umbraco UDI Identifiers. In the example below, the UDI Identifiers are referencing content items. To learn more see the UDI Identifiers documentation.

Success Response

Code: 201

Content Example:

Create content with files

Create a new content item with one or more language variations and files.

When content contains an upload field it is possible to send a file along with the request to create new content. This is done by sending a multi-part request with the JSON body and the file.

If the content item doesn't include files then you can send a standard reqeust with a JSON payload to create a new content item.

All newly created content will be DRAFT by default. If you want to publish it you will need to issue a publish request as well.

URL: /content

Method: POST

Header: Content-Type: multipart/form-data; boundary=MultipartBoundry

Permissions required : Create

Request

The request must contain a field named content that contains the content JSON.

For the files being uploaded the field names must be in the format propertyName.culture. An example could be when the content has an upload property with the name fileUpload and the file is being uploaded to the en-US lanugage. In that case the field name should be fileUpload.en-US.

The property must also be includud in the content JSON and the value shoud be the filename.

Success Response

Code: 201

Content Example:

Update content

Updates an existing content item that has one or more language variations.

When content contains an upload field it is possible to send a file along with the request to update content. This is done by sending a multi-part request with the json body and the file, see Create content with files for an example. If the content item doesn't include files then you can send a standard reqeust with a JSON payload to update the content item.

URL: /content/{id}

Method: PUT

Permissions required : Update

Request

In this example only one language exists, so the properties are marked with $invariant. If multiple languages existed the culture for each of the languages would be defined for each of the properties. Ie.: "name": { "en-US": "Another one", "da-DK": "Endnu en" }.

If a property uses a multinode treepicker editor, the value should be a comma-separated list of Umbraco UDI Identifiers. In the example below, the UDI Identifiers are referencing content items. To learn more see the UDI Identifiers documentation.

Success Response

Code: 200

Content Example:

Publish content

Publish specific content item with all language variations or for a specific language.

URL: /content/{id}/publish

Method: PUT

Query Strings

Permissions required : Publish

Success Response

Code: 200

Content Example:

Unpublish content

Unpublish specific content item with all language variations or for a specific language.

URL: /content/{id}/unpublish

Method: PUT

Query Strings

Permissions required : Unpublish

Success Response

Code: 200

Content Example:

Delete content

Delete a specific content item with all its language variations.

URL: /content/{id}

Method: DELETE

Permissions required : Delete

Success Response

Code: 200

Content Example:

DELETE https://api.umbraco.io/content/041067a0-74f5-4d03-92af-40c3c0aa13e7

PreviousLanguagesNextContent Types

Last updated

Was this helpful?