DataAnnotation

Append-only annotation attached to an item, container, or another annotation. Annotations are the primitive for comments, audit-log entries, and inbound-email ticket conversations. Once created, annotations are intentionally not directly editable — they’re audit-trail-shaped.

Sample JSON

Copy, edit, paste. Server-set fields (id, created, tenantId, …) are omitted from the example — they’re populated by the server on response.

{
  "owner": "Item",
  "ownerId": "item_01HITEM_LOGIN_BUG",
  "annotator": "Email",
  "annotatorId": "[email protected]",
  "contentType": "Text",
  "content": "Hi support — our login flow has been timing out for the last 30 minutes. We're seeing 500 errors after about 30 seconds of inactivity.",
  "restrictedTo": [
    "group_01HGROUP_EVERYONE"
  ],
  "meta": [
    {
      "key": "ekso_mailbox_id",
      "value": "mailbox_01HMAILBOX_SUPPORT"
    },
    {
      "key": "ekso_ticketing_id",
      "value": "ticketing_01HTICKETING_HELP"
    },
    {
      "key": "ekso_sender_email_address",
      "value": "[email protected]"
    },
    {
      "key": "ekso_recipient_email_address",
      "value": "[email protected]"
    }
  ]
}

Fields

Field	Type	Required	Notes
`entity`	string • nullable	Server-set	Set by the server. Read-only on writes.
`owner`	`ContentOwner`	Required	Type of the entity this annotation hangs off. See `ContentOwner` — usually `Item`; `Annotation` for replies on a thread.
`ownerId`	string	Required	Id of the owning entity.
`annotator`	`AnnotatorType`	Optional	Source of the annotation. See `AnnotatorType`. Common values: `User` (in-app comment), `Email` (inbound ticket email), `System` (automation rule).
`annotatorId`	string	Required	Identifier for the annotator. User id when `annotator=User`; sender email address when `annotator=Email`; rule id when `annotator=System`.
`restrictedTo`	array<string>	Optional	Optional ACL — list of user-group ids allowed to read this annotation. Empty array means inherits the owning entity’s read permissions.
`contentType`	string	Optional	Format of `content`. The set of accepted values is tenant-configurable — fetch via `GET /api/annotation/list-supported`. Common: `Text`, `Markdown`, `Html`.
`content`	string	Optional	The annotation body itself. Plain text, markdown, or HTML depending on `contentType`.
`meta`	`array<{ key: string, value: string }>`	Optional	Free-form key/value metadata. The ticketing pipeline uses this for `ekso_mailbox_id` / `ekso_ticketing_id` cross-references on inbound emails.
`tenantId`	string	Server-set	Set by the server. Read-only on writes.
`id`	string	Server-set	Set by the server. Read-only on writes.
`created`	string (date-time)	Server-set	Set by the server. Read-only on writes.
`createdBy`	string	Server-set	Set by the server. Read-only on writes.
`updated`	string (date-time)	Server-set	Set by the server. Read-only on writes.
`updatedBy`	string	Server-set	Set by the server. Read-only on writes.
`deleted`	boolean	Server-set	Set by the server. Read-only on writes.

Used by

Request body

POST /api/annotation
POST /api/item/{itemId}/reply
PUT /api/annotation/{id}

Response body

GET /api/annotation/owner/{ownerId}
GET /api/annotation/{id}
POST /api/annotation

CLI

ekso annotation — see the command branches page for available verbs. Body for create / update verbs typically passed via --data @file.json matching the sample JSON above.

Reference

Core

Items

Process

Fields

Constraints & Rules

People & Access

Time & Finance

Knowledge

Mail & Tickets

Operational

Settings

Sample JSON

Fields

Used by

Request body

Response body

CLI

​Sample JSON

​Fields

​Used by

​Request body

​Response body

​CLI

Sample JSON

Fields

Used by

Request body

Response body

CLI