Brick Work API v2: contract

Status: the contract of the whole v2 surface, written for M.11a (issue #113, 2026-10-27). The transport, the meta endpoints and item addressing are implemented in M.11a, the reads in M.11b, the writes in M.11c and the orders, jobs, sources, sync, imports, identifications, tokens and admin operations in M.11d, and the MCP and the parity test in M.11e: every operation of the contract is implemented (a piece that has not landed answers 501 not_implemented, none is left). The machine-readable twin is openapi-v2.yaml; the data model behind it is data-model-design.md (sections 3.1, 3.2, 3.5, 3.6, 3.8 and 7).

How to read this file. v2 is v1 with the 4.0 identity, not a redesign (api-v1.md is the v1 contract and stays as the reference for what v2 inherits). Section 1 says what changed and what did not. Section 2 holds the conventions, section 3 the resource catalogue with every v1 operation mapped to its v2 operation (or dropped, with the reason), section 4 the pieces and the 501 list. Each operation carries the piece that implements it: M.11a the contract, transport, meta and item addressing; M.11b the reads; M.11c the writes; M.11d orders, jobs, sources, keys, sync, imports, identifications, tokens and admin; M.11e the MCP regenerated from this file and the parity test (no operations of its own).

1. What changed from v1, and what did not

v1 answers 410 Gone on the 4.0 line (its /health excepted) because it cannot represent local or unidentified items; the 410 text names /api/v2 and this file.

Unchanged (a client changes only how it names items): envelopes (data, page, write receipts), cursor pagination and the filter vocabulary, ETag / If-Match, Idempotency-Key, problem+json errors with stable codes, bearer tokens with the read < write < admin scopes, BW_API_TOKEN, the throttle on failed token checks, read-only instances, archive instead of delete, one event per write with via=api and actor = token name, and Undo through POST /events/{id}/undo. The code behind them is shared with v1 (brickwork/api/transport.py).

Changed:

Ids are per install (data model 3.1). A Brick Work id from one install means nothing in another, and a restore from a different archive can renumber. Clients store provider numbers and use ids only within a session.

2. Conventions

2.1 Identity and addressing

Number paths and /lookup (decisions 2 to 4 of #113):

• provider is bricklink (the default) or rebrickable. BrickLink is the default because every current client, order e-mail and the House API speak BrickLink numbers. A set number is the same at both providers, so a set is looked up at both and the answers merge.
• kind is set, part, minifigure, instructions, box, gear, book or catalog; the three number paths fix it. Rebrickable has numbers only for sets, parts and minifigures; another kind with provider=rebrickable is 422.
• A BrickLink number resolves through the item's links (every confirmed link: manual, matched, inferred) and through a BrickLink-born local item's own number. A Rebrickable number resolves through the born key.
• A BrickLink figure number the catalogue holds as a part (#150). BrickLink files the old Technic figures (tech028) as minifigures, where the catalogue links the same number to a Rebrickable part. With provider=bricklink and kind=minifigure, a number that no minifigure holds but exactly one part holds, as that very same BrickLink number, answers with the part (kind: part). A catalogue minifigure always wins; two parts keep the answer 404; no other number is tried. An order line or a BrickLink subsets list that names such a figure becomes a part line in no colour.
• Colour-scoped links. With color, the colour is read in the provider's space (bricklink: a BrickLink colour id, rebrickable: a Rebrickable colour id) and the lookup is the inverse of the resolution function (data model 3.2): a link scoped to that colour applies, an unscoped link applies only when the item has none scoped to the colour (the leg rule), and a manual link decides alone. The answer then carries data.color, the resolved Brick Work colour, so a client can map provider colours. Without color, a link of any scope matches.
• A BrickLink-born local item's own number is an unscoped claim that follows the same precedence: a manual link for the number decides alone, and the item does not answer by its born number in a colour it has a scoped link for. Across different items a colour-scoped link and an unscoped one both apply, so they are 409 ambiguous together.
• One match is 200 with the item body. Several is 409 ambiguous with candidates (item bodies) and the problem fields; none is 404. A merged item found by number is followed to its survivor silently.
• Unknown query names are 400 unknown_filter. A colour that names no colour, or a bad kind or provider, is 422 validation_failed.

Colours in a request are in the provider's space (decision 4): a BrickLink colour id with provider=bricklink, a Rebrickable colour id with provider=rebrickable, and a Brick Work colour id with provider=brickwork. The brickwork space is for paths that already name the item by id (/items/{id}/...); on a number path it is 422, since a Brick Work id is not a number.

Item and colour bodies (data model 7):

{"id": 15011, "kind": "set", "name": "...", "unidentified": false,
 "bricklink": [{"type": "S", "no": "6081-1", "color_id": null, "color_scoped": false, "brickwork_color_id": null, "preferred": true}],
 "rebrickable": {"key": "6081-1"}}

bricklink lists the confirmed BrickLink links, preferred first; a colour-scoped link names its BrickLink colour in color_id and has color_scoped: true, an unscoped one has color_id: null and color_scoped: false. A link scoped to a colour that has no BrickLink id also reads color_id: null, but with color_scoped: true: it never reads as "every colour", and brickwork_color_id (set exactly when color_scoped) names the scope in Brick Work's own space. (color_scoped and brickwork_color_id are additions to the design 7 shape, made for this case.) A BrickLink-born local item with no link of its own lists its born number. rebrickable is the born key or null. unidentified is true for a local item that is not born at Rebrickable (data model 3.8): no born key, or a BrickLink-only number. Every field of a row that names an item (item, child, parent_minifig, part, figure) carries this body, and every colour (color) the colour body {id, name, rgb, bricklink_id, rebrickable_id}.

Merged ids (decision 5, amended 2026-10-27):

• GET of a merged id (any /items/{id}... path) answers 307 Temporary Redirect with Location to the same path under the survivor (the query string is kept), Cache-Control: no-store and a problem body (code: moved, survivor).
• This deviates from data model 3.6 and 7, which say 301. A merge can be undone exactly (unmerge restores every moved row), and a cached permanent 301 would keep sending the unmerged id to the old survivor. 307 also keeps the method, though only GET redirects.
• Resolving an id and serialising its item are one read snapshot, so a merge that commits in between never mixes two states in one answer.
• A write that names a merged id is 409 merged with survivor; nothing is written, since a client that silently writes to a moved id would surprise. POST /items/{id}/unmerge is the one write that names a merged id on purpose.

2.2 Value formats

As v1: money is a decimal string with a currency code ^[A-Z]{3,8}$; time is ISO-8601 UTC with offset; dates the user types are stored as given. Stored words are served as stored (Q8): conditions new, used (stock adds damaged; wishes new, used, any), completeness sealed, complete, incomplete with completeness_source manual or derived, kinds as above. The v1 code-to-word mappings are gone because nothing is stored as a letter any more.

2.3 Envelopes

• Single read: {"data": {...}} with ETag on copies, stock and wishes.
• List: {"data": [...], "page": {"next_cursor": "...|null", "limit": 50, "total": 123|null}}.
• Write: {"data": {...}, "event_id": 412, "undo_url": "/api/v2/events/412/undo", "idempotent_replay": false}.
• Queued work: 202 Accepted, the write envelope with the Job as data, header Location: /api/v2/jobs/{id}.
• Every response of the API carries Cache-Control: no-store.

2.4 Resource states

As v1: archived rows are hidden from lists (archived=true|include|only), a GET of an archived record returns it with archived_at, writes to one fail with 409 archived.

2.5 Pagination, filters, sort

As v1: opaque cursor, limit 1 to 200 (default 50), sort and direction with a stable tie-break, unknown filter names are 400 unknown_filter. The filters that named an item by BrickLink type and number change: item_type becomes kind, item_no becomes number with provider, and color_id / colour become color (in the provider space, default bricklink; provider=brickwork takes a Brick Work colour id). type on GET /items is kind.

2.6 ETag and If-Match

As v1: copies, stock and wishes carry an ETag; PATCH, PUT and DELETE accept If-Match; a mismatch is 412 precondition_failed and nothing is written. POST /copies/{id}/inventory accepts If-Match as well, since a switch rewrites the copy's lines.

2.7 Idempotency

As v1: Idempotency-Key: <1 to 80 characters of [A-Za-z0-9-]>, stored in the one event row of the request; same key and body replays the stored response (idempotent_replay: true), another body is 409 idempotency_conflict, a key is honoured for 30 days. Fingerprint version: the request fingerprint (method, path, sorted query, body, file hash) carries a version v (now 1), and the receipt stores the version it was made under; a replay is compared under the receipt's own version, so a later change to what is hashed bumps v and old receipts keep replaying. Required on: creates (POST /copies, /stock, /wishes, /found, /stock/booklets, /lots, /wishlists) and the wishlist edits (PATCH and DELETE /wishlists/{id}, POST /wishlists/{id}/restore and /transfer), quantity moves (/copies/{id}/take, /stock/{id}/give, /wishes/{id}/to-owned, /storages/{id}/contents, /copies/{id}/parts/bulk), orders (/orders/documents, /orders/{id}/allocate, /orders/{id}/allocations/retry), prices (/prices/observations, /items/{id}/prices), /events/{id}/undo, and the v2 identity writes (PUT /items/{id}/links, POST /items/{id}/merge, POST /items/{id}/unmerge, POST /items/{id}/change-variant, POST /copies/{id}/inventory). A missing key is 428 idempotency_key_required. Optional elsewhere.

2.8 Errors

Media type application/problem+json, as v1:

{"type":"urn:brickwork:error:ambiguous","title":"Ambiguous","status":409,"code":"ambiguous",
 "detail":"bricklink part 3001 names 2 items; address one by id",
 "candidates":[{"id":44280,"kind":"part","name":"...","unidentified":false,"bricklink":[],"rebrickable":{"key":"3001"}}],
 "instance":"/api/v2/parts/by-number/3001"}

Optional members: retry_after, job_id, source, and in v2 candidates (with ambiguous), survivor (with merged and moved), piece and error (with not_implemented). Codes and statuses are in Appendix A; x-error-status in the OpenAPI file lists the same table. A path under /api/v2 that does not exist is 404 not_found and a wrong method 405 method_not_allowed with Allow, both problem+json.

2.9 Authentication, scopes, tokens

As v1: Authorization: Bearer <token>; read < write < admin; BW_API_TOKEN is a bootstrap admin token named bootstrap; stored tokens are hashed, scoped and may expire; with neither, 503 api_disabled. /health and /openapi.yaml need no token. BW_READ_ONLY makes every non-GET 403 read_only_instance whatever the scope. Failed token checks back off per client (429 too_many_attempts, Retry-After); forwarded addresses count only with BW_TRUSTED_PROXIES. The scope of every v2 operation is the one its security entry in openapi-v2.yaml names; the blueprint reads it from there, so the contract is the single place that says who may call what. Request bodies are refused unread over their cap (JSON 4 MB, uploads per route) with 413 payload_too_large.

2.10 Reads (M.11b) and writes (M.11c)

What the 60 read operations (M.11b) and the 67 write operations (M.11c, further down) do beyond v1, and where the first contract text changed when they were built (each is also in openapi-v2.yaml).

• The query is the contract's. A query name an operation does not declare is 400 unknown_filter, a name given twice is 400 bad_request unless the contract declares it an array (copy_id on the exports). limit, direction, cursor and sort are accepted where the operation lists them.
• Filters on an item or colour take the provider space of decision 4: number (with provider, bricklink by default, rebrickable) finds the live items that number stands for in any kind, or in kind; color is read in the same provider space, and provider=brickwork is for color only (a Brick Work id is not a number: number with it is 422). A filter that names nothing is an empty list; a colour that does not exist is 422.
• Lists are filtered and sorted over the rows the screens use, and paged with the cursor of v1: it holds the sort position, never an offset, so rows that arrive meanwhile never move a page. page.total is the exact count of the filtered rows (v1 left it null under q and archived); the SQL-paged histories (/events, /items/{id}/prices/history) give total: null (a long log is paged by its key, never counted), and /catalogue/items is paged in SQL with the exact count of the entries that match. archived=true|include|only as before; status=unknown is a copy with no recorded completeness; storage, place, lot take null for none.
• Rows that name an item or a colour carry the bodies of section 2.1, built for a whole page in a fixed number of queries. The tie-break of every sort is the row's key, so a page is stable.
• etag is in the body of a copy, stock line or wish on lists and single reads; the ETag header is on the single read. It is a hash of the stored row and its flag ids, so a change of the item's name does not move it.
• A merged id is 307 on every /items/{id}/... path and on GET /minifigures/{id}; the Location keeps the rest of the path and the query.
• Corrections to the first contract text, found by validating every answer against it: the id of an Image is the picture number or the 32-character hex id of an own photo (/images/{id}/content takes either); Lot.created_date is created_at; StaleItem.source_table is copy, stock or wish (the 4.0 tables); ItemLink says color_scoped and brickwork_color_id as the item body does; ItemDetail also carries used_in, gaps and matches; the unpriced lines of a copy's part-out value are {item, color}; GET /export/missing.json names its lines by item and colour body with the BrickLink type, number and colour number beside them, and lists the lines the XML must leave out under skipped; GET /wishlists pages like every list; the virtual location "Not stored" has the id unstored (null stays the filter spelling); has_file on GET /instruction-files is whether the PDF is on disk.
• Gaps of a missing booklet or box name the copy's set as their item (target instructions or box, target_id the copy id); every other gap names the item that is missing.
• The catalogue is the attached catalogue.db, not v1's BrickLink file. GET /catalogue/items finds a text by number (the Rebrickable number, then any linked BrickLink number) and by name; without the file the answer is 424 catalogue_not_loaded.

Writes (M.11c). Every write calls the core writer that owns the change, in one transaction with its answer; a write that has no core writer got one beside the code it belongs to (checker.mark, checker.set_checked, checker.mark_stock_parts, admin.attach_instruction, the colour scope of identity_admin.add_link, the BrickLink preference in admin.patch_settings).

• The request is checked against brickwork/api2/write_contract.json, generated from openapi-v2.yaml by python -m scripts.generate_api_writes (the gate fails when it differs). An object that lists properties is closed: an unknown member, a wrong type, a value out of its enum, pattern or range is 422 validation_failed naming the member; wrong media type is 415, a body that is not a JSON object 400, a query name the operation does not declare 400 unknown_filter. The Idempotency-Key is read after the body, so a malformed body is 422 before a missing key is 428.
• An item in a body is an ItemKey: by id (a merged id is 409 merged with the survivor) or by provider, kind and key (bricklink unless named). A number that names no item, or an id that does not exist, is 422 unidentified; one that names several is 409 ambiguous with the candidates as item bodies; a kind Rebrickable has no numbers for is 422. A colour next to it is read in the provider's space of the key and in Brick Work's own space when the item is named by id. On a path that names the item (POST /items/{id}/prices) and on PATCH /wishes/{id} the colour is a Brick Work colour id.
• Creating goes through the Add flow (add.resolve, validate_edits, confirm), so an API copy has the part list the web would give it and its catalogue import is queued for the token that asked (the embedded worker is woken after the commit). decision is another (add although the set is owned or wished), skip or absent. Absent on something already owned or wished is 409 conflict; skip on it is 200 with {data: {skipped: true, existing: <the item's body>}, event_id: null} and writes nothing (the client asked for the skip, so it is an answer, not an error; changed in the follow-up to M.11c), skip on something new adds it (201). Loose stock merges into an identical line (the answer lists that line's id); POST /stock of a set and POST /copies of anything but a set are 422. A new wish for a list and an item and colour already wished adds to the wished quantity on decision=another.
• The envelope. event_id is the last event of the write that a registered undoer takes (else its last event), undo_url is that event's Undo (left out when nothing takes it). Undoing that event undoes the write whole: the undoable events the same request made before it, newest first, in one transaction (so Undo of POST /wishes/{id}/to-owned takes the copies away and puts the wish back). A preview (dry_run) and a write that changed nothing have event_id: null where the contract allows it (WrittenBulkResult, and, since M.11c, WrittenSettings and WrittenItemLink).
• Idempotency is stored as a bw_api event op:<key> in the transaction of the write, per token, for 30 days; a failed write leaves no record, so the same key can be sent again. The record is hidden from /events (no values). A preview stores nothing. The wishlist writes require the key as well (the contract says so; section 2.7 lists them since M.11c).
• If-Match is checked in the write's transaction, after the 404 and before 409 archived. A restore of a record that is not archived is 409; every write to an archived record is 409 archived.
• Marks of a copy's lines (PATCH /copies/{id}/parts/{part_id}, POST .../parts/bulk, PATCH .../figures/{item_id}, PUT .../checked) are one part_check event of the shape a check answer writes; Undo is refused (409 undo_blocked) when the lines changed after it, so marks are undone in the order they were made. Each count is bounded 0 to the line's quantity on its own. A figure's own parts are parts/{part_id} too and never change the set's derived completeness; a whole missing figure does. parts/bulk names the set's non-spare lines by item and colour: mode=set replaces missing, mode=add adds to it (over the quantity is 422, nothing written); a line that is not there, or a number that names no item or several, is listed under skipped with its field (items[n]) and code (not_found, unidentified, ambiguous); dry_run reports the same without writing. PATCH /stock/{id}/parts takes spare as 0 or 1 (null is 0); its event is a collection receipt over the loose figure's parts.
• POST /copies/{id}/check takes the checker's operation id from the Idempotency-Key (a random one without it) and answers the full CheckState, as GET does; a repeated operation answers from the checker's own receipt, which is then the event.
• Take, Give, Found, booklets answer a Receipt (event_id, message); Take of a whole minifigure with a colour is 422; a stock or gap that changed is 409 stale_match.
• Storages: DELETE of a storage that holds things, or that other storages sit in, is 409 conflict unless move_to_unstored=true (it never moves storages); the id unstored is the target of POST /storages/unstored/contents. Flags: the app's own status flags (system) are 409 to rename or archive. An archived place or flag keeps its references; restoring brings them back.
• PDFs. POST /instruction-files is multipart with item as JSON text ({"id": 15011}), label and file; the PDF belongs to a set, a booklet names the set with its number. A photo (POST /copies/{id}/photos, /stock/{id}/photos) is an image up to 15 MB; the copy's or line's image_id stays the cached picture, the own photo is in /items/{id}/images.
• Settings. GET /settings reads admin.settings; source_priority is {step: {kind or "*": [source ids]}} over pictures, metadata and market_price (a step that is sent replaces that step), prefer_bricklink_inventory is the global switch of design 4.4, candidate_sets_common_max (a whole number of 25 or more, default 300) is the most sets a part may be held by and still count in Lot Detective (#200). A key outside the whitelist is 422 unsupported_setting. Changing settings needs admin.
• Links, merge, unmerge. PUT /items/{id}/links makes sure the item has the BrickLink link as a manual one (a link to check is confirmed; one scoped to a colour is its own row, in the BrickLink colour space) and, with preferred: true, makes it the preferred one of its scope; the BrickLink type must be the item's. It is idempotent per (type, number, colour): putting what is there writes nothing. preferred: false means no change to the preference: a preference is replaced by marking another link preferred, never cleared to none (there is always a resolver order). POST /items/{id}/merge names the loser in the path and the survivor as an ItemKey; Merge.receipt is {event_id, counts}. POST /items/{id}/unmerge names the merged id in the path; merge_id is optional and must belong to it; an unmerge has no Undo (merge again). No M.11c operation writes provider status: a person resolves a to-check row by a link or a merge.
• Change variant (#151). POST /items/{id}/change-variant takes {"to": <ItemKey>} and names the old variant in the path; both are catalogue figures (or parts, or other items) of one kind, neither merged. Every owned row moves from the item in the path to to, keeping its id: loose stock, wishes, the figure lines of copies (a copy keeps its part list; a line that named a catalogue list to does not have becomes a migrated one) and the part lines of loose parts. BrickLink's number (the old item's preferred one, else the one link to check on to) becomes to's preferred manual link, and the old item's link of it becomes to_check; the old item is left as it is. VariantChange is {from, to, number, receipt: {event_id, counts}}. One event: its Undo (POST /events/{id}/undo) puts every row and link back, and is 409 once any of them changed. Refused with 409: a merged item on either side (merged with survivor), another kind, a set, the same item, a job in flight for either, a copy, loose figure or part list with a line for both items, a row holding a fetched part list of the old item, and a live stock row or wish that would meet a live one of to on its key (nothing is added up).
• Sets versus a pile of parts (#199). GET /planning/set-scores ranks the catalogue's sets by how much of a pile of loose parts each explains: give exactly one of lot, storage (with the storages inside it), loose=true or stock (repeated line ids), else 422; an unknown lot or storage is 404, a stock id that is not a live loose part or figure 422. limit (1 to 100, default 20), offset and detail (matched lines per set, 0 to 50, default 10) page and size the answer; the ranking is cached per catalogue build and input, so a later page is cheap. Each set carries evidence (the sum, over the lines it holds, of the rarity weight ln(N/df) times the covered share of the set's quantity), coverage (evidence over the set's own total weight), covered, complete and distinctive lines, the matched lines with the stock flags passed through (flags sums them per flag) and swaps (the same part in another colour or as an alternate mould, listed apart and in no number). It reads and writes nothing, so a read token may call it, and it is a GET: an arbitrary parts list goes through the Python service brickwork.core.set_scoring.score. The formula and the decisions are ADR 0026; the how-to for developers is the reference page Set scoring.
• Which sets came in this lot (#200). GET /lots/{id}/candidate-sets ranks the sets a lot may have come from with the engine of GET /planning/set-scores, read-only; an unknown lot is 404. score is 0 to 100: the set's evidence over the best candidate's, so the best set that passes the set filters scores 100; it is not a probability. reasons are sentences ("7 of 9 distinctive parts found", "2 printed parts only in this set"), distinctive_found_parts and distinctive_missing_parts list up to 20 distinctive parts each (held by at most 25 sets) with their picture (id, content_url of the newest local one, image_url of the catalogue). Filters: min_score, theme (a catalogue theme id or name, with its sub-themes; an unknown one is 422), year_from, year_to, parts_min, parts_max (the catalogue's part count), ignore_common (default true: lines held by more than candidate_sets_common_max sets are dropped before scoring) and limit (1 to 100, default 20) and offset, which page after the filters. A bad boolean is 400 unknown_filter, any other bad value 422. The rules and the code are in Set scoring.
• Value and gain (#57). GET /valuation (MCP tool get_valuation) answers copies (every live copy, in set-number order) and statistics (the Paid vs value figures of Statistics), all in the display currency of Settings. A copy has paid (its price paid, null with paid_reason no_price_paid for none or 0.00, or no_rate), worth (null with worth_reason no_quote or no_rate) and gain (worth minus paid, negative for a loss, with its whole percent of the price paid; null unless both are known). A money figure is {amount, currency, converted, rate, rate_as_of, original}: a converted one carries the rate used, its date and the amount as recorded, and a missing rate is a null figure with the reason, never a guess; two currencies never share a figure. worth_source is override (the copy's own value) or used or new (the sold average of its set, chosen as the Prices card chooses it, for the copy's condition and completeness; a new or sealed copy is priced new, one with a missing or damaged line has the incomplete-set discount taken off, as the set page does, worth_discount_pct), with worth_date (the day of the quote), worth_sales and worth_stale (the Prices card's rule). statistics counts only the copies that have both a price paid and a worth (comparable_copies; enough is three or more), so the gain compares like with like; without_price_paid, without_quote and without_rate count the rest apart, and by_theme and by_year list {label, paid, worth, gain, percent, copies} (a purchase year that is not recorded is Not recorded). GET /export/insurance.csv is the insurance report: every live copy, one row each, columns Set number, Name, Year, Condition, Completeness, Purchase date, Price paid, Price paid currency, Current value, Current value currency, Value source, Value date, Photos (the copy's own photos, a count) and Remarks; text cells are made safe for a spreadsheet. Both are read-only. The column set is a proposal until the Discussions say what insurers ask for.
• Stickers (#201). GET /lots/{id}/stock/{stock_id}/stickers lists the sets whose latest inventory holds the part line's part in its colour and a sticker sheet (a part of the category Stickers), with the sheet and its picture, and the line's sticker state (flagged, confirmed). POST /lots/{id}/stock/{stock_id}/sticker with set_item_id and sheet_item_id from that list confirms the choice (409 when the line has no Sticker flag, 422 for a pair that is not a candidate); DELETE on the same path is "Not a sticker": it removes the flag and stops counting a confirmation. Both are one undoable event, an unchanged state writes nothing (changed: false, event_id: null when there is no event) and the Idempotency-Key is optional. The candidate-sets answer lists each set's swaps. Filing with sticker: true is a Part Spotter (web) matter; the API sets the flag with PUT /stock/{id}/flags as before. See Set scoring for the evidence rule.
• The copy's part list. POST /copies/{id}/inventory takes source, version (Rebrickable; default the latest) and, new in M.11c, remember (also the set's preference for new copies, in the same event). BrickLink's list without a key is 424 source_not_configured; with no fetched list the answer is 202 with Location: /api/v2/jobs/{id} and the copy waits (inventory.pending); a copy already waiting, or already on that list, is 409. DELETE .../inventory/pending cancels the wait and puts back the preference it remembered.
• Refusals of the 4.0 store are problems: a state that does not allow the change (nothing to switch, a marked copy, a pending change, a refused merge) is 409, a missing catalogue 424, the rest 422; the words are the refusal's own with folders cut.
• Corrections to the first contract text of the writes: WishlistTransfer.ids are texts (wish ids are uuids); Settings.source_priority is nested as above; CopyInventorySwitch has remember; WrittenSettings.event_id and WrittenItemLink.event_id may be null; InstructionUpload.item is JSON text in the form; PriceCreate.color and WishPatch.color are Brick Work colour ids; LooseFigurePartKey.spare null reads as 0.

Orders, jobs, sources, sync, imports, identifications, tokens and admin (M.11d). What the 57 remaining operations do beyond v1, and where the first contract text changed when they were built.

• Detached writes. A write that reaches the network (a key test, a connect, the ECB feed, a pulled order, a sync plan or send, a photo identification, the catalogue import, a drain) or runs long (a BrickTracker plan) runs outside any transaction; the core writers open their own short ones, and the answer is stored in one more. A claim row (api:claim:<token>:<key>, 15 minutes) makes a second request with the same key while the first is out 409 idempotency_conflict; a call that fails stores no receipt and releases the claim, so the key can be sent again. A reply is replayed before any network call. An exhausted budget is 429 budget_exhausted (a remote throttle 429 source_throttled) with Retry-After; a provider's reply that cannot be used is 502 source_error. Where a call changes nothing in the collection (a key test, a plan) event_id is null. An order imported by BrickLink number fetches first and imports in the transaction that stores the answer, so it is whole or not at all.
• A body whose members are all optional may be left out (POST /jobs/{id}/retry, POST /items/{id}/import, POST /items/{id}/prices/refresh): an empty body is {}. A body that holds key material or a password (PUT /sources/{source}/key, PUT /sources/{source}/user, POST .../user/connect) is fingerprinted with the keyed digest, never a plain hash, and needs BW_SECRET_KEY.
• POST /colors/sync is dropped (section 3.3): the BrickLink colour table comes with the catalogue builds since M.8f. POST /catalogue/import loads the newest folder of BrickLink item lists beside the collection and reconciles (the page's Load lists) and answers CatalogueStatus as the 4.0 catalogue is: whether it is loaded, its items, the builds the collection activated, the link coverage per status and the last reconcile.
• Orders. Order carries the counts and phase the Orders page shows (lines, pieces, received, allocated, held). OrderLine names its item and colour as the bodies of section 2.1 (null while the importer could not place it, and then unplaced_reason says why in words, null when placed; raw holds the provider's words and suggestions the items the line could be, best first: the ones a name that matches several items names, or, for a name no item has exactly, the nearest names of the loaded BrickLink item list, a longest-prefix match first and then names that hold all its words (#155); a suggestion is never placed by itself). A match names the item as an ItemKey and the colour in its provider space (color); a part needs its colour. A BrickLink number that no item holds but the loaded BrickLink item list names (an instruction booklet, a BrickLink-only part) becomes a local BrickLink-born item, at import and when matched by number (#154); an import's Undo leaves that item, unused. A line or document that is not in the order is 404; the core's refusals (a stale count, a gap that changed, a document in the wrong phase) are 422. GET /orders/{id}/allocations lists Allocation as the 4.0 table has it (target_type, copy_id, stock_id, item, color, intent_before, intent_after, target_label, undo_event_id); .../allocation-review the saved lines with what is available and the gaps they could fill (destinations); .../history the order's saves from the event log with via and actor. short.xml and export.csv are downloads. Every order write is one orders:<id> event and its Undo restores the order rows.
• Jobs. Job is a row of job with its job_step rows (interrupted is a running job whose worker is gone). GET /jobs pages by id and takes state and failed. Retry and resume are for the pipeline jobs (kind: item); the two fetch kinds answer 404 there. Queueing answers 202 with Location: /api/v2/jobs/{id} when it made one job, else a JobList (POST /jobs/pictures, /jobs/instruction-identities; POST /prices/refresh answers 200). POST /jobs/pictures takes scope (missing or all), kinds and expected_count (the call is refused when the count has changed) and queues one pictures job per held item of those kinds that has none running, replacing v1's source and types. POST /items/{id}/import takes steps only; the sources of a step are the stored order of its kind. A price refresh of an item with an unfinished job answers that job.
• Sources and keys. Source.key is {configured, origin, saved_at} and nothing else. The user token or hash of the collection sync is the key store under <source>_user. Undo of a key save, a key removal and a source switch is admin's, as making them was.
• Sync and import. SyncPlan also carries remote and, for a send, state; ImportPlan lists unplaced lines (not unresolved); SyncApplied and ImportApplied also carry event_id. A plan applied twice is applied once (already_applied), whatever the key. A pull apply is a write-scope operation and so is its Undo; a send apply and an import apply are admin's, and an import's Undo is admin's. The uploaded database is streamed to a private file under the import folder (up to BW_IMPORT_MAX_MB, 200 by default) and deleted whatever happens.
• Identifications. A candidate is {item, score, name} with owned (#45) on the answer of the upload, which also lists the predictions that named no item or several under unresolved. A read of an archived identification returns it with archived_at (section 2.4, v1 hid it); DELETE of an archived one is 409. GET .../thumb is the 256 px JPEG.
• Tokens, exchange rates, database. A token's secret is in the answer of its creation only (the replay record keeps it out: a replay of the creation answers secret: null, so a lost answer means revoking the token and creating another); bootstrap is reserved and cannot be revoked. A rate is a decimal string per EUR; PUT with null removes a hand-entered one and the ECB feed keeps hand-entered rates. GET /database/check adds catalogue_integrity_check when a catalogue is attached. GET /database/export is a snapshot of the collection without the stored source keys and refuses (409) if a known secret would remain in it; it writes nothing.
• v1 answers 410 Gone and names v2 on every path but GET /health; its modules and route table are gone.

The MCP (M.11e). The MCP server reads openapi-v2.yaml and calls /api/v2; its 65 tools are the operations that carry x-mcp-tool: the 61 tools of v1 keep their names (decision 7) and get_set_by_number, get_part_by_number, get_minifigure_by_number and lookup_item are new. Its 8 resources are x-mcp.resources. How a client uses it is in mcp.md.

• A tool takes numbers, never a Brick Work item id. The contract marks the item-id path parameters x-mcp-item: true (/items/{id} for get_item, import_item, get_prices, record_price and refresh_price; item_id in /copies/{id}/figures/{item_id} for set_figure_missing) and the ItemKey schema x-mcp-item: key. A tool with a marked path parameter takes provider (bricklink by default, or rebrickable), kind and no instead, and the adapter calls GET /lookup?provider=&kind=&key= before the call and puts the id into the path. A tool whose body names an item (add_copies, add_stock, add_wish, take_for_gap) takes item as {provider, kind, key} and has no id member. The rule is read from the contract, not listed in the adapter.
• A lookup that fails is the tool's error, unchanged: 404 not_found, or 409 ambiguous with the candidates. Nothing is written then.
• On get_prices the provider is also the colour space of color (decision 4), so provider=rebrickable reads color as a Rebrickable colour id. Elsewhere color stays as the operation has it (record_price takes a Brick Work colour id, as POST /items/{id}/prices does).
• Collection records keep their ids (copy, stock line, wish, wishlist, storage, lot, event, job, order, plan, purchase location): a client takes them from the list tools. bricklink_id and bricklink_order_id are numbers of BrickLink and stay.
• Resources: brickwork://items/{provider}/{kind}/{no} is get_lookup (the contract maps the URI's variables to its query); the others are as in v1.
• Fixed in the contract: PATCH /copies/{id}/figures/{item_id} named the figure's parameter with the id of an item path, so two parameters were called id; it now uses Path_figure_item_id.

3. Resource catalogue

3.1 Summary

201 operations in all (M.11a 9, M.11b 64, M.11c 71, M.11d 57 by piece); v1 had 179 operations.

3.2 Operations

Scope none means no token. Every path is relative to /api/v2. The v1 column names the v1 operation the row replaces when its path changed, says same when the path is unchanged and NEW when v1 had no such operation. Write rows are one transaction plus one event; the receipt kinds and Undo dispatch per write group are v1's (api-v1.md section 4) and move to this file with M.11c.

Meta

Catalogue

Items

Identity

Images

Copies

Copy parts

Loose stock

Minifigures

Instructions

Prices

Wishlist

Storages

Lots

Places

Flags

Planning

Orders

Events

Jobs

Sources

Settings

part_list_grouping is a settings key: grouped (default), bricklink, or none. PATCH uses the same save and undo event as the Settings page. It changes the set detail list only.

Admin

Matching

Tokens

3.3 Dropped v1 operations

The ? item type and the item_type, item_no and color_id members are gone from every body (section 1). Nothing else in v1's 179 operations is dropped: 175 are carried (13 of them with a changed path, the rest on the same path with changed bodies where they named an item).

4. Pieces and what is implemented

Operations by piece: M.11a 9, M.11b 64, M.11c 71, M.11d 57 (201 in all). The two tables below are generated from the contract and the routes by scripts/check_api_contract.py --write, and that check (run by scripts/check.sh) fails when the contract, the routes or these tables disagree. A piece lands by adding itself to brickwork.api2.DONE.

Implemented

Not implemented yet (answer 501)

501 not_implemented with a problem body that also carries {"error": "not_implemented", "piece": "M.11x"}. Authentication, scope and read-only come first, so a client without the right token still sees 401 or 403.

5. Decisions

Decided by brick-works under Ulf's delegation on #113 (2026-10-27); design section 7 is the approved frame.

1. v2 is v1's resource set with the 4.0 identity, not a redesign.
2. /items/{id} is canonical; the number paths and /lookup answer 200 with the same item body.
3. The default provider for numbers is bricklink (parts, minifigures); provider=rebrickable for Rebrickable numbers; a set number is the same in both. Several matches are 409 ambiguous, none 404, 422 unidentified on create.
4. Colours in a request are in the provider's space.
5. A merged id answers 307 on GET (amended from 301, section 2.1) and 409 merged on writes.
6. Wish ids are uuids; stored words are served.
7. The MCP keeps its tool names; its tools take numbers and a provider, never a Brick Work id.

Choices M.11a made where the scope comment and design section 7 were silent:

• GET /items/{id} returns exactly the section 7 item body. v1's item detail (properties, counts, copies, stock, wishes, prices) moves to GET /items/{id}/detail (M.11b), with links where v1 had matches.
• /minifigures/{id} (M.11b) is v1's figure aggregate (sets, loose lines, missing, matches, prices) by Brick Work id; the item body of a figure by number is /minifigures/by-number/{no}.
• provider=brickwork is for colours on id paths only; on number paths and /lookup it is 422.
• A lookup given color answers data.color next to the item fields.
• GET /items/{id}/provider-status is read-only: reconcile writes item_provider_status; a person resolves a to-check row by adding a link or merging.
• PUT /items/{id}/links sets one manual link or makes one preferred for its colour scope; there is no link delete (Undo reverses a mistake).
• POST /items/{id}/merge takes {"survivor": <item key>} and names the merged item in the path; POST /items/{id}/unmerge names the merged id in the path and an optional merge_id.
• GET /settings is implemented with the settings writes (M.11c), not with the reads.
• Undo (POST /events/{id}/undo) is a write and belongs to M.11c.

Appendix A: error codes