> ## Documentation Index
> Fetch the complete documentation index at: https://ekso.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# DataAnnotation

> Append-only annotation attached to an item, container, or another annotation.

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.

```json theme={null}
{
  "owner": "Item",
  "ownerId": "item_01HITEM_LOGIN_BUG",
  "annotator": "Email",
  "annotatorId": "customer@acme.example.com",
  "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": "customer@acme.example.com"
    },
    {
      "key": "ekso_recipient_email_address",
      "value": "support@example.com"
    }
  ]
}
```

## Fields

| Field          | Type                                                    | Required     | Notes                                                                                                                                                                                      |
| -------------- | ------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `entity`       | string • nullable                                       | Server-set   | Set by the server. Read-only on writes.                                                                                                                                                    |
| `owner`        | [`ContentOwner`](/data-model/constants#content-owner)   | **Required** | Type of the entity this annotation hangs off. See [`ContentOwner`](/data-model/constants#content-owner) — usually `Item`; `Annotation` for replies on a thread.                            |
| `ownerId`      | string                                                  | **Required** | Id of the owning entity.                                                                                                                                                                   |
| `annotator`    | [`AnnotatorType`](/data-model/constants#annotator-type) | Optional     | Source of the annotation. See [`AnnotatorType`](/data-model/constants#annotator-type). 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](/cli/branches) page for available verbs. Body for create / update verbs typically passed via `--data @file.json` matching the [sample JSON](#sample-json) above.