List Cases

List all cases in your workspace with search and minimum-document count filters. Cases automatically group related documents that share linked identifiers.

A case is an automatically discovered group of related documents, connected through shared identifiers in the document linking graph. When an invoice, a purchase order, and a delivery note carry the same vendor ID or PO number, the linking engine clusters them into one case for review. GET /v1/cases lists every case in your workspace with its label, document count, and stable key.

The list is served from the materialized case-synthesis rows — the system of record for case identity and curation. Each case is keyed on a stable UUID (id) that survives rebuilds, and carries a lifecycle status progressing discovered → confirmed → active → resolved (Closed). The label is your curated display name when one has been set, falling back to the LLM-narrated title, or null when neither exists yet.

Filtering happens server-side. The search parameter matches case-insensitively against the label, narrated title, and blurb, so a query like acme finds every Acme-related case regardless of how it was named. min_documents drops cases below a document-count threshold — useful for hiding trivial one- or two-document groupings from a review dashboard. Only fresh cases are returned: cases marked stale by an in-progress rebuild are excluded from the list.

Results respect document visibility. When your API key is restricted by Sources IAM rules, document_count is recomputed over the documents the key is allowed to see, and a case whose member documents are all hidden is dropped from the response entirely. Two callers with different visibility can therefore see different counts for the same case, and the platform view (which may run under broader access) can show more.

• Filter by search for a case-insensitive match on the case label, title, and blurb.
• Use min_documents to exclude trivial single-document cases.
• Cases are created automatically by document linking: there is no manual create endpoint.

curl "https://api.talonic.com/v1/cases?min_documents=2" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

curl "https://api.talonic.com/v1/cases?search=acme&min_documents=3" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

Response

{
  "data": [
    {
      "id": "5c7fa78c-4d92-4613-9f42-9fe74458d8a9",
      "case_key": "8c1ca050535e3ea3",
      "label": "Acme Corp Q4 Invoices",
      "status": "discovered",
      "document_count": 5,
      "created_at": "2024-10-01T08:30:00.000Z",
      "links": {
        "self": "/v1/cases/5c7fa78c-4d92-4613-9f42-9fe74458d8a9"
      }
    }
  ]
}

Errors