Cases API

Create, manage, and comment on cases programmatically, and log time against them — with a pointer to the interactive API reference for the full spec.

Written By Erdinc Akay

Last updated 26 days ago

Cases API

The Cases API lets you create and manage cases programmatically — assign them to a user, link them to a device and customer, add comments, track every change in a built-in audit history, and log time spent as time entries.

Cases are addressed under the /api/tickets path — "ticket" is the platform's internal name for a case — and time entries under /api/time-entries.

Authentication and permissions

Every request needs a valid bearer token in the Authorization header — see API Authentication. Reading cases requires the tickets.view permission; creating, updating, commenting, and deleting them require tickets.manage. Time entries follow their own permission split — see Time entries below.

What you can do

  • List, search, and read cases, including their comments and audit history.
  • Create a case and assign it to a user, device, or customer.
  • Update a case — every change is recorded in its history automatically.
  • Add comments.
  • Delete a case (permanent — the case and its history cannot be recovered).
  • Log, link, annotate, and list time entries against a case.

Worth knowing before you call it

  • The linked device decides the customer. When a case is linked to a device, its customer is always taken from that device — any customer you send in the same request is ignored.
  • Updates wrap each value. Each updatable field is sent as { "hasValue": true, "value": … }; to leave a field unchanged, omit it entirely. Only wrapped fields are applied.
  • Status and priority are fixed sets — for example Open, InProgress, and Closed for status, and Low through Critical for priority.

Comments and audit history

Adding a comment requires the tickets.manage permission. Each comment is appended to the case's comments array and also recorded as a history entry.

Every case carries a history array (full case shape only) whose changeType tells you what happened: Created when the case was opened, FieldChanged for an edited field (with fieldName, oldValue, and newValue set), StatusChanged for a status transition, and Comment for an added comment.

Time entries

Time entries record effort against a case. They live under /api/time-entries, and a case keeps its tracked time as a separate collection of entries rather than a field on the case object. An entry can be linked to a device, to a case, or to both. An entry linked to a case with no device is a case-only entry. A few behaviours and validations are not visible in the schema:

  • Permissions split — creating a manual entry and listing a case's entries both require tickets.manage. Linking, updating the note, and deleting an entry are scoped to the user who owns the entry: the caller must be authenticated as that user.
  • Manual entries are created as Closed — and the end (endedAt) must be after the start (startedAt). Omitting assetId (or sending it as null) makes a case-only entry.
  • Note updates need an open entry — PUT /api/time-entries/{id}/note returns 410 Gone when the entry is already closed.
  • Unlinking keeps the entry — sending null to PUT /api/time-entries/{id}/ticket leaves the entry on its device but no longer counts it toward any case.
  • The for-case list returns totals — POST /api/time-entries/for-ticket returns { items, total, totalDurationSeconds }, where total is the entry count and totalDurationSeconds is the summed duration of all entries.

Fields worth knowing

The full case, comment, and time-entry objects are documented field-by-field in Swagger. A few fields carry meaning that is easy to miss:

  • status — a case is Open, InProgress, or Closed; a time entry is Open, Closed, or AutoClosed.
  • priority — one of Low, Medium, High, or Critical.
  • displayId vs ticketNumber — ticketNumber is the raw sequential number; displayId is its human-friendly form, such as #42.
  • createdBySystem — true when the case was opened automatically by octoja rather than by a user.
  • List shape vs full shape — the list endpoint omits description, comments, and history, and adds commentCount and lastCommentAt (the number of comments and the timestamp of the most recent one). Call GET /api/tickets/{id} for the full case.

Full endpoint reference

For the exact endpoints, query parameters, request bodies, and response fields — generated from the running platform, so it never goes out of date — use octoja's interactive API reference. See API Design Principles for how to open it.