Entities API (v2.0)

Use the Entities API to retrieve, create, update, and delete entities. An entity is a set of data that belongs together (such as for a product, campaign, project, story, recipe, or asset).

Authentication

To use the Try it feature of the Entities API, you need:

  • The URL of your Content Hub server. You can get this from your Content Hub Administrator. Enter this URL in the {{server}} variable by hovering over the variable in the Try it pane and then clicking Edit.
  • An access token and the client ID. Both are sent with every request. You can create a token through the Content Hub interface or by requesting one to the API itself
    Note
    A Copy method is also available.
Download OpenAPI description
Overview
Languages
Servers
https://{server}/

Entities

The Entities endpoint is used to manage entities.

Operations

Lifecycle

The Lifecycle endpoint is used to manage the entity lifecycle and validate user permissions to perform various actions.

Operations

Retrieve lifecycle actions

Request

Retrieves the lifecycle actions that are available for the entity based on its permissions (independent of its current state). For example, if a user is allowed to submit an entity, the submit action will be returned in the list, even if the entity has already been approved.

Path
idinteger(int64)required

The unique identifier for the entity.

curl -i -X GET \
  'https://your-server/api/entities/{id}/lifecycle' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Lifecycle actions retrieved successfully

Bodyapplication/json
actionsobject or null

A list of actions that can be performed on the entity with an API link to perform them.

selfobject(Link)

Represents a link to a resource.

Response
application/json
{ "actions": { "property1": {}, "property2": {} }, "self": { "href": "string", "filename_properties": [], "title": "string", "templated": false } }

Submit an entity for review

Request

Submits an entity in the created state for review allowing the user to approve or reject it. Requires the Submit permission.

Path
idinteger(int64)required

The unique identifier for the entity.

curl -i -X POST \
  'https://your-server/api/entities/{id}/lifecycle/submit' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Entity successfully submitted

Publish an entity directly

Request

Publishes an entity with the created state directly, without going through the approval process. Requires the DirectPublish permission.

Path
idinteger(int64)required

The unique identifier for the entity.

curl -i -X POST \
  'https://your-server/api/entities/{id}/lifecycle/directpublish' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Entity published successfully

Approve an entity

Request

Approves an entity in the review state. Requires the Approve permission.

Path
idinteger(int64)required

The unique identifier for the entity.

curl -i -X POST \
  'https://your-server/api/entities/{id}/lifecycle/approve' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Entity approved successfully

Reject an entity

Request

Rejects an entity in the review state. A reason for the rejection must be provided. Requires the Reject permission.

Path
idinteger(int64)required

The unique identifier for the entity.

Body

The reject request containing the reason for the rejection.

reasonstring or null

The reason for the rejection.

curl -i -X POST \
  'https://your-server/api/entities/{id}/lifecycle/reject' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json-patch+json' \
  -d '{
    "reason": "string"
  }'

Responses

Entity rejected successfully

Archive an entity

Request

Archives an approved entity. The entity can be restored if needed. Requires the Archive permission.

Path
idinteger(int64)required

The unique identifier for the entity.

curl -i -X POST \
  'https://your-server/api/entities/{id}/lifecycle/archive' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Entity archived successfully

Restore an entity

Request

Restores an archived entity to the approved state. Requires the Archive permission.

Path
idinteger(int64)required

The unique identifier for the entity.

curl -i -X POST \
  'https://your-server/api/entities/{id}/lifecycle/restore' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Entity restored successfully from archive

Restore an entity from the deleted state

Request

Restores an entity that has been soft deleted. Hard deleted entities cannot be restored. Requires the Delete permission.

Path
idinteger(int64)required

The unique identifier for the entity.

curl -i -X POST \
  'https://your-server/api/entities/{id}/lifecycle/restorefromdelete' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Entity restored successfully from deletion

Soft delete an entity

Request

Deletes an entity, marking it as deleted but without permanently removing it from the system (soft deletion). This action can be reversed by restoring the entity later. Requires the Delete permission.

Path
idinteger(int64)required

The unique identifier for the entity.

curl -i -X POST \
  'https://your-server/api/entities/{id}/lifecycle/softdeleteentity' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Entity soft deleted successfully