Lists API

GET /lists

List Lists

Parameters

Responses

Example

curl -X GET http://localhost:8000/lists \
  -H "Authorization: Bearer $TOKEN"

POST /lists

Create List

Request body

Responses

Example

curl -X POST http://localhost:8000/lists \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

POST /lists/audit

Create Audit List

Create a location-bound audit as a DRAFT manifest pre-seeded with the location's physical items. The manifest is reviewed/extended in draft (scan adds more); Finalize freezes each line's on-hand snapshot, then counting happens in the finalized stage.

Request body

Responses

Example

curl -X POST http://localhost:8000/lists/audit \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

GET /lists/export/csv

Export Lists Csv

Parameters

Responses

Example

curl -X GET http://localhost:8000/lists/export/csv \
  -H "Authorization: Bearer $TOKEN"

POST /lists/import

Import List

Request body

Responses

Example

curl -X POST http://localhost:8000/lists/import \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

POST /lists/import/batch

Batch Import Lists

Request body

Responses

Example

curl -X POST http://localhost:8000/lists/import/batch \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

GET /lists/summary

Get List Summary

Responses

Example

curl -X GET http://localhost:8000/lists/summary \
  -H "Authorization: Bearer $TOKEN"

POST /lists/writeoff

Create Writeoff List

Create a write-off list as a DRAFT seeded from the selected inventory items - the entry point for the inventory Write off bulk action. Each seeded line carries the item's on-hand quantity and blank qty_out/account/comment for on-page entry; Finalize locks it, then the Write off stock terminal removes the stock and posts one JE. Mirrors create_audit_list, but the seed source is the selection, not a location scan.

Request body

Responses

Example

curl -X POST http://localhost:8000/lists/writeoff \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

GET /lists/{entity_id}

Get List

Parameters

Responses

Example

curl -X GET http://localhost:8000/lists/:entity_id \
  -H "Authorization: Bearer $TOKEN"

PATCH /lists/{entity_id}

Patch List

Parameters

Request body

Responses

Example

curl -X PATCH http://localhost:8000/lists/:entity_id \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

DELETE /lists/{entity_id}

Delete List

Parameters

Responses

Example

curl -X DELETE http://localhost:8000/lists/:entity_id \
  -H "Authorization: Bearer $TOKEN"

POST /lists/{entity_id}/adjust

Adjust Audit

Audit terminal action: overwrite each counted line's item qty to its count (finalized -> closed). The magnitude and the shrinkage/overage JE are computed against the LIVE item qty at adjust time (decision 5.2) - `new_qty = counted`, `delta = counted - live`. Uncounted (blank) lines are skipped and reported. Reversible via undo-adjust.

Parameters

Responses

Example

curl -X POST http://localhost:8000/lists/:entity_id/adjust \
  -H "Authorization: Bearer $TOKEN"

POST /lists/{entity_id}/change-type

Change List Type

Change a list's type while it is a draft OR issued (finalized). The change is just another event in history, so everything the list did under its old type stays recorded; terminal/ financial actions are gated by status, so re-typing can't undo or fabricate past work. Type fields persist (nothing is zeroed). Switching a FINALIZED list to audit re-freezes the on-hand baseline that the audit's own finalize would have captured, so variance/Adjust stay correct. Closed/void lists are terminal - duplicate instead.

Parameters

Request body

Responses

Example

curl -X POST http://localhost:8000/lists/:entity_id/change-type \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

POST /lists/{entity_id}/convert

Convert List

Parameters

Request body

Responses

Example

curl -X POST http://localhost:8000/lists/:entity_id/convert \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

POST /lists/{entity_id}/duplicate

Duplicate List

Parameters

Responses

Example

curl -X POST http://localhost:8000/lists/:entity_id/duplicate \
  -H "Authorization: Bearer $TOKEN"

POST /lists/{entity_id}/finalize

Finalize List

Lock a draft list (draft -> finalized). The single draft->open transition for every type. Type-specific on-finalize (from the behaviour registry): a quotation records `sent_at`, a transfer `issued_at`, an audit freezes each line's on-hand snapshot (for variance + a stable On-hand column while counting). Counting / terminal actions happen in the finalized stage.

Parameters

Responses

Example

curl -X POST http://localhost:8000/lists/:entity_id/finalize \
  -H "Authorization: Bearer $TOKEN"

PATCH /lists/{entity_id}/line-page

Patch List Line Page

Save one page of a list's lines without scraping or re-sending the whole array. Under the same row lock and optimistic-version guard as a full save, the submitted page REPLACES the stored window [offset:offset+original_count] the client originally loaded. Relative to that window a shorter page truncates (deletes) tail rows and a longer one inserts; off-window rows are left byte-identical and totals are recomputed from the full merged array. Omitting original_count means the window is exactly the submitted page's own length (a pure in-place replace that never drops off-window rows), so a delete or insert must carry the loaded window length, which the editor always sends.

Parameters

Request body

Responses

Example

curl -X PATCH http://localhost:8000/lists/:entity_id/line-page \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

PATCH /lists/{entity_id}/line/{item_id}

Set Audit Count

Set a line's physical count. Editable only while the audit is finalized (counting stage).

Parameters

Request body

Responses

Example

curl -X PATCH http://localhost:8000/lists/:entity_id/line/:item_id \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

POST /lists/{entity_id}/move

Move Transfer

Transfer action: relocate every item on a finalized transfer to one location, by emitting the inventory `item.transferred` event per line (stock is owned by inventory; docs only emits the event). Repeatable - the transfer stays finalized so it can be moved again.

Parameters

Request body

Responses

Example

curl -X POST http://localhost:8000/lists/:entity_id/move \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

GET /lists/{entity_id}/notes

List List Notes

Parameters

Responses

Example

curl -X GET http://localhost:8000/lists/:entity_id/notes \
  -H "Authorization: Bearer $TOKEN"

POST /lists/{entity_id}/notes

Add List Note

Parameters

Request body

Responses

Example

curl -X POST http://localhost:8000/lists/:entity_id/notes \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

PATCH /lists/{entity_id}/notes/{note_id}

Update List Note

Parameters

Request body

Responses

Example

curl -X PATCH http://localhost:8000/lists/:entity_id/notes/:note_id \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

DELETE /lists/{entity_id}/notes/{note_id}

Delete List Note

Parameters

Responses

Example

curl -X DELETE http://localhost:8000/lists/:entity_id/notes/:note_id \
  -H "Authorization: Bearer $TOKEN"

GET /lists/{entity_id}/page

Get List Page

The list header (stored state without line_items), one bounded page of line_items, the total, and enriched item metadata for exactly the page's ids. Everything is read in bounded SQL: the header is `state - line_items` (never the whole document row), the total is json_array_length, the window is a positional json subscript over generate_series, and item_meta joins the page's catalog items only. The detail view renders the page and enriches it from this one call, so a large list is never expanded into Python and no follow-up metadata round-trip is needed.

Parameters

Responses

Example

curl -X GET http://localhost:8000/lists/:entity_id/page \
  -H "Authorization: Bearer $TOKEN"

POST /lists/{entity_id}/reserve-lines

Reserve List Lines

Set selected lines reserved/available on a draft or finalized list of any type (ledger-neutral).

Parameters

Request body

Responses

Example

curl -X POST http://localhost:8000/lists/:entity_id/reserve-lines \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

POST /lists/{entity_id}/revert-to-draft

Revert List To Draft

Go back from finalized to draft, allowed only before a terminal action has run (GDR 2c).

Parameters

Request body

Responses

Example

curl -X POST http://localhost:8000/lists/:entity_id/revert-to-draft \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

POST /lists/{entity_id}/scan

Scan List

One scan endpoint for every list type, dispatching on (list_type, status): - DRAFT (all types): always ADD a line (audit dedups its manifest + moves to top; money lists price the new line). No status change (GDR 2d) - building the list never finalizes it. - FINALIZED audit: record presence (audited_at), add + audit if not yet on the manifest. - FINALIZED transfer: scan-to-receive (records receipt on the line; the stock move is the Phase 4 seam). - FINALIZED quotation / any closed|void list: scanning is disabled (clear 409).

Parameters

Request body

Responses

Example

curl -X POST http://localhost:8000/lists/:entity_id/scan \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

POST /lists/{entity_id}/send

Send List

Record a finalized list as sent (sets the `sent_at` milestone; status stays finalized) and, if a recipient is given, fire the relay email - the same Send / Mark-as-sent mechanism documents use. `sent_via="manual"` (no recipient) is the Mark-as-sent path.

Parameters

Request body

Responses

Example

curl -X POST http://localhost:8000/lists/:entity_id/send \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

POST /lists/{entity_id}/set-scanned

Set Scanned

Toggle the scanned/accounted-for highlight (audited_at) on audit lines. scanned=True marks the rows as scanned (stamps audited_at), scanned=False clears it. Pass item_ids to target specific rows, or none for every line. The highlight otherwise persists indefinitely.

Parameters

Request body

Responses

Example

curl -X POST http://localhost:8000/lists/:entity_id/set-scanned \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

POST /lists/{entity_id}/undo-adjust

Undo Audit Adjust

Reverse the last stock adjustment (manager/owner): restore each item's prior quantity and void the audit JE. Reopens the audit (closed -> finalized) so it can be re-counted or re-adjusted.

Parameters

Responses

Example

curl -X POST http://localhost:8000/lists/:entity_id/undo-adjust \
  -H "Authorization: Bearer $TOKEN"

POST /lists/{entity_id}/undo-write-off

Undo Write Off

Reverse a write-off (manager): void its JE and restore each disposed lot to `available`. A carved child lot is NOT re-merged into its parent - it returns as its own available lot, so quantity is conserved (parent remainder + restored child = the original). Reopens the list (closed -> finalized) so it can be re-run.

Parameters

Responses

Example

curl -X POST http://localhost:8000/lists/:entity_id/undo-write-off \
  -H "Authorization: Bearer $TOKEN"

POST /lists/{entity_id}/unmark-sent

Unmark List Sent

Clear the sent milestone (the list stays finalized).

Parameters

Responses

Example

curl -X POST http://localhost:8000/lists/:entity_id/unmark-sent \
  -H "Authorization: Bearer $TOKEN"

POST /lists/{entity_id}/void

Void List

Parameters

Request body

Responses

Example

curl -X POST http://localhost:8000/lists/:entity_id/void \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

POST /lists/{entity_id}/write-off

Write Off Stock

Write-off terminal (manager): in one step, validate every intended line, remove each line's qty_out from stock and post one balanced JE (one debit per destination account against a single Inventory credit). Runs from a draft (finalized inline after validation) or a finalized list. A full-quantity line disposes the whole item row; a partial line carves a child lot via the shared split primitive and disposes that. Every disposed portion ends as a hidden `disposed` item - the permanent disposal record. Lines with no quantity entered are skipped and reported; a line with a quantity but an invalid account/item/quantity rejects the whole action. Reversible via undo-write-off.

Parameters

Responses

Example

curl -X POST http://localhost:8000/lists/:entity_id/write-off \
  -H "Authorization: Bearer $TOKEN"

POST /lists/{entity_id}/writeoff-line

Set Writeoff Line

Set (or append) a write-off line's quantity-out, destination account and comment, on-page while the list is a draft. Pass line_id to edit a seeded line, or item_id (no line_id) to add another line for an item already selectable on the list - the SAME item can be written off to two accounts (spoiled -> wastage, sampled -> marketing). qty_out and account are validated at the function level.

Parameters

Request body

Responses

Example

curl -X POST http://localhost:8000/lists/:entity_id/writeoff-line \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'