Cases

A case is a unit of investigative or operational Work that a human (or a workflow acting on their behalf) owns from creation to resolution. Where a work assignment is the routing decision — which analyst, queue, or agent (the Worker) should pick something up — a case is the durable record that decision attaches to: it carries status, priority, severity, a comment thread, tasks, attachments, an audit timeline, and links to the tenant data rows it concerns.

This page is the entity-and-lifecycle surface. The assignment substrate that decides who a case goes to (least-loaded selection, escalation workers, the human_loop workflow step) is documented in Work strategies — this page does not re-explain it. Everything here belongs to the Cases tag under /api/cases.

The case object

The lifecycle

A case moves through a fixed set of statuses. Transitions are validated against a per-tenant transition graph — an illegal jump (say, new straight to resolved) is rejected with a conflict rather than silently applied. closed is the only terminal status; a resolved case can still be reopened to in_progress.

1. Create

CreateCase — POST /api/cases (case:write) — opens a case in a queue. summary and queue_id are required; priority and severity default when omitted. A new case starts at status new and emits a created event.

curl -s -X POST https://api.ductor.io/api/cases \
  -H "Authorization: Bearer $DUCTOR_TOKEN" \
  -H "X-Tenant-ID: $DUCTOR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Suspicious login from new geo",
    "description": "Multiple failed logins followed by a success.",
    "priority": "CASE_PRIORITY_HIGH",
    "severity": "CASE_SEVERITY_MEDIUM",
    "queue_id": "tier1-triage",
    "tags": ["auth", "geo-anomaly"]
  }'

2. Assign or claim

Two paths move a case from a queue to an owner:

• AssignCase — POST /api/cases/{case_id}/assign (case:write) — a lead assigns the case to a specific assignee_id.
• ClaimCase — POST /api/cases/{case_id}/claim (case:write) — an analyst pulls the case from a queue_id, assigning it to themselves.

# Lead assigns explicitly:
curl -s -X POST https://api.ductor.io/api/cases/$CASE_ID/assign \
  -H "Authorization: Bearer $DUCTOR_TOKEN" \
  -H "X-Tenant-ID: $DUCTOR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{ "case_id": "'"$CASE_ID"'", "assignee_id": "analyst-42" }'

# ...or an analyst claims from the queue:
curl -s -X POST https://api.ductor.io/api/cases/$CASE_ID/claim \
  -H "Authorization: Bearer $DUCTOR_TOKEN" \
  -H "X-Tenant-ID: $DUCTOR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{ "case_id": "'"$CASE_ID"'", "queue_id": "tier1-triage" }'

Both record an assigned event. For automatic assignment — least-loaded selection across a candidate set, or routing to an AI agent — the decision is made by the work-assignment substrate; see Work strategies.

3. Escalate

EscalateCase — POST /api/cases/{case_id}/escalate (case:write) — pushes a case into an active work state and records an escalated event with an optional reason. Escalation is idempotent per the case's escalated_at marker, so the escalation worker re-running does not double-fire.

curl -s -X POST https://api.ductor.io/api/cases/$CASE_ID/escalate \
  -H "Authorization: Bearer $DUCTOR_TOKEN" \
  -H "X-Tenant-ID: $DUCTOR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{ "case_id": "'"$CASE_ID"'", "reason": "SLA at risk" }'

4. Resolve or close

ResolveCase — POST /api/cases/{case_id}/resolve (case:write) — transitions a case to RESOLVED or CLOSED (any other target status is rejected), with an optional response_fields payload capturing the resolution.

curl -s -X POST https://api.ductor.io/api/cases/$CASE_ID/resolve \
  -H "Authorization: Bearer $DUCTOR_TOKEN" \
  -H "X-Tenant-ID: $DUCTOR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "case_id": "'"$CASE_ID"'",
    "status": "CASE_STATUS_RESOLVED",
    "response_fields": { "disposition": "false_positive" }
  }'

Freeform field edits (summary, priority, severity, status, queue, tags) go through UpdateCase — PUT /api/cases/{case_id} (case:write).

Sub-collections

Around the case aggregate sit five child collections. Each is addressed under the case and carries its own read/write scopes.

Comments

A threaded discussion log. AddComment — POST /api/cases/{case_id}/comments (case:write) — appends a markdown comment; supply parent_comment_id for a single-level reply. ListComments — GET .../comments (case:read) — paginates the thread. Each comment records its author_type — human, workflow, or system — so automated notes are distinguishable from analyst notes.

Tasks

Discrete, assignable work items inside a case. CreateCaseTask (POST .../tasks), UpdateCaseTask (PATCH .../tasks/{task_id}), and DeleteCaseTask (DELETE .../tasks/{task_id}) manage them; ListCaseTasks (GET .../tasks) returns them in display order. A task has its own status machine — todo → in_progress → {blocked, completed} with blocked → in_progress — and status changes are validated against it. completed is terminal.

Attachments

Binary files stored against a case. CreateCaseAttachment (POST .../attachments, case:write) uploads bytes inline (base64-encoded in JSON); the server writes them to the configured object store and keeps only metadata — filename, mime_type, size_bytes, storage_key, uploaded_by — on the case. GetCaseAttachment downloads one, ListCaseAttachments lists them, and DeleteCaseAttachment removes both the row and the underlying object. Uploads and deletions emit attachment_added / attachment_removed events.

Events (the timeline)

ListEvents — GET /api/cases/{case_id}/events (case:read) — returns the case's audit timeline: an append-only sequence of CaseEvent records, each with an event_type, an actor_id, a source_type (api, workflow, escalation_worker, or system), and field-level changes. The timeline is how you reconstruct exactly what happened to a case and who (or what) did it.

Table-row links

A case can point at the tenant data rows it concerns — hosts, assets, indicators, records. LinkTableRowToCase — POST .../table-row-links (case:write) — links a (table_ref, row_id) tuple; re-linking the same tuple is a no-op that returns the existing link. UnlinkTableRowFromCase (DELETE .../table-row-links/{link_id}) removes it. ListCaseTableRowLinks (GET .../table-row-links, case:read) returns them in link order.

Operations at a glance

List endpoints use cursor pagination (pagination.page_size up to 1000, default 50; pagination.page_token). ListCases additionally filters by status, priority, severity, queue_id, assignee_id, and tags.

Where to go next