Skip to main content

Entries

Entries API helps you manage the content created in Codex. In this section of documentation you will find information about how Codex manages entries and how you can use them.

Schema​

Entries schema is generated based on the model fields and their respective configuration. Regardless of the model fields, each entry in Codex also contains some predefined fields. Below you can find the schema representation of one entry in Codex:

{
  "id": "id",
  "content": {},
  "system": {},
  "attrs": {},
  "references": []
}

Entry ID​

Entry ID is a unique identifier generated by Codex. It is usually a string containing only alphanumeric characters with a fixed length and starts with prefix "ce".

Entry Content​

The content object of the entry contains the values for all model fields the entry belongs to, with different data types based on field configurations.

Entry System​

Entry System is an object that contains common metadata about all entries. It contains the following fields:

title The title of the entry. This value is taken from the field configured to represent the title of the field.

siteId The site ID the entry belongs to.

modelId The model ID the entry belongs to.

modelAlias The model alias the entry belongs to.

externalId An external ID of the entry. This field is optional and is not generated by Codex. It has to be unique for a site.

versionId The version ID of the entry. This field is auto generated for each update of the entry. When you are updating the entry through Codex admin editor one version id is generated per session while many updates are performed as auto save.

metrics An object representing metrics about the entry. It contains atuomatically calculated metrics such as word count, characters count, sentences count, images count and reading time (calculated based on word count and the average word per minute reading time). The first three metrics apply for text, rich text and rich content field types, meanwhile the images count applies only for media field types.

labels The array of label id the entry belongs to.

status Status of the entry. Values are:

  1. PUBLISHED
  2. DELETED
  3. DRAFT
  4. UNPUBLISHED
  5. ARCHIVED
  6. SCHEDULED
  7. EDITED

publishedAt The publish date and time of the entry (in UTC).

unpublishedAt The unpublish date and time of the entry (in UTC).

firstPublishedAt The first publish date and time of the entry (in UTC).

createdAt The date and time when the entry was first created (in UTC).

updatedAt The date and time when the entry was updated for the last time (in UTC).

createdBy The ID of the user who created the entry.

updatedBy The ID of the user who updated the entry for the last time.

revisionId The revision ID of the entry. Is used for updating and conflict prevention.

Entry Attrs​

API only dynamic entry metadata placeholder. Can be used for different cusotm purposes on cases when you don't have to save these data on the content field.

Entry References​

An array of object representing metadata about entities that the entry is referncing to. It contains the entity type (entity) (which can be Entry, Asset, Section, Author etc..), model (model) in case the entry references another entry and the id (id) of the entity.

Entity type values are:

  1. ENTRY
  2. ASSET
  3. AUTHOR
  4. SECTION

A full example of entry object schema is:

{
  "id": "ceqBfhs1vz",
  "content": {},
  "system": {
    "title": "title",
    "siteId": "siteId",
    "modelId": "modelId",
    "modelAlias": "modelAlias",
    "externalId": "externalId",
    "versionId": "versionId",
    "metrics": {
      "wordCount": 1,
      "characterCount": 1,
      "sentenceCount": 1,
      "imageCount": 1,
      "readingTime": 1
    },
    "labels": [
      {
        "id": "lbSafTC3ta"
      }
    ],
    "status": 1,
    "publishedAt": "2022-11-06T19:33:08.119Z",
    "unpublishedAt": "2022-11-06T19:33:08.119Z",
    "firstPublishedAt": "2022-11-06T19:33:08.119Z",
    "createdAt": "2022-11-06T19:33:08.119Z",
    "updatedAt": "2022-11-06T19:33:08.119Z",
    "createdBy": "createdBy",
    "updatedBy": "updatedBy",
    "revisionId": "revisionId"
  },
  "attrs": {},
  "references": [
    {
      "id": "ceqBfhs1vz",
      "entity": 1,
      "model": "my_model"
    },
    {
      "id" : "asOM9vpcNaa25I1AK",
      "entity" : 2,
      "model" : null
    },
    {
      "id" : "atH8500EAQ",
      "entity" : 3,
      "model" : null
    },
    {
      "id" : "seFhwhITjA",
      "entity" : 3,
      "model" : null
    },
  ]
}

Updating entries​

Codex doesn't merge changes made to content, so when updating content, you need to send the entire body of an entry. If you update content with a subset of properties, you will lose all existing properties not included in that update.

You should always update resources in the following order:

  • Retrieve current entry.
  • Make changes to the entry.
  • Update the entry by passing the changed entry along with current revision id.

This way no unseen changes are overridden and unexpected conflicts are unlikely to occur.

Update locking​

Codex uses optimistic locking. When updating an existing entry, you need to specify its current revision with system revision id field. Codex compares this revision with the current revision stored to ensure that a client doesn't overwrite en entry that has since been updated. If the version changed in-between, Codex would reject the update.

Patch update entry​

Codex allows updating specific fields using the HTTP PATCH request method. The supported operations are add, remove, replace, move and copy. The examples below modify the /content part which is an object, using these operations.

add​

Adds a value to the specified location. If the target location specifies an array index, the value is inserted at that index. If the index is equal to the length of the array, the value is appended to the end of the array.

[
  {
    "op": "add",
    "path": "/content/multiplemedias/1",
    "value": {
      "id": "yourAssetId",
      "type": 1,
      "caption": null,
      "focalPoints": {
        "default": {
          "x": 0.5,
          "y": 0.5
        }
      }
    }
  }
]

This inserts image in the second position since indexes start from 0.

remove​

Removes the value at the specified location

[
  {
    "op": "remove",
    "path": "/content/text"
  }
]

replace​

Replaces the value at the specified location with a new value. This operation is identical to a "remove" operation for a value followed immediately by an "add" operation at the same location with the new value

[
  {
    "op": "replace",
    "path": "/content/title",
    "value": "New title"
  }
]

move​

Removes the value at a specified location and adds it to the target location. This is equivalent to performing a "remove" operation on the source location followed by an "add" operation at the target location with the value that was removed.

[
  {
    "op": "move",
    "from": "/content/oldLocation",
    "path": "/content/newLocation"
  }
]

copy​

Copies the value at a specified location to the target location. The value at the source location is not removed.

[
  {
    "op": "copy",
    "from": "/content/sourceLocation",
    "path": "/content/destinationLocation"
  }
]