Skip to main content
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

FieldTypeRequiredNotes
entitystring • nullableServer-setSet by the server. Read-only on writes.
ownerContentOwnerRequiredType of the entity this annotation hangs off. See ContentOwner — usually Item; Annotation for replies on a thread.
ownerIdstringRequiredId of the owning entity.
annotatorAnnotatorTypeOptionalSource of the annotation. See AnnotatorType. Common values: User (in-app comment), Email (inbound ticket email), System (automation rule).
annotatorIdstringRequiredIdentifier for the annotator. User id when annotator=User; sender email address when annotator=Email; rule id when annotator=System.
restrictedToarray<string>OptionalOptional ACL — list of user-group ids allowed to read this annotation. Empty array means inherits the owning entity’s read permissions.
contentTypestringOptionalFormat of content. The set of accepted values is tenant-configurable — fetch via GET /api/annotation/list-supported. Common: Text, Markdown, Html.
contentstringOptionalThe annotation body itself. Plain text, markdown, or HTML depending on contentType.
metaarray<{ key: string, value: string }>OptionalFree-form key/value metadata. The ticketing pipeline uses this for ekso_mailbox_id / ekso_ticketing_id cross-references on inbound emails.
tenantIdstringServer-setSet by the server. Read-only on writes.
idstringServer-setSet by the server. Read-only on writes.
createdstring (date-time)Server-setSet by the server. Read-only on writes.
createdBystringServer-setSet by the server. Read-only on writes.
updatedstring (date-time)Server-setSet by the server. Read-only on writes.
updatedBystringServer-setSet by the server. Read-only on writes.
deletedbooleanServer-setSet 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.