API reference

operationId: get_wishlists
x-mcp-tool: get_wishlists
summary: get wishlists
description: The wishlists in their order (`sort`, name); `archived=true` includes
  the archived ones.
tags:
- Wishlist
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- name: archived
  in: query
  schema:
    type: boolean
- $ref: '#/components/parameters/Direction'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ListOfWishlist'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_wishlists
x-piece: M.11b

operationId: post_wishlists
x-mcp-tool: create_wishlist
summary: Create a wishlist
tags:
- Wishlist
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/IdempotencyKeyRequired'
responses:
  '201':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenWishlist'
  default:
    $ref: '#/components/responses/Problem'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/WishlistCreate'
x-v1: post_wishlists
x-piece: M.11c

operationId: patch_wishlists_by_id
x-mcp-tool: edit_wishlist
summary: Rename a wishlist or change its settings
tags:
- Wishlist
security:
- bearerAuth:
  - write
parameters:
- name: id
  in: path
  required: true
  schema:
    type: string
- $ref: '#/components/parameters/IdempotencyKeyRequired'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenWishlist'
  default:
    $ref: '#/components/responses/Problem'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/WishlistPatch'
x-v1: patch_wishlists_id
x-piece: M.11c

operationId: delete_wishlists_by_id
x-mcp-tool: archive_wishlist
summary: Archive a wishlist
tags:
- Wishlist
security:
- bearerAuth:
  - write
parameters:
- name: id
  in: path
  required: true
  schema:
    type: string
- $ref: '#/components/parameters/IdempotencyKeyRequired'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenWishlist'
  default:
    $ref: '#/components/responses/Problem'
x-v1: delete_wishlists_id
x-piece: M.11c

operationId: post_wishlists_by_id_restore
x-mcp-tool: restore_wishlist
summary: Restore an archived wishlist
tags:
- Wishlist
security:
- bearerAuth:
  - write
parameters:
- name: id
  in: path
  required: true
  schema:
    type: string
- $ref: '#/components/parameters/IdempotencyKeyRequired'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenWishlist'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_wishlists_id_restore
x-piece: M.11c

operationId: post_wishlists_by_id_transfer
x-mcp-tool: transfer_wishes
summary: Move or copy wishes into this wishlist
tags:
- Wishlist
security:
- bearerAuth:
  - write
parameters:
- name: id
  in: path
  required: true
  schema:
    type: string
- $ref: '#/components/parameters/IdempotencyKeyRequired'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenReceipt'
  default:
    $ref: '#/components/responses/Problem'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/WishlistTransfer'
x-v1: post_wishlists_id_transfer
x-piece: M.11c

operationId: get_wishlists_by_id_export_xml
x-mcp-tool: export_wishlist_xml
summary: Export wishlist as BrickLink wanted list XML
tags:
- Wishlist
security:
- bearerAuth:
  - read
parameters:
- name: id
  in: path
  required: true
  schema:
    type: string
- name: kind
  in: query
  schema:
    type: string
    enum:
    - sets
    - parts
    default: parts
- name: summary
  in: query
  schema:
    type: boolean
  description: Return content and download summary as JSON. id=all exports every active
    list.
responses:
  '200':
    description: OK
    content:
      application/xml:
        schema:
          type: string
      application/json:
        schema:
          type: object
  default:
    $ref: '#/components/responses/Problem'
x-v1: export_wishlist_xml
x-piece: M.11b

operationId: get_wishlists_by_id_export_csv
x-mcp-tool: export_wishlist_csv
summary: Export wishlist as Rebrickable CSV
tags:
- Wishlist
security:
- bearerAuth:
  - read
parameters:
- name: id
  in: path
  required: true
  schema:
    type: string
- name: kind
  in: query
  schema:
    type: string
    enum:
    - sets
    - parts
    default: parts
- name: summary
  in: query
  schema:
    type: boolean
  description: Return content and download summary as JSON. id=all exports every active
    list.
responses:
  '200':
    description: OK
    content:
      text/csv:
        schema:
          type: string
      application/json:
        schema:
          type: object
  default:
    $ref: '#/components/responses/Problem'
x-v1: export_wishlist_csv
x-piece: M.11b

operationId: get_health
summary: Liveness, schema and API version. No token.
tags:
- Meta
security: []
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/OneHealth'
  '503':
    $ref: '#/components/responses/Problem'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_health
x-piece: M.11a

operationId: get_version
summary: Build, API and schema versions, enabled features.
tags:
- Meta
security:
- bearerAuth:
  - read
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/OneVersion'
  '401':
    $ref: '#/components/responses/Unauthorized'
  '503':
    $ref: '#/components/responses/Problem'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_version
x-piece: M.11a

operationId: get_openapi_yaml
summary: This contract as OpenAPI 3.1 YAML. No token.
tags:
- Meta
security: []
responses:
  '200':
    description: File.
    content:
      application/yaml:
        schema:
          type: string
          format: binary
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_openapi_yaml
x-piece: M.11a

operationId: get_me
summary: 'The calling token: name, scopes, expiry.'
tags:
- Meta
security:
- bearerAuth:
  - read
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/OneMe'
  '401':
    $ref: '#/components/responses/Unauthorized'
  '503':
    $ref: '#/components/responses/Problem'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_me
x-piece: M.11a

operationId: get_catalogue_items
x-mcp-tool: search_catalogue
summary: Search the local BrickLink catalogue file by type and text.
tags:
- Catalogue
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Q_item_kind'
- $ref: '#/components/parameters/Q_q'
- $ref: '#/components/parameters/Q_sort'
- $ref: '#/components/parameters/Direction'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ListOfCatalogueItem'
  '424':
    $ref: '#/components/responses/DependencyFailed'
  '429':
    $ref: '#/components/responses/BudgetExhausted'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_catalogue_items
x-piece: M.11b

operationId: get_catalogue_items_by_id
summary: One catalogue entry.
tags:
- Catalogue
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Path_item_id'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/OneCatalogueItem'
  '404':
    $ref: '#/components/responses/NotFound'
  '424':
    $ref: '#/components/responses/DependencyFailed'
  '429':
    $ref: '#/components/responses/BudgetExhausted'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_catalogue_items_by_type_by_no
x-piece: M.11b

operationId: get_catalogue_status
summary: Catalogue file state (loaded, item counts, imported_at).
tags:
- Catalogue
security:
- bearerAuth:
  - read
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/OneCatalogueStatus'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_catalogue_status
x-piece: M.11b

operationId: get_colors
summary: All colours.
tags:
- Catalogue
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Q_q'
- $ref: '#/components/parameters/Direction'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ListOfColor'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_colors
x-piece: M.11b

operationId: get_colors_by_color_id
summary: One colour.
tags:
- Catalogue
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Path_color_id_int'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/OneColor'
  '404':
    $ref: '#/components/responses/NotFound'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_colors_by_color_id
x-piece: M.11b

operationId: get_items
summary: Items known to the store, with text search over name, number and properties.
tags:
- Items
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Q_item_kind'
- $ref: '#/components/parameters/Q_q'
- $ref: '#/components/parameters/Q_theme'
- $ref: '#/components/parameters/Q_category'
- $ref: '#/components/parameters/Q_year'
- $ref: '#/components/parameters/Q_owned'
- $ref: '#/components/parameters/Q_sort'
- $ref: '#/components/parameters/Direction'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ListOfItem'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_items
x-piece: M.11b

operationId: get_items_by_id
x-mcp-tool: get_item
summary: 'The item: its Brick Work id, kind, name, the BrickLink numbers it is known
  by and its Rebrickable key (design 7). A merged id answers 307 to the survivor.'
tags:
- Items
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Path_item_id'
responses:
  '200':
    description: The item.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/OneItem'
  '307':
    $ref: '#/components/responses/Moved'
  '404':
    $ref: '#/components/responses/NotFound'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_items_by_type_by_no
x-piece: M.11a

operationId: get_items_by_id_inventory
summary: Parts and figures the item is made of (inventory lines).
tags:
- Items
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Path_item_id'
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Direction'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ListOfInventoryLine'
  '307':
    $ref: '#/components/responses/Moved'
  '404':
    $ref: '#/components/responses/NotFound'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_items_by_type_by_no_inventory
x-piece: M.11b

operationId: get_items_by_id_used_in
summary: Owned copies that contain this part or figure.
tags:
- Items
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Path_item_id'
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Direction'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ListOfUsedIn'
  '307':
    $ref: '#/components/responses/Moved'
  '404':
    $ref: '#/components/responses/NotFound'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_items_by_type_by_no_used_in
x-piece: M.11b

operationId: get_items_by_id_colors
summary: Colours this part is known in.
tags:
- Items
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Path_item_id'
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Direction'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ListOfColor'
  '307':
    $ref: '#/components/responses/Moved'
  '404':
    $ref: '#/components/responses/NotFound'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_items_by_type_by_no_colors
x-piece: M.11b

operationId: get_items_by_id_images
summary: Local pictures of the item.
tags:
- Items
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Path_item_id'
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Direction'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ListOfImage'
  '307':
    $ref: '#/components/responses/Moved'
  '404':
    $ref: '#/components/responses/NotFound'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_items_by_type_by_no_images
x-piece: M.11b

operationId: post_items_by_id_import
x-mcp-tool: import_item
summary: Create the item identity and queue the six import steps.
tags:
- Items
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_item_id'
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/ImportRequest'
responses:
  '202':
    description: Accepted. The job runs in the background; poll GET /jobs/{id}.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenJob'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  '424':
    $ref: '#/components/responses/DependencyFailed'
  '429':
    $ref: '#/components/responses/BudgetExhausted'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_items_by_type_by_no_import
x-piece: M.11d

operationId: get_images_by_id_content
summary: Image bytes from the local picture store.
tags:
- Images
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Path_image_id'
responses:
  '200':
    description: File.
    content:
      image/*:
        schema:
          type: string
          format: binary
  '404':
    $ref: '#/components/responses/NotFound'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_images_by_id_content
x-piece: M.11b

operationId: get_copies
x-mcp-tool: list_copies
summary: Owned set copies.
tags:
- Copies
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Q_number'
- $ref: '#/components/parameters/Q_provider'
- $ref: '#/components/parameters/Q_condition'
- $ref: '#/components/parameters/Q_status'
- $ref: '#/components/parameters/Q_storage'
- $ref: '#/components/parameters/Q_place'
- $ref: '#/components/parameters/Q_flag'
- $ref: '#/components/parameters/Q_lot'
- $ref: '#/components/parameters/Q_problem'
- $ref: '#/components/parameters/Q_duplicates'
- $ref: '#/components/parameters/Q_theme'
- $ref: '#/components/parameters/Q_year'
- $ref: '#/components/parameters/Q_q'
- $ref: '#/components/parameters/Q_sort'
- $ref: '#/components/parameters/Q_archived'
- $ref: '#/components/parameters/Direction'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ListOfCopy'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_copies
x-piece: M.11b

operationId: post_copies
x-mcp-tool: add_copies
summary: Add owned copies of a set (quantity N makes N copies) and queue its import.
tags:
- Copies
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/IdempotencyKeyRequired'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/CopyCreate'
responses:
  '200':
    description: Skipped. The client asked for decision=skip and the item is already
      owned or wished; nothing was written, event_id is null.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenSkipped'
  '201':
    description: Written. One transaction, one events row.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenCreated'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_copies
x-piece: M.11c

operationId: get_copies_by_id
x-mcp-tool: get_copy
summary: One copy.
tags:
- Copies
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Path_id'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/OneCopy'
    headers:
      ETag:
        schema:
          type: string
  '404':
    $ref: '#/components/responses/NotFound'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_copies_by_id
x-piece: M.11b

operationId: patch_copies_by_id
x-mcp-tool: update_copy
summary: Edit condition, completeness, storage, purchase and estimate fields, note.
tags:
- Copies
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/IdempotencyKey'
- $ref: '#/components/parameters/IfMatch'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/CopyPatch'
responses:
  '200':
    description: Written. One transaction, one events row.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenCopy'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  '412':
    $ref: '#/components/responses/PreconditionFailed'
  default:
    $ref: '#/components/responses/Problem'
x-v1: patch_copies_by_id
x-piece: M.11c

operationId: delete_copies_by_id
x-mcp-tool: archive_copy
summary: Archive the copy (the UI calls this deleting a set).
tags:
- Copies
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/IdempotencyKey'
- $ref: '#/components/parameters/IfMatch'
responses:
  '200':
    description: Written. One transaction, one events row.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenCopy'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  '412':
    $ref: '#/components/responses/PreconditionFailed'
  default:
    $ref: '#/components/responses/Problem'
x-v1: delete_copies_by_id
x-piece: M.11c

operationId: post_copies_by_id_restore
summary: Clear the archive mark.
tags:
- Copies
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/IdempotencyKey'
responses:
  '200':
    description: Written. One transaction, one events row.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenCopy'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_copies_by_id_restore
x-piece: M.11c

operationId: put_copies_by_id_flags
summary: Replace the copy flags.
tags:
- Copies
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/FlagSet'
responses:
  '200':
    description: Written. One transaction, one events row.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenCopy'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: put_copies_by_id_flags
x-piece: M.11c

operationId: put_copies_by_id_pin
summary: Pin or unpin a copy.
tags:
- Copies
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/Pin'
responses:
  '200':
    description: Written. One transaction, one events row.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenCopy'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: put_copies_by_id_pin
x-piece: M.11c

operationId: get_copies_by_id_completeness
x-mcp-tool: get_copy_completeness
summary: Stored and derived completeness, checked flag, missing and damaged counts.
tags:
- Copies
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Path_id'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/OneCompleteness'
  '404':
    $ref: '#/components/responses/NotFound'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_copies_by_id_completeness
x-piece: M.11b

operationId: put_copies_by_id_checked
x-mcp-tool: set_copy_checked
summary: Set or clear the "Set is checked" flag and recompute derived completeness.
tags:
- Copies
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/Checked'
responses:
  '200':
    description: Written. One transaction, one events row.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenCompleteness'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: put_copies_by_id_checked
x-piece: M.11c

operationId: get_copies_by_id_check
summary: Part-check session state for this copy.
tags:
- Copies
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Path_id'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/OneCheckState'
  '404':
    $ref: '#/components/responses/NotFound'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_copies_by_id_check
x-piece: M.11b

operationId: post_copies_by_id_check
summary: Apply one part-check action (start, answer, found_one, skip, select, back,
  next, spares, recheck, finish, undo).
tags:
- Copies
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/CheckAction'
responses:
  '200':
    description: Done.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenCheckState'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_copies_by_id_check
x-piece: M.11c

operationId: get_copies_by_id_gaps
summary: Missing, damaged and absent items of the copy.
tags:
- Copies
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Direction'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ListOfGap'
  '404':
    $ref: '#/components/responses/NotFound'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_copies_by_id_gaps
x-piece: M.11b

operationId: get_copies_by_id_matches
summary: Loose stock that would fill the copy gaps.
tags:
- Copies
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Direction'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ListOfMatch'
  '404':
    $ref: '#/components/responses/NotFound'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_copies_by_id_matches
x-piece: M.11b

operationId: post_copies_by_id_take
x-mcp-tool: take_for_gap
summary: Take N of one missing part (with its colour) or whole minifigure from loose
  stock into the copy; one Undo reverses every move.
tags:
- Copies
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/IdempotencyKeyRequired'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/Take'
responses:
  '200':
    description: Done.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenReceipt'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_copies_by_id_take
x-piece: M.11c

operationId: get_copies_by_id_parts
x-mcp-tool: list_copy_parts
summary: Part lines of the copy (required, spare, figure components).
tags:
- Copy parts
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Q_spare'
- $ref: '#/components/parameters/Q_parent'
- $ref: '#/components/parameters/Q_problem'
- $ref: '#/components/parameters/Direction'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ListOfCopyPart'
  '404':
    $ref: '#/components/responses/NotFound'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_copies_by_id_parts
x-piece: M.11b

operationId: patch_copies_by_id_parts_by_part_id
x-mcp-tool: set_part_missing
summary: Set missing, damaged, checked for one line (mark missing or found).
tags:
- Copy parts
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/Path_part_id_int'
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/CopyPartPatch'
responses:
  '200':
    description: Written. One transaction, one events row.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenCopyPart'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: patch_copies_by_id_parts_by_part_id
x-piece: M.11c

operationId: post_copies_by_id_parts_bulk
summary: Apply missing counts to many lines by item and colour (mode set or add, optional
  dry run).
tags:
- Copy parts
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/IdempotencyKeyRequired'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/CopyPartBulk'
responses:
  '200':
    description: Done.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenBulkResult'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_copies_by_id_parts_bulk
x-piece: M.11c

operationId: get_copies_by_id_figures
x-mcp-tool: list_copy_figures
summary: Whole figures of the copy.
tags:
- Copy parts
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Direction'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ListOfCopyFigure'
  '404':
    $ref: '#/components/responses/NotFound'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_copies_by_id_figures
x-piece: M.11b

operationId: patch_copies_by_id_figures_by_item_id
x-mcp-tool: set_figure_missing
summary: Set the missing count of one whole figure.
tags:
- Copy parts
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/Path_figure_item_id'
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/CopyFigurePatch'
responses:
  '200':
    description: Written. One transaction, one events row.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenCopyFigure'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: patch_copies_by_id_figures_by_type_by_no
x-piece: M.11c

operationId: get_stock
x-mcp-tool: list_stock
summary: Loose stock lines (parts, minifigures, booklets, anything).
tags:
- Loose stock
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Q_item_kind'
- $ref: '#/components/parameters/Q_number'
- $ref: '#/components/parameters/Q_provider'
- $ref: '#/components/parameters/Q_color'
- $ref: '#/components/parameters/Q_condition'
- $ref: '#/components/parameters/Q_storage'
- $ref: '#/components/parameters/Q_lot'
- $ref: '#/components/parameters/Q_place'
- $ref: '#/components/parameters/Q_flag'
- $ref: '#/components/parameters/Q_problem'
- $ref: '#/components/parameters/Q_theme'
- $ref: '#/components/parameters/Q_year'
- $ref: '#/components/parameters/Q_q'
- $ref: '#/components/parameters/Q_sort'
- $ref: '#/components/parameters/Q_archived'
- $ref: '#/components/parameters/Direction'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ListOfStock'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_stock
x-piece: M.11b

operationId: post_stock
x-mcp-tool: add_stock
summary: Add loose stock; identical lines merge.
tags:
- Loose stock
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/IdempotencyKeyRequired'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/StockCreate'
responses:
  '201':
    description: Written. One transaction, one events row.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenCreated'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_stock
x-piece: M.11c

operationId: get_stock_by_id
summary: One stock line.
tags:
- Loose stock
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Path_id'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/OneStock'
    headers:
      ETag:
        schema:
          type: string
  '404':
    $ref: '#/components/responses/NotFound'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_stock_by_id
x-piece: M.11b

operationId: patch_stock_by_id
x-mcp-tool: update_stock
summary: Edit a stock line (may merge into an existing line; response lists merged
  ids).
tags:
- Loose stock
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/IdempotencyKey'
- $ref: '#/components/parameters/IfMatch'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/StockPatch'
responses:
  '200':
    description: Written. One transaction, one events row.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenStock'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  '412':
    $ref: '#/components/responses/PreconditionFailed'
  default:
    $ref: '#/components/responses/Problem'
x-v1: patch_stock_by_id
x-piece: M.11c

operationId: delete_stock_by_id
summary: Archive the line.
tags:
- Loose stock
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/IdempotencyKey'
- $ref: '#/components/parameters/IfMatch'
responses:
  '200':
    description: Written. One transaction, one events row.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenStock'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  '412':
    $ref: '#/components/responses/PreconditionFailed'
  default:
    $ref: '#/components/responses/Problem'
x-v1: delete_stock_by_id
x-piece: M.11c

operationId: post_stock_by_id_restore
summary: Clear the archive mark.
tags:
- Loose stock
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/IdempotencyKey'
responses:
  '200':
    description: Written. One transaction, one events row.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenStock'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_stock_by_id_restore
x-piece: M.11c

operationId: put_stock_by_id_flags
summary: Replace the line flags.
tags:
- Loose stock
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/FlagSet'
responses:
  '200':
    description: Written. One transaction, one events row.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenStock'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: put_stock_by_id_flags
x-piece: M.11c

operationId: get_stock_by_id_parts
summary: Parts of a loose minifigure.
tags:
- Loose stock
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Direction'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ListOfLooseFigurePart'
  '404':
    $ref: '#/components/responses/NotFound'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_stock_by_id_parts
x-piece: M.11b

operationId: patch_stock_by_id_parts
summary: Set missing and damaged on parts of a loose minifigure.
tags:
- Loose stock
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/LooseFigurePartPatch'
responses:
  '200':
    description: Written. One transaction, one events row.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenLooseFigureParts'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: patch_stock_by_id_parts
x-piece: M.11c

operationId: post_stock_by_id_give
x-mcp-tool: give_from_stock
summary: Give N from this line to a copy gap or a loose-figure part gap.
tags:
- Loose stock
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/IdempotencyKeyRequired'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/Give'
responses:
  '200':
    description: Done.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenReceipt'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_stock_by_id_give
x-piece: M.11c

operationId: post_stock_booklets
summary: Add loose booklets from lines "set number, quantity".
tags:
- Loose stock
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/IdempotencyKeyRequired'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/Booklets'
responses:
  '200':
    description: Done.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenReceipt'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_stock_booklets
x-piece: M.11c

operationId: post_found
summary: Record found parts into copies, a loose line, or a list.
tags:
- Loose stock
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/IdempotencyKeyRequired'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/Found'
responses:
  '200':
    description: Done.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenReceipt'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_found
x-piece: M.11c

operationId: get_minifigures
x-mcp-tool: list_minifigures
summary: 'Figures by identity: owned in sets, loose, missing.'
tags:
- Minifigures
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Q_color'
- $ref: '#/components/parameters/Q_provider'
- $ref: '#/components/parameters/Q_problem'
- $ref: '#/components/parameters/Q_theme'
- $ref: '#/components/parameters/Q_year'
- $ref: '#/components/parameters/Q_q'
- $ref: '#/components/parameters/Q_sort'
- $ref: '#/components/parameters/Q_inventory'
- $ref: '#/components/parameters/Direction'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ListOfMinifigureRow'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_minifigures
x-piece: M.11b

operationId: get_minifigures_by_id
summary: 'One figure: sets, loose lines, missing, matches, prices.'
description: The item detail of a minifigure by its Brick Work id (`used_in` the sets,
  `stock` the loose lines, `gaps` and `matches`). A merged id is `307` to the survivor's
  `/minifigures/{id}`; an item that is not a figure is `404`.
tags:
- Minifigures
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Path_item_id'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/OneItemDetail'
  '307':
    $ref: '#/components/responses/Moved'
  '404':
    $ref: '#/components/responses/NotFound'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_minifigures_by_no
x-piece: M.11b

operationId: get_gaps
x-mcp-tool: list_gaps
summary: Missing items over all copies and loose figures.
tags:
- Matching
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Q_item_kind'
- $ref: '#/components/parameters/Q_number'
- $ref: '#/components/parameters/Q_provider'
- $ref: '#/components/parameters/Q_color'
- $ref: '#/components/parameters/Q_copy_id'
- $ref: '#/components/parameters/Direction'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ListOfGap'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_gaps
x-piece: M.11b

operationId: get_matches
x-mcp-tool: list_matches
summary: 'Suggestions: loose stock that fills a gap.'
tags:
- Matching
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Q_item_kind'
- $ref: '#/components/parameters/Q_number'
- $ref: '#/components/parameters/Q_provider'
- $ref: '#/components/parameters/Q_color'
- $ref: '#/components/parameters/Q_copy_id'
- $ref: '#/components/parameters/Q_completes'
- $ref: '#/components/parameters/Direction'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ListOfMatch'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_matches
x-piece: M.11b

operationId: get_instruction_files
x-mcp-tool: list_instruction_files
summary: Booklet files and booklet identities with coverage.
tags:
- Instructions
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Q_item_kind'
- $ref: '#/components/parameters/Q_number'
- $ref: '#/components/parameters/Q_provider'
- $ref: '#/components/parameters/Q_has_file'
- $ref: '#/components/parameters/Q_archived'
- $ref: '#/components/parameters/Direction'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ListOfInstructionFile'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_instruction_files
x-piece: M.11b

operationId: post_instruction_files
summary: Attach a PDF (multipart, up to 20 MB) to an item.
tags:
- Instructions
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: true
  content:
    multipart/form-data:
      schema:
        $ref: '#/components/schemas/InstructionUpload'
responses:
  '201':
    description: Written. One transaction, one events row.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenInstructionFile'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_instruction_files
x-piece: M.11c

operationId: get_instruction_files_by_id
summary: One file record.
tags:
- Instructions
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Path_id_int'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/OneInstructionFile'
  '404':
    $ref: '#/components/responses/NotFound'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_instruction_files_by_id
x-piece: M.11b

operationId: patch_instruction_files_by_id
summary: Rename the label.
tags:
- Instructions
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id_int'
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/InstructionPatch'
responses:
  '200':
    description: Written. One transaction, one events row.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenInstructionFile'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: patch_instruction_files_by_id
x-piece: M.11c

operationId: delete_instruction_files_by_id
summary: Archive a PDF association.
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id_int'
- $ref: '#/components/parameters/IdempotencyKey'
responses:
  '200':
    description: Archived.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenDeleted'
  default:
    $ref: '#/components/responses/Problem'
x-v1: delete_instruction_files_by_id
x-piece: M.11c

operationId: get_instruction_files_by_id_content
summary: Download the PDF.
tags:
- Instructions
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Path_id_int'
responses:
  '200':
    description: File.
    content:
      application/pdf:
        schema:
          type: string
          format: binary
  '404':
    $ref: '#/components/responses/NotFound'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_instruction_files_by_id_content
x-piece: M.11b

operationId: get_prices
summary: Current price per item, colour, condition and guide.
tags:
- Prices
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Q_item_kind'
- $ref: '#/components/parameters/Q_number'
- $ref: '#/components/parameters/Q_provider'
- $ref: '#/components/parameters/Q_color'
- $ref: '#/components/parameters/Q_condition'
- $ref: '#/components/parameters/Q_guide'
- $ref: '#/components/parameters/Q_source'
- $ref: '#/components/parameters/Direction'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ListOfPriceCurrent'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_prices
x-piece: M.11b

operationId: get_items_by_id_prices
x-mcp-tool: get_prices
summary: Current prices and recorded observations of one item.
tags:
- Prices
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Path_item_id'
- $ref: '#/components/parameters/Q_color'
- $ref: '#/components/parameters/Q_provider'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/OneItemPrices'
  '307':
    $ref: '#/components/responses/Moved'
  '404':
    $ref: '#/components/responses/NotFound'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_items_by_type_by_no_prices
x-piece: M.11b

operationId: post_items_by_id_prices
x-mcp-tool: record_price
summary: Record one manual or valuation observation; Undo sets error=undone and recomputes
  price_current.
tags:
- Prices
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_item_id'
- $ref: '#/components/parameters/IdempotencyKeyRequired'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/PriceCreate'
responses:
  '201':
    description: Written. One transaction, one events row.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenPriceObservation'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_items_by_type_by_no_prices
x-piece: M.11c

operationId: get_items_by_id_prices_history
summary: Observation history of one item.
tags:
- Prices
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Path_item_id'
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Q_color'
- $ref: '#/components/parameters/Q_provider'
- $ref: '#/components/parameters/Q_condition'
- $ref: '#/components/parameters/DirectionNewest'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ListOfPriceObservation'
  '307':
    $ref: '#/components/responses/Moved'
  '404':
    $ref: '#/components/responses/NotFound'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_items_by_type_by_no_prices_history
x-piece: M.11b

operationId: post_prices_observations
summary: Record up to 500 observations in one transaction.
tags:
- Prices
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/IdempotencyKeyRequired'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/PriceBatch'
responses:
  '200':
    description: Done.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenBulkResult'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_prices_observations
x-piece: M.11c

operationId: post_items_by_id_prices_refresh
x-mcp-tool: refresh_price
summary: Queue a market price refresh for one item.
tags:
- Prices
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_item_id'
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/RefreshRequest'
responses:
  '202':
    description: Accepted. The job runs in the background; poll GET /jobs/{id}.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenJob'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  '424':
    $ref: '#/components/responses/DependencyFailed'
  '429':
    $ref: '#/components/responses/BudgetExhausted'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_items_by_type_by_no_prices_refresh
x-piece: M.11d

operationId: get_prices_stale
x-mcp-tool: list_stale_prices
summary: Items whose price is older than the freshness rule.
tags:
- Prices
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Direction'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ListOfStaleItem'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_prices_stale
x-piece: M.11b

operationId: post_prices_refresh
summary: Queue refresh jobs for every stale item.
tags:
- Prices
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
responses:
  '200':
    description: Done.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenJobList'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  '424':
    $ref: '#/components/responses/DependencyFailed'
  '429':
    $ref: '#/components/responses/BudgetExhausted'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_prices_refresh
x-piece: M.11d

operationId: get_wishes
x-mcp-tool: list_wishes
summary: Wishlist rows; under_max filters to rows priced under the wish maximum.
tags:
- Wishlist
security:
- bearerAuth:
  - read
parameters:
- name: list
  in: query
  schema:
    type: string
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Q_item_kind'
- $ref: '#/components/parameters/Q_number'
- $ref: '#/components/parameters/Q_provider'
- $ref: '#/components/parameters/Q_color'
- $ref: '#/components/parameters/Q_condition'
- $ref: '#/components/parameters/Q_flag'
- $ref: '#/components/parameters/Q_under_max'
- $ref: '#/components/parameters/Q_q'
- $ref: '#/components/parameters/Q_sort'
- $ref: '#/components/parameters/Q_archived'
- $ref: '#/components/parameters/Direction'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ListOfWish'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_wishes
x-piece: M.11b

operationId: post_wishes
x-mcp-tool: add_wish
summary: Add a wish (same colour and item adds to the live row on decision=another).
tags:
- Wishlist
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/IdempotencyKeyRequired'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/WishCreate'
responses:
  '200':
    description: Skipped. The client asked for decision=skip and the item is already
      owned or wished; nothing was written, event_id is null.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenSkipped'
  '201':
    description: Written. One transaction, one events row.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenCreated'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_wishes
x-piece: M.11c

operationId: get_wishes_by_id
summary: One wish.
tags:
- Wishlist
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Path_wish_id'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/OneWish'
    headers:
      ETag:
        schema:
          type: string
  '404':
    $ref: '#/components/responses/NotFound'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_wishes_by_id
x-piece: M.11b

operationId: patch_wishes_by_id
x-mcp-tool: update_wish
summary: Edit quantity, colour, condition, max price, max price with box and their
  currencies, note.
tags:
- Wishlist
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_wish_id'
- $ref: '#/components/parameters/IdempotencyKey'
- $ref: '#/components/parameters/IfMatch'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/WishPatch'
responses:
  '200':
    description: Written. One transaction, one events row.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenWish'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  '412':
    $ref: '#/components/responses/PreconditionFailed'
  default:
    $ref: '#/components/responses/Problem'
x-v1: patch_wishes_by_id
x-piece: M.11c

operationId: delete_wishes_by_id
x-mcp-tool: archive_wish
summary: Archive the wish.
tags:
- Wishlist
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_wish_id'
- $ref: '#/components/parameters/IdempotencyKey'
- $ref: '#/components/parameters/IfMatch'
responses:
  '200':
    description: Written. One transaction, one events row.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenWish'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  '412':
    $ref: '#/components/responses/PreconditionFailed'
  default:
    $ref: '#/components/responses/Problem'
x-v1: delete_wishes_by_id
x-piece: M.11c

operationId: post_wishes_by_id_restore
summary: Restore an archived wish.
tags:
- Wishlist
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_wish_id'
- $ref: '#/components/parameters/IdempotencyKey'
responses:
  '200':
    description: Written. One transaction, one events row.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenWish'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_wishes_by_id_restore
x-piece: M.11c

operationId: put_wishes_by_id_flags
summary: Replace the wish flags.
tags:
- Wishlist
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_wish_id'
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/FlagSet'
responses:
  '200':
    description: Written. One transaction, one events row.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenWish'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: put_wishes_by_id_flags
x-piece: M.11c

operationId: post_wishes_by_id_to_owned
x-mcp-tool: wish_to_owned
summary: Turn a wish into owned copies and archive the wish, one transaction.
tags:
- Wishlist
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_wish_id'
- $ref: '#/components/parameters/IdempotencyKeyRequired'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/WishToOwned'
responses:
  '200':
    description: Written. One transaction, one events row.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenCreated'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_wishes_by_id_to_owned
x-piece: M.11c

operationId: get_storages
x-mcp-tool: list_storages
summary: Active storages with counts, plus the virtual "Not stored".
tags:
- Storages
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Direction'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ListOfStorage'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_storages
x-piece: M.11b

operationId: post_storages
x-mcp-tool: create_storage
summary: Create a storage.
tags:
- Storages
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/StorageInput'
responses:
  '201':
    description: Written. One transaction, one events row.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenStorage'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_storages
x-piece: M.11c

operationId: get_storages_by_id
summary: Storage with its contents.
tags:
- Storages
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Path_id'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/OneStorageDetail'
  '404':
    $ref: '#/components/responses/NotFound'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_storages_by_id
x-piece: M.11b

operationId: patch_storages_by_id
summary: Rename.
tags:
- Storages
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/StorageInput'
responses:
  '200':
    description: Written. One transaction, one events row.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenStorage'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: patch_storages_by_id
x-piece: M.11c

operationId: delete_storages_by_id
summary: Archive; refuses non-empty unless move_to_unstored=true.
tags:
- Storages
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/Q_move_to_unstored'
- $ref: '#/components/parameters/IdempotencyKey'
responses:
  '200':
    description: Written. One transaction, one events row.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenStorage'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: delete_storages_by_id
x-piece: M.11c

operationId: post_storages_by_id_contents
x-mcp-tool: move_to_storage
summary: Move copies, stock and lots into this storage (id "unstored" for none). A
  lot carries its parts in the same storage.
tags:
- Storages
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/IdempotencyKeyRequired'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/StorageMove'
responses:
  '200':
    description: Done.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenReceipt'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_storages_by_id_contents
x-piece: M.11c

operationId: get_lots
x-mcp-tool: list_lots
summary: Part lots.
tags:
- Lots
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Q_storage'
- $ref: '#/components/parameters/Q_archived'
- $ref: '#/components/parameters/Direction'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ListOfLot'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_lots
x-piece: M.11b

operationId: post_lots
summary: Create a lot from existing stock lines.
tags:
- Lots
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/IdempotencyKeyRequired'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/LotCreate'
responses:
  '201':
    description: Written. One transaction, one events row.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenLot'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_lots
x-piece: M.11c

operationId: get_lots_by_id
summary: Lot with its stock.
tags:
- Lots
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Path_id'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/OneLotDetail'
  '404':
    $ref: '#/components/responses/NotFound'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_lots_by_id
x-piece: M.11b

operationId: patch_lots_by_id
summary: Edit name, note, storage, purchase fields.
tags:
- Lots
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/LotPatch'
responses:
  '200':
    description: Written. One transaction, one events row.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenLot'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: patch_lots_by_id
x-piece: M.11c

operationId: delete_lots_by_id
summary: Archive the lot.
tags:
- Lots
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/IdempotencyKey'
responses:
  '200':
    description: Written. One transaction, one events row.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenLot'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: delete_lots_by_id
x-piece: M.11c

operationId: get_places
x-mcp-tool: list_places
summary: Purchase locations with counts and totals per currency.
tags:
- Places
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Direction'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ListOfPlace'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_places
x-piece: M.11b

operationId: post_places
summary: Create a purchase location.
tags:
- Places
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/NameInput'
responses:
  '201':
    description: Written. One transaction, one events row.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenPlace'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_places
x-piece: M.11c

operationId: patch_places_by_id
summary: Rename.
tags:
- Places
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/NameInput'
responses:
  '200':
    description: Written. One transaction, one events row.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenPlace'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: patch_places_by_id
x-piece: M.11c

operationId: delete_places_by_id
summary: Archive retaining references; Undo restores the place.
tags:
- Places
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/IdempotencyKey'
responses:
  '200':
    description: Done.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenDeleted'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: delete_places_by_id
x-piece: M.11c

operationId: get_flags
x-mcp-tool: list_flags
summary: Flags of kind owner, status and tag.
tags:
- Flags
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Q_kind'
- $ref: '#/components/parameters/Direction'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ListOfFlag'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_flags
x-piece: M.11b

operationId: post_flags
summary: Create a flag.
tags:
- Flags
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/FlagInput'
responses:
  '201':
    description: Written. One transaction, one events row.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenFlag'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_flags
x-piece: M.11c

operationId: patch_flags_by_id
summary: Rename.
tags:
- Flags
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/NameInput'
responses:
  '200':
    description: Written. One transaction, one events row.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenFlag'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: patch_flags_by_id
x-piece: M.11c

operationId: delete_flags_by_id
summary: Archive retaining flag links; Undo restores the flag.
tags:
- Flags
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/IdempotencyKey'
responses:
  '200':
    description: Done.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenDeleted'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: delete_flags_by_id
x-piece: M.11c

operationId: get_planning_ranking
x-mcp-tool: get_planning_ranking
summary: Owned copies ranked by cost to complete, with the repair settings used.
tags:
- Planning
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Q_sort'
- $ref: '#/components/parameters/Q_q'
- $ref: '#/components/parameters/Direction'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/RankingPage'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_planning_ranking
x-piece: M.11b

operationId: get_planning_set_scores
x-mcp-tool: get_planning_set_scores
summary: The catalogue's sets ranked by how much of a pile of loose parts each explains.
description: 'Scores the live loose stock of one lot, one storage (and the storages
  inside it), all loose stock, or a saved selection of stock lines (`stock`, repeated)
  against the active catalogue build; give exactly one of `lot`, `storage`, `loose=true`
  or `stock`. Read-only. Each set carries the evidence (the sum, over the lines of
  the pile that the set holds, of the line''s rarity weight ln(N/df) times the covered
  share of the set''s quantity), the coverage (evidence over the set''s own total
  weight), the covered and complete lines, the distinctive lines found of the set''s
  distinctive ones, the matched lines (the heaviest `detail` of them, with the stock
  flags passed through and summed per flag), and the swaps: the same part in another
  colour or as an alternate mould, listed apart and never counted in any number. Ranked
  by evidence, then coverage, then set id. ADR 0026.'
tags:
- Planning
security:
- bearerAuth:
  - read
parameters:
- name: lot
  in: query
  description: A lot id; scores its live loose parts and figures.
  schema:
    type: string
- name: storage
  in: query
  description: A storage id; scores the live loose stock kept in it and in the storages
    inside it.
  schema:
    type: string
- name: loose
  in: query
  description: true scores all live loose parts and figures.
  schema:
    type: boolean
- name: stock
  in: query
  description: Stock line ids (live loose parts or figures), 1 to 5000 different ones.
  style: form
  explode: true
  schema:
    type: array
    items:
      type: string
    maxItems: 5000
    uniqueItems: true
- name: limit
  in: query
  schema:
    type: integer
    minimum: 1
    maximum: 100
    default: 20
- name: offset
  in: query
  schema:
    type: integer
    minimum: 0
    default: 0
- name: detail
  in: query
  description: How many matched lines each set lists (the numbers always count all
    of them).
  schema:
    type: integer
    minimum: 0
    maximum: 50
    default: 10
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/SetScorePage'
  default:
    $ref: '#/components/responses/Problem'
x-piece: M.11b

operationId: get_lots_by_id_candidate_sets
x-mcp-tool: get_lot_candidate_sets
summary: The sets a lot may have come from, ranked, with reasons and distinctive parts
  (Lot Detective).
description: 'Scores the live loose parts and figures of the lot against the active
  catalogue build (the engine of `GET /planning/set-scores`, ADR 0026) and returns
  the candidate sets. The `score` is 0 to 100: how strongly the found parts point
  to the set, weighed by how rare each part is, relative to the best candidate (the
  first set that passes the set filters scores 100). It is NOT a probability and says
  nothing about how likely the set is to be the right one in absolute terms. Each
  set has `reasons` (for example "7 of 9 distinctive parts found", "2 printed parts
  only in this set"), the distinctive parts found and not found yet (a distinctive
  part is held by at most 25 sets; up to 20 of each, heaviest first, with their pictures)
  and the stock flags passed to the engine (a flag named Sticker as `sticker`), and
  the swaps (the lot has the part in another colour, or an alternate mould), listed
  apart and never in the score. A Sticker flag raises the sets that hold the part
  and a sticker sheet, and a confirmed sticker is strong evidence for its set (`POST
  /lots/{id}/stock/{stock_id}/sticker`). By default `ignore_common` drops the lines
  held by more than N sets before scoring (setting `candidate_sets_common_max`, default
  300). The theme filter takes a catalogue theme id or a name (its sub-themes are
  included); the part range is the catalogue''s part count of the set. Read-only;
  an unknown lot is 404.'
tags:
- Lots
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Path_id'
- name: min_score
  in: query
  description: Only sets scoring at least this (0 to 100).
  schema:
    type: number
    minimum: 0
    maximum: 100
    default: 0
- name: theme
  in: query
  description: A catalogue theme id or name; the theme and the themes below it.
  schema:
    type: string
- name: year_from
  in: query
  description: Only sets released in this year or later.
  schema:
    type: integer
    minimum: 0
- name: year_to
  in: query
  description: Only sets released in this year or earlier.
  schema:
    type: integer
    minimum: 0
- name: parts_min
  in: query
  description: Only sets with at least this many parts (the catalogue's part count).
  schema:
    type: integer
    minimum: 0
- name: parts_max
  in: query
  description: Only sets with at most this many parts (the catalogue's part count).
  schema:
    type: integer
    minimum: 0
- name: ignore_common
  in: query
  description: Drop the parts that more than `candidate_sets_common_max` sets hold
    before scoring (default true).
  schema:
    type: boolean
    default: true
- name: limit
  in: query
  schema:
    type: integer
    minimum: 1
    maximum: 100
    default: 20
- name: offset
  in: query
  schema:
    type: integer
    minimum: 0
    default: 0
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/CandidateSetPage'
  '404':
    $ref: '#/components/responses/NotFound'
  default:
    $ref: '#/components/responses/Problem'
x-piece: M.11b

operationId: get_planning_build_scout
x-mcp-tool: get_planning_build_scout
summary: 'Build Scout (#9): the catalogue''s sets ranked by how much of each the loose
  stock already makes.'
description: 'For every catalogue set that shares a part with the chosen loose stock:
  the parts available (the sum over the set''s own part lines of min(have, need);
  spares and a minifigure''s components are not part lines), the percent of the set''s
  parts that is, the missing parts and lines, the whole figures available of those
  required (a loose whole figure counts), and with `detail` the biggest missing lines,
  the missing figures, the cost to complete (missing lines priced from the current
  prices, in the one currency most are priced in, with the number of unpriced lines)
  and the swaps (another colour, an alternate mould), listed apart and never in a
  number. Ranked by percent available, then fewest missing parts, then set id. The
  stock is the live loose parts and whole figures with what can be given (damaged
  rows give nothing unless `damaged=true`) of the chosen sources: `loose=true` (the
  stock kept in no lot or storage), the `lot` and `storage` ids (a storage with the
  storages inside it), or all loose stock when none is given. Read-only. ADR 0027.'
tags:
- Planning
security:
- bearerAuth:
  - read
parameters:
- name: lot
  in: query
  description: Lot ids (repeated); the stock kept in them.
  style: form
  explode: true
  schema:
    type: array
    items:
      type: string
    maxItems: 500
    uniqueItems: true
- name: storage
  in: query
  description: Storage ids (repeated); the stock kept in them and in the storages
    inside them.
  style: form
  explode: true
  schema:
    type: array
    items:
      type: string
    maxItems: 500
    uniqueItems: true
- name: loose
  in: query
  description: true adds the stock kept in no lot or storage.
  schema:
    type: boolean
- name: damaged
  in: query
  description: true counts stock whose condition is damaged (off by default).
  schema:
    type: boolean
- name: min_percent
  in: query
  description: The least percent of a set's parts that must be available.
  schema:
    type: integer
    minimum: 0
    maximum: 100
    default: 60
- name: max_missing
  in: query
  description: The most missing parts (pieces) a set may have.
  schema:
    type: integer
    minimum: 0
- name: theme
  in: query
  description: A catalogue theme id or name (any case), with its sub-themes.
  schema:
    type: string
- name: year_from
  in: query
  schema:
    type: integer
- name: year_to
  in: query
  schema:
    type: integer
- name: size_from
  in: query
  description: The fewest parts a set has (spares left out).
  schema:
    type: integer
    minimum: 0
- name: size_to
  in: query
  schema:
    type: integer
    minimum: 0
- name: limit
  in: query
  schema:
    type: integer
    minimum: 1
    maximum: 100
    default: 20
- name: offset
  in: query
  schema:
    type: integer
    minimum: 0
    default: 0
- name: detail
  in: query
  description: How many missing lines each set lists, with its missing figures, cost
    and swaps (0 lists none of them).
  schema:
    type: integer
    minimum: 0
    maximum: 50
    default: 0
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/BuildScoutPage'
  '404':
    $ref: '#/components/responses/NotFound'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-piece: M.11b

operationId: get_lots_by_id_stock_by_stock_id_stickers
x-mcp-tool: list_sticker_candidates
summary: The sets a sticker on a part line of a lot may belong to (sets that hold
  the part in its colour and a sticker sheet).
description: 'The catalogue does not say which part a sticker goes on, so this is
  the fallback: the live catalogue sets whose latest inventory holds the part in the
  line''s colour AND a sticker sheet (a part of the category named `Stickers`; spare
  lines are left out). A set with several sheets is one row, its sheet with the lowest
  number first; sets with a sheet picture come first, then the earlier year. `sticker`
  says whether the line holds the Sticker flag and which set was confirmed ("This
  one"). Read-only; a line that is not a live part of the lot is 404.'
tags:
- Lots
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/Path_stock_id'
- name: limit
  in: query
  schema:
    type: integer
    minimum: 1
    maximum: 100
    default: 20
- name: offset
  in: query
  schema:
    type: integer
    minimum: 0
    default: 0
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/StickerCandidatePage'
  '404':
    $ref: '#/components/responses/NotFound'
  default:
    $ref: '#/components/responses/Problem'
x-piece: M.11b

operationId: post_lots_by_id_stock_by_stock_id_sticker
x-mcp-tool: confirm_sticker
summary: 'Confirm the sticker of a part line: the sheet of a set from the candidates
  ("This one"). One undoable event; choosing what is already chosen writes nothing.'
description: The line must hold the Sticker flag (409 otherwise) and the pair must
  be one of the line's candidates (422 otherwise). A confirmed sticker is strong evidence
  for its set in Lot Detective and `GET /planning/set-scores`; the flag alone is a
  smaller hint. Undo takes the choice back.
tags:
- Lots
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/Path_stock_id'
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/StickerConfirm'
responses:
  '200':
    description: Done.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenSticker'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-piece: M.11c

operationId: delete_lots_by_id_stock_by_stock_id_sticker
x-mcp-tool: clear_sticker
summary: 'Not a sticker: remove the Sticker flag from a part line and stop counting
  a confirmed sticker. One undoable event; a line without the flag writes nothing.'
tags:
- Lots
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/Path_stock_id'
- $ref: '#/components/parameters/IdempotencyKey'
responses:
  '200':
    description: Done.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenSticker'
  '404':
    $ref: '#/components/responses/NotFound'
  default:
    $ref: '#/components/responses/Problem'
x-piece: M.11c

operationId: get_lots_by_id_pull_list_by_set_id
x-mcp-tool: get_lot_pull_list
summary: 'The pull list of a set for a lot (#202, Lot Detective): the set''s lines
  with what each needs, what the lot holds and what is found so far.'
description: 'The set''s own parts (the latest Rebrickable list, sub-sets expanded,
  spares left out) and its whole minifigures, as Build Scout reads them. Per line:
  `need` (what the set has), `held` (what the lot can give: damaged rows give nothing),
  `found` (`held` plus the pieces ticked in the bulk and not filed yet, never above
  `need`) and `to_find`. `totals` count pieces over all lines: `moves` is what Make
  it a copy would move out of the lot, `missing` what it would record as missing on
  the copy and `stays` what the lot keeps. Lines come in category then number order
  (whole figures last); `show` keeps the lines still to find (`find`), the complete
  ones (`found`) or all. `refusal` says why Make it a copy would be refused (a set
  made of other sets, nothing found yet). Read-only; an unknown lot or set is 404,
  a set with no part list 422.'
tags:
- Lots
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/Path_set_item_id'
- name: show
  in: query
  description: Which lines to list; the totals always count the whole list.
  schema:
    type: string
    enum:
    - find
    - found
    - all
    default: all
- name: limit
  in: query
  schema:
    type: integer
    minimum: 1
    maximum: 500
    default: 100
- name: offset
  in: query
  schema:
    type: integer
    minimum: 0
    default: 0
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/PullListPage'
  '404':
    $ref: '#/components/responses/NotFound'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-piece: M.11b

operationId: post_lots_by_id_pull_list_by_set_id_found
summary: 'Save how many of one part of the pull list are found (an absolute count,
  idempotent; kept between visits). Not an event: nothing to undo.'
description: The count includes what the lot already holds of the line (`held`); a
  count below it only drops the pieces ticked in the bulk. Pieces ticked and not in
  the lot yet are filed in the lot, as found in the bulk, when Make it a copy runs.
  The line must be on the list (422 otherwise) and `found` is 0 to its `need`. `event_id`
  and `undo_url` are always null.
tags:
- Lots
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/Path_set_item_id'
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/PullFound'
responses:
  '200':
    description: Done.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenPullFound'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-piece: M.11c

operationId: post_lots_by_id_pull_list_by_set_id_make_copy
x-mcp-tool: make_copy_from_lot
summary: 'Make it a copy (#202): the found pieces of the pull list move out of the
  lot into a new copy of the set, the rest recorded as missing on it. One undoable
  event.'
description: 'One transaction and one event (`copy` / `make_from_stock`). The pieces
  ticked in the bulk are filed in the lot first, then exactly the found counts move
  from the lot''s stock rows into the copy (nothing of another lot); everything the
  set has and was not found is recorded as missing on the copy, which starts used,
  incomplete and not checked. The lot keeps the leftovers and the progress of this
  (lot, set) is cleared. Undo (`POST /events/{id}/undo`) puts the stock back and archives
  the copy; the pieces ticked in the bulk stay filed in the lot. Refused with 422
  and nothing written: a set made of other sets, nothing found yet, a set with no
  part list.'
tags:
- Lots
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/Path_set_item_id'
- $ref: '#/components/parameters/IdempotencyKeyRequired'
responses:
  '200':
    description: Done.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenCopyFromLot'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-piece: M.11c

operationId: get_export_missing_csv
summary: 'Missing parts of the chosen copies as CSV (the printable list, #43).'
security:
- bearerAuth:
  - read
parameters:
- name: copy_id
  in: query
  description: Repeated copy IDs.
  style: form
  explode: true
  schema:
    type: array
    items:
      type: string
    maxItems: 2000
    uniqueItems: true
- name: ids
  in: query
  description: Comma-separated copy IDs; alternative to copy_id.
  schema:
    type: string
responses:
  '200':
    description: CSV with the columns Item type, Item number, Name, Colour, Colour
      id, Condition, Quantity.
    content:
      text/csv:
        schema:
          type: string
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_export_missing_csv
x-piece: M.11b

operationId: get_export_picker_csv
summary: Part Runner results for the chosen copies as CSV, in pick order (#43).
security:
- bearerAuth:
  - read
parameters:
- name: copy_id
  in: query
  description: Repeated copy IDs.
  style: form
  explode: true
  schema:
    type: array
    items:
      type: string
    maxItems: 2000
    uniqueItems: true
- name: rank
  in: query
  description: Pick order keys (category, colour, size, set, storage); default all.
  style: form
  explode: true
  schema:
    type: array
    items:
      type: string
responses:
  '200':
    description: CSV with the columns Rank, Item type, Item number, Name, Colour,
      Colour id, Quantity, Sets, Storage.
    content:
      text/csv:
        schema:
          type: string
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_export_picker_csv
x-piece: M.11b

operationId: get_export_wishlist_csv
summary: The wishlist (one list or all) as CSV (#43).
security:
- bearerAuth:
  - read
parameters:
- name: list
  in: query
  description: A wishlist id, or all (default).
  schema:
    type: string
responses:
  '200':
    description: CSV with the columns List, Item type, Item number, Name, Colour,
      Colour id, Quantity, Condition, Max price, Currency, Note.
    content:
      text/csv:
        schema:
          type: string
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_export_wishlist_csv
x-piece: M.11b

operationId: get_export_missing_json
summary: Aggregated missing items for chosen copies, using the XML export rules.
description: One line per item, colour and condition, each with the BrickLink type,
  number and colour number the XML names it by. A line with no confirmed BrickLink
  number is not in the XML; it is in `skipped` with the reason.
security:
- bearerAuth:
  - read
parameters:
- name: ids
  in: query
  description: Comma-separated copy IDs (1 to 2000 unique IDs).
  schema:
    type: string
- name: copy_id
  in: query
  description: Repeated copy IDs; alternative to comma-separated ids.
  style: form
  explode: true
  schema:
    type: array
    items:
      type: string
    maxItems: 2000
    uniqueItems: true
responses:
  '200':
    description: Missing items.
    content:
      application/json:
        schema:
          type: object
          required:
          - data
          properties:
            data:
              type: array
              items:
                type: object
                required:
                - item
                - color
                - quantity
                - condition
                - bricklink
                properties:
                  item:
                    $ref: '#/components/schemas/Item'
                  color:
                    oneOf:
                    - $ref: '#/components/schemas/Color'
                    - type: 'null'
                  quantity:
                    type: integer
                  condition:
                    enum:
                    - new
                    - used
                    - null
                  bricklink:
                    description: The BrickLink type, item number and colour number
                      of the wanted-list line.
                    type: object
                    required:
                    - type
                    - 'no'
                    - color_id
                    properties:
                      type:
                        type: string
                      'no':
                        type: string
                      color_id:
                        type:
                        - integer
                        - 'null'
            skipped:
              description: Lines the XML leaves out because BrickLink cannot name
                them.
              type: array
              items:
                type: object
                required:
                - item
                - color
                - quantity
                - condition
                - why
                properties:
                  item:
                    $ref: '#/components/schemas/Item'
                  color:
                    oneOf:
                    - $ref: '#/components/schemas/Color'
                    - type: 'null'
                  quantity:
                    type: integer
                  condition:
                    enum:
                    - new
                    - used
                    - null
                  why:
                    type: string
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_export_missing_json
x-piece: M.11b

operationId: get_export_missing_xml
summary: BrickLink wanted-list XML of missing items for chosen copies.
tags:
- Planning
security:
- bearerAuth:
  - read
parameters:
- name: copy_id
  in: query
  description: Repeated copy IDs, or use comma-separated ids (1 to 2000 unique IDs).
  style: form
  explode: true
  schema:
    type: array
    items:
      type: string
    maxItems: 2000
    uniqueItems: true
- name: ids
  in: query
  description: Comma-separated copy IDs; alternative to repeated copy_id.
  schema:
    type: string
responses:
  '200':
    description: File.
    content:
      application/xml:
        schema:
          type: string
          format: binary
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_export_missing_xml
x-piece: M.11b

operationId: get_orders
x-mcp-tool: list_orders
summary: Orders with line and receipt state.
tags:
- Orders
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Q_bricklink_order_id'
- $ref: '#/components/parameters/Q_status'
- $ref: '#/components/parameters/Direction'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ListOfOrder'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_orders
x-piece: M.11d

operationId: get_orders_export_csv
summary: Saved order lines (kind=lines) or one row per order with new and used totals
  (kind=summary) as CSV, filtered by order date and store (#44). Totals never mix
  currencies.
security:
- bearerAuth:
  - read
parameters:
- name: from
  in: query
  schema:
    type: string
    format: date
- name: to
  in: query
  schema:
    type: string
    format: date
- name: store
  in: query
  schema:
    type: string
- name: kind
  in: query
  schema:
    type: string
    enum:
    - lines
    - summary
    default: lines
responses:
  '200':
    description: 'CSV. Lines: Order, Date, Store, Seller, Item type, Item number,
      Name, Colour, Colour id, Condition, Quantity, Unit price, Line total, Currency.
      Summary: Order, Date, Store, Seller, Status, Lines, Items, New total, Used total,
      Other costs, Grand total, Currency.'
    content:
      text/csv:
        schema:
          type: string
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_orders_export_csv
x-piece: M.11d

operationId: get_orders_by_id
x-mcp-tool: get_order
summary: Order with documents and lines.
tags:
- Orders
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Path_id_int'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/OneOrderDetail'
  '404':
    $ref: '#/components/responses/NotFound'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_orders_by_id
x-piece: M.11d

operationId: post_orders_documents
x-mcp-tool: import_order
summary: 'Import an order document: pasted email, BrickLink XML, or fetch by order
  number with the user key.'
tags:
- Orders
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/IdempotencyKeyRequired'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/OrderImport'
responses:
  '200':
    description: Done.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenOrderImportResult'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  '424':
    $ref: '#/components/responses/DependencyFailed'
  '429':
    $ref: '#/components/responses/BudgetExhausted'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_orders_documents
x-piece: M.11d

operationId: patch_orders_by_id_lines_by_line_id
summary: Match a line to a catalogue identity.
tags:
- Orders
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id_int'
- $ref: '#/components/parameters/Path_line_id_int'
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/OrderLineMatch'
responses:
  '200':
    description: Done.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenReceipt'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: patch_orders_by_id_lines_by_line_id
x-piece: M.11d

operationId: put_orders_by_id_lines_by_line_id_hold
summary: Hold or release a line.
tags:
- Orders
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id_int'
- $ref: '#/components/parameters/Path_line_id_int'
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/Hold'
responses:
  '200':
    description: Done.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenReceipt'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: put_orders_by_id_lines_by_line_id_hold
x-piece: M.11d

operationId: post_orders_by_id_documents_by_doc_id_phase
summary: 'Move a document: review, reopen or save.'
tags:
- Orders
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id_int'
- $ref: '#/components/parameters/Path_doc_id_int'
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/OrderPhase'
responses:
  '200':
    description: Done.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenReceipt'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_orders_by_id_documents_by_doc_id_phase
x-piece: M.11d

operationId: post_orders_by_id_received
summary: Record received counts per line.
tags:
- Orders
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id_int'
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/OrderReceived'
responses:
  '200':
    description: Done.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenReceipt'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_orders_by_id_received
x-piece: M.11d

operationId: post_orders_by_id_allocate
summary: Allocate received lines to copies or stock.
tags:
- Orders
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id_int'
- $ref: '#/components/parameters/IdempotencyKeyRequired'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/OrderAllocate'
responses:
  '200':
    description: Done.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenReceipt'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_orders_by_id_allocate
x-piece: M.11d

operationId: post_orders_by_id_reconcile
summary: Reconcile the order.
tags:
- Orders
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id_int'
- $ref: '#/components/parameters/IdempotencyKey'
responses:
  '200':
    description: Done.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenReceipt'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_orders_by_id_reconcile
x-piece: M.11d

operationId: get_orders_by_id_short_xml
summary: BrickLink XML of the still-missing lines.
tags:
- Orders
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Path_id_int'
responses:
  '200':
    description: File.
    content:
      application/xml:
        schema:
          type: string
          format: binary
  '404':
    $ref: '#/components/responses/NotFound'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_orders_by_id_short_xml
x-piece: M.11d

operationId: post_orders_by_id_allocations_retry
summary: Retry reviewed allocation choices atomically against current counts and gaps.
tags:
- Orders
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id_int'
- $ref: '#/components/parameters/IdempotencyKeyRequired'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/OrderAllocate'
responses:
  '200':
    description: Done.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenReceipt'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_orders_by_id_allocations_retry
x-piece: M.11d

operationId: get_orders_by_id_allocation_review
summary: Read order allocation-review.
tags:
- Orders
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Path_id_int'
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
responses:
  '200':
    description: Done.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ListOfOrderReview'
  '404':
    $ref: '#/components/responses/NotFound'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_orders_by_id_allocation_review
x-piece: M.11d

operationId: get_orders_by_id_allocations
summary: Read order allocations.
tags:
- Orders
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Path_id_int'
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
responses:
  '200':
    description: Done.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ListOfAllocation'
  '404':
    $ref: '#/components/responses/NotFound'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_orders_by_id_allocations
x-piece: M.11d

operationId: get_orders_by_id_history
summary: Read order history.
tags:
- Orders
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Path_id_int'
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
responses:
  '200':
    description: Done.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ListOfOrderHistory'
  '404':
    $ref: '#/components/responses/NotFound'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_orders_by_id_history
x-piece: M.11d

operationId: get_events
x-mcp-tool: list_events
summary: Audit events, newest first.
tags:
- Events
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Q_entity'
- $ref: '#/components/parameters/Q_field'
- $ref: '#/components/parameters/Q_via'
- $ref: '#/components/parameters/Q_since'
- $ref: '#/components/parameters/Q_undoable'
- $ref: '#/components/parameters/DirectionNewest'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ListOfEvent'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_events
x-piece: M.11b

operationId: get_events_by_id
summary: One event with old and new values.
tags:
- Events
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Path_id_int'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/OneEvent'
  '404':
    $ref: '#/components/responses/NotFound'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_events_by_id
x-piece: M.11b

operationId: post_events_by_id_undo
x-mcp-tool: undo_event
summary: Undo M3 collection or supported standalone core receipts. Token, source key
  and source toggle receipts (alone or inside an API event) require admin; other receipts
  require write.
tags:
- Events
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id_int'
- $ref: '#/components/parameters/IdempotencyKeyRequired'
responses:
  '200':
    description: Done.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenUndoResult'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '401':
    $ref: '#/components/responses/Unauthorized'
  '503':
    $ref: '#/components/responses/Problem'
  '403':
    $ref: '#/components/responses/Forbidden'
  '400':
    $ref: '#/components/responses/Problem'
  '428':
    $ref: '#/components/responses/Problem'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_events_by_id_undo
x-piece: M.11c

operationId: get_jobs
x-mcp-tool: list_jobs
summary: Import and refresh jobs with steps.
tags:
- Jobs
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Q_state'
- $ref: '#/components/parameters/Q_failed'
- $ref: '#/components/parameters/DirectionNewest'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ListOfJob'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_jobs
x-piece: M.11d

operationId: get_jobs_by_id
summary: One job.
tags:
- Jobs
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Path_id_int'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/OneJob'
  '404':
    $ref: '#/components/responses/NotFound'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_jobs_by_id
x-piece: M.11d

operationId: post_jobs_by_id_retry
x-mcp-tool: retry_job
summary: Retry failed steps (all, or one step). Queues the work and returns the job.
tags:
- Jobs
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id_int'
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: false
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/JobRetry'
responses:
  '202':
    description: Accepted. The job runs in the background; poll GET /jobs/{id}.
    headers:
      Location:
        description: Poll this job.
        schema:
          type: string
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenJob'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  '424':
    $ref: '#/components/responses/DependencyFailed'
  '429':
    $ref: '#/components/responses/BudgetExhausted'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_jobs_by_id_retry
x-piece: M.11d

operationId: post_jobs_by_id_resume
summary: Resume an interrupted or budget-waiting job.
tags:
- Jobs
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id_int'
- $ref: '#/components/parameters/IdempotencyKey'
responses:
  '202':
    description: Accepted. The job runs in the background; poll GET /jobs/{id}.
    headers:
      Location:
        description: Poll this job.
        schema:
          type: string
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenJob'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  '424':
    $ref: '#/components/responses/DependencyFailed'
  '429':
    $ref: '#/components/responses/BudgetExhausted'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_jobs_by_id_resume
x-piece: M.11d

operationId: post_jobs_drain
summary: Run one drain of due jobs in the request.
tags:
- Jobs
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
responses:
  '200':
    description: Done.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenJobList'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  '424':
    $ref: '#/components/responses/DependencyFailed'
  '429':
    $ref: '#/components/responses/BudgetExhausted'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_jobs_drain
x-piece: M.11d

operationId: post_jobs_instruction_identities
summary: Queue identity refresh for booklets without a file.
tags:
- Jobs
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
responses:
  '202':
    description: Accepted. The jobs run in the background; poll GET /jobs/{id}.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenJobList'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  '424':
    $ref: '#/components/responses/DependencyFailed'
  '429':
    $ref: '#/components/responses/BudgetExhausted'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_jobs_instruction_identities
x-piece: M.11d

operationId: post_jobs_pictures
summary: Queue a picture refresh for a scope.
tags:
- Jobs
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/PictureRefresh'
responses:
  '202':
    description: Accepted. The job runs in the background; poll GET /jobs/{id}.
    headers:
      Location:
        description: Poll this job.
        schema:
          type: string
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenJobList'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  '424':
    $ref: '#/components/responses/DependencyFailed'
  '429':
    $ref: '#/components/responses/BudgetExhausted'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_jobs_pictures
x-piece: M.11d

operationId: get_sources
x-mcp-tool: get_sources
summary: Sources with key state (configured yes or no), budget, usage today, last
  success and error.
tags:
- Sources
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Direction'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ListOfSource'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_sources
x-piece: M.11d

operationId: patch_sources_by_source
summary: Enable or disable a source. Undo restores the previous state.
tags:
- Sources
security:
- bearerAuth:
  - admin
parameters:
- $ref: '#/components/parameters/Path_source'
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/SourceToggle'
responses:
  '200':
    description: Written. One transaction, one events row.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenSource'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: patch_sources_by_source
x-piece: M.11d

operationId: post_catalogue_import
summary: Rebuild the catalogue file from the BrickLink XML files beside the database.
  No path or URL parameter; not undoable.
tags:
- Sources
security:
- bearerAuth:
  - admin
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
responses:
  '200':
    description: Done.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenCatalogueStatus'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_catalogue_import
x-piece: M.11d

operationId: get_sync_by_source
x-mcp-tool: get_sync_status
summary: 'Sync status per source: credentials (never their values), link, last pull,
  last send and what is waiting.'
tags:
- Sync
security:
- bearerAuth:
  - read
parameters:
- name: source
  in: path
  required: true
  schema:
    type: string
    enum:
    - rebrickable
    - brickset
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/OneSyncStatus'
  '404':
    $ref: '#/components/responses/NotFound'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_sync_by_source
x-piece: M.11d

operationId: get_sync_by_source_lists
summary: The site's set lists (Rebrickable); Brickset has none. One remote call.
tags:
- Sync
security:
- bearerAuth:
  - read
parameters:
- name: source
  in: path
  required: true
  schema:
    type: string
    enum:
    - rebrickable
    - brickset
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/SyncListPage'
  '404':
    $ref: '#/components/responses/NotFound'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_sync_by_source_lists
x-piece: M.11d

operationId: put_sync_by_source_link
summary: 'Choose the remote lists: Rebrickable owned (ids), wishlist (id), send_to
  (id); both: wish_list (a Brick Work wishlist).'
tags:
- Sync
security:
- bearerAuth:
  - write
parameters:
- name: source
  in: path
  required: true
  schema:
    type: string
    enum:
    - rebrickable
    - brickset
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: true
  content:
    application/json:
      schema:
        type: object
        additionalProperties: false
        properties:
          owned:
            type: array
            items:
              type: integer
          wishlist:
            type:
            - integer
            - 'null'
          send_to:
            type:
            - integer
            - 'null'
          wish_list:
            type: string
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenSyncStatus'
  '404':
    $ref: '#/components/responses/NotFound'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: put_sync_by_source_link
x-piece: M.11d

operationId: post_sync_by_source_pull_plan
x-mcp-tool: plan_sync_pull
summary: 'Fetch the remote collection and compare: add here, only here, differs, conflict
  (changed in both places), unmatched. Writes nothing to the collection; the plan
  expires after 24 hours.'
tags:
- Sync
security:
- bearerAuth:
  - write
parameters:
- name: source
  in: path
  required: true
  schema:
    type: string
    enum:
    - rebrickable
    - brickset
- $ref: '#/components/parameters/IdempotencyKey'
responses:
  '201':
    description: Plan created.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenSyncPlan'
  '404':
    $ref: '#/components/responses/NotFound'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_sync_by_source_pull_plan
x-piece: M.11d

operationId: post_sync_by_source_pull_apply
x-mcp-tool: apply_sync_pull
summary: 'Apply a pull plan: one copy per missing unit (flag imported from <site>,
  condition and completeness unset) and missing wishes, in one transaction. Ticked
  defaults to the suggested rows; conflicts only when ticked. Undo with POST /events/{id}/undo.'
tags:
- Sync
security:
- bearerAuth:
  - write
parameters:
- name: source
  in: path
  required: true
  schema:
    type: string
    enum:
    - rebrickable
    - brickset
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: true
  content:
    application/json:
      schema:
        type: object
        additionalProperties: false
        required:
        - plan_id
        properties:
          plan_id:
            type: string
          ticked:
            type: array
            items:
              type: string
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenSyncApplied'
  '404':
    $ref: '#/components/responses/NotFound'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_sync_by_source_pull_apply
x-piece: M.11d

operationId: post_sync_by_source_send_plan
x-mcp-tool: plan_sync_send
summary: 'The remote calls a send would make: set counts and wishes; removals are
  never ticked by default.'
tags:
- Sync
security:
- bearerAuth:
  - write
parameters:
- name: source
  in: path
  required: true
  schema:
    type: string
    enum:
    - rebrickable
    - brickset
- $ref: '#/components/parameters/IdempotencyKey'
responses:
  '201':
    description: Plan created.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenSyncPlan'
  '404':
    $ref: '#/components/responses/NotFound'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_sync_by_source_send_plan
x-piece: M.11d

operationId: post_sync_by_source_send_apply
summary: Perform the ticked remote calls; each row reports sent, unchanged, failed,
  paused (budget) or key_rejected. Remote changes are not undone by Brick Work's Undo;
  re-applying retries only rows not yet sent.
tags:
- Sync
security:
- bearerAuth:
  - admin
parameters:
- name: source
  in: path
  required: true
  schema:
    type: string
    enum:
    - rebrickable
    - brickset
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: true
  content:
    application/json:
      schema:
        type: object
        additionalProperties: false
        required:
        - plan_id
        properties:
          plan_id:
            type: string
          ticked:
            type: array
            items:
              type: string
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenSyncSent'
  '404':
    $ref: '#/components/responses/NotFound'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_sync_by_source_send_apply
x-piece: M.11d

operationId: put_sources_by_source_user
summary: Store a user token (Rebrickable) or userHash (Brickset) you generated on
  the site. Write-only; BW_SECRET_KEY required.
tags:
- Sync
security:
- bearerAuth:
  - admin
parameters:
- name: source
  in: path
  required: true
  schema:
    type: string
    enum:
    - rebrickable
    - brickset
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: true
  content:
    application/json:
      schema:
        type: object
        additionalProperties: false
        required:
        - value
        properties:
          value:
            type: string
            minLength: 8
            maxLength: 256
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenSyncCredentials'
  '404':
    $ref: '#/components/responses/NotFound'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: put_sources_source_user
x-piece: M.11d

operationId: delete_sources_by_source_user
summary: Archive the stored user token or hash; Undo restores it.
tags:
- Sync
security:
- bearerAuth:
  - admin
parameters:
- name: source
  in: path
  required: true
  schema:
    type: string
    enum:
    - rebrickable
    - brickset
- $ref: '#/components/parameters/IdempotencyKey'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenSyncCredentials'
  '404':
    $ref: '#/components/responses/NotFound'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: delete_sources_source_user
x-piece: M.11d

operationId: post_sources_by_source_user_connect
summary: 'One-time connect: the username and password go straight to the site (Rebrickable
  POST /users/_token/, Brickset login); only the returned token or hash is stored,
  encrypted. The password is never stored, logged or returned.'
tags:
- Sync
security:
- bearerAuth:
  - admin
parameters:
- name: source
  in: path
  required: true
  schema:
    type: string
    enum:
    - rebrickable
    - brickset
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: true
  content:
    application/json:
      schema:
        type: object
        additionalProperties: false
        required:
        - username
        - password
        properties:
          username:
            type: string
          password:
            type: string
            format: password
            writeOnly: true
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenSyncCredentials'
  '404':
    $ref: '#/components/responses/NotFound'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_sources_source_user_connect
x-piece: M.11d

operationId: post_sources_by_source_user_test
summary: One remote call that proves the stored user token or hash works.
tags:
- Sync
security:
- bearerAuth:
  - admin
parameters:
- name: source
  in: path
  required: true
  schema:
    type: string
    enum:
    - rebrickable
    - brickset
- $ref: '#/components/parameters/IdempotencyKey'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenKeyTest'
  '404':
    $ref: '#/components/responses/NotFound'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_sources_source_user_test
x-piece: M.11d

operationId: put_sources_by_source_key
summary: Encrypt and store a source key (replaces a stored one). Write-only; BW_SECRET_KEY
  required.
tags:
- Sources
security:
- bearerAuth:
  - admin
parameters:
- $ref: '#/components/parameters/Path_source'
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/SourceKeyInput'
responses:
  '200':
    description: Stored. The key value is never returned.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenSource'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  '424':
    $ref: '#/components/responses/DependencyFailed'
  default:
    $ref: '#/components/responses/Problem'
x-v1: put_sources_source_key
x-piece: M.11d

operationId: delete_sources_by_source_key
summary: Archive the stored key; the source stops using it and Undo restores it.
tags:
- Sources
security:
- bearerAuth:
  - admin
parameters:
- $ref: '#/components/parameters/Path_source'
- $ref: '#/components/parameters/IdempotencyKey'
responses:
  '200':
    description: Archived.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenSource'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: delete_sources_source_key
x-piece: M.11d

operationId: post_sources_by_source_key_test
summary: Make one budgeted call with the key in use. The result carries no key material;
  not undoable.
tags:
- Sources
security:
- bearerAuth:
  - admin
parameters:
- $ref: '#/components/parameters/Path_source'
- $ref: '#/components/parameters/IdempotencyKey'
responses:
  '200':
    description: The key works.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenKeyTest'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  '424':
    $ref: '#/components/responses/DependencyFailed'
  '429':
    $ref: '#/components/responses/BudgetExhausted'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_sources_source_key_test
x-piece: M.11d

operationId: get_exchange_rates
summary: Exchange rates per 1 EUR (hand-entered or ECB) and the display currency (#39).
  Stored amounts never change currency.
security:
- bearerAuth:
  - read
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          type: object
          required:
          - data
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/ExchangeRate'
            display_currency:
              type: string
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_exchange_rates
x-piece: M.11d

operationId: put_exchange_rates_by_code
summary: Enter (or with null remove) one rate per 1 EUR by hand.
security:
- bearerAuth:
  - admin
parameters:
- name: code
  in: path
  required: true
  schema:
    type: string
    pattern: ^[A-Za-z]{3}$
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: true
  content:
    application/json:
      schema:
        type: object
        additionalProperties: false
        required:
        - per_eur
        properties:
          per_eur:
            type:
            - string
            - number
            - 'null'
responses:
  '200':
    description: Saved; the full rate list.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenExchangeRates'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: put_exchange_rates_by_code
x-piece: M.11d

operationId: post_exchange_rates_ecb
summary: Load the ECB daily reference rates (one keyless request); hand-entered rates
  are kept.
security:
- bearerAuth:
  - admin
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
responses:
  '200':
    description: Loaded.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenEcbResult'
  '502':
    $ref: '#/components/responses/Problem'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_exchange_rates_ecb
x-piece: M.11d

operationId: get_settings
x-mcp-tool: get_settings
summary: Allowed settings and freshness rules.
tags:
- Settings
security:
- bearerAuth:
  - read
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/OneSettings'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_settings
x-piece: M.11c

operationId: patch_settings
summary: Update allowed settings (whitelist).
tags:
- Settings
security:
- bearerAuth:
  - admin
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/SettingsPatch'
responses:
  '200':
    description: Written. One transaction, one events row.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenSettings'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: patch_settings
x-piece: M.11c

operationId: get_statistics
x-mcp-tool: get_statistics
summary: Counts by completeness, theme, storage, place.
tags:
- Admin
security:
- bearerAuth:
  - read
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/OneStatistics'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_statistics
x-piece: M.11b

operationId: get_database_check
summary: Integrity, foreign-key check and row counts.
tags:
- Admin
security:
- bearerAuth:
  - admin
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/OneDatabaseCheck'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_database_check
x-piece: M.11d

operationId: get_database_export
summary: SQLite snapshot download. Stored source keys, even encrypted, are removed
  from the copy; refuses (409) if known plaintext credentials would remain.
tags:
- Admin
security:
- bearerAuth:
  - admin
responses:
  '200':
    description: File.
    content:
      application/vnd.sqlite3:
        schema:
          type: string
          format: binary
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_database_export
x-piece: M.11d

operationId: post_imports_bricktracker
summary: Upload a BrickTracker app.db (any upstream version, up to 200 MB) and get
  an import plan. A copy is upgraded with upstream's migrations and compared with
  this collection; nothing is written to the collection.
tags:
- Admin
security:
- bearerAuth:
  - admin
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: true
  content:
    multipart/form-data:
      schema:
        type: object
        additionalProperties: false
        properties:
          file:
            type: string
            format: binary
        required:
        - file
responses:
  '201':
    description: Plan created (expires after 24 hours).
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenImportPlan'
  '413':
    $ref: '#/components/responses/Problem'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_imports_bricktracker
x-piece: M.11d

operationId: post_imports_by_id_apply
summary: 'Apply an import plan: rows marked add are written in one transaction; locked
  rows (already imported, duplicate wishes) are always skipped. Undo with POST /events/{id}/undo
  (admin).'
tags:
- Admin
security:
- bearerAuth:
  - admin
parameters:
- name: id
  in: path
  required: true
  schema:
    type: string
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: false
  content:
    application/json:
      schema:
        type: object
        additionalProperties: false
        properties:
          decisions:
            type: object
            additionalProperties:
              type: string
              enum:
              - add
              - skip
responses:
  '200':
    description: Applied; the event id undoes the whole import.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenImportApplied'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_imports_by_id_apply
x-piece: M.11d

operationId: post_identifications
summary: Upload an image to Brickognize (image, up to 8 MB). Undo archives the record.
tags:
- Admin
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: true
  content:
    multipart/form-data:
      schema:
        type: object
        additionalProperties: false
        properties:
          file:
            type: string
            format: binary
        required:
        - file
responses:
  '201':
    description: Identified and recorded.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenIdentification'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  '424':
    $ref: '#/components/responses/DependencyFailed'
  '429':
    $ref: '#/components/responses/BudgetExhausted'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_identifications
x-piece: M.11d

operationId: get_identifications
summary: Photo identification history; archived rows hidden.
tags:
- Admin
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Direction'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ListOfIdentification'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_identifications
x-piece: M.11d

operationId: get_tokens
summary: 'Tokens: name, scopes, created, last used, revoked. Never the secret.'
tags:
- Tokens
security:
- bearerAuth:
  - admin
parameters:
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Direction'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ListOfToken'
  '401':
    $ref: '#/components/responses/Unauthorized'
  '503':
    $ref: '#/components/responses/Problem'
  '403':
    $ref: '#/components/responses/Forbidden'
  '400':
    $ref: '#/components/responses/Problem'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_tokens
x-piece: M.11d

operationId: post_tokens
summary: Create a token. The secret is shown once in this response.
tags:
- Tokens
security:
- bearerAuth:
  - admin
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/TokenCreate'
responses:
  '201':
    description: Written. One transaction, one events row.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenTokenCreated'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  '401':
    $ref: '#/components/responses/Unauthorized'
  '503':
    $ref: '#/components/responses/Problem'
  '403':
    $ref: '#/components/responses/Forbidden'
  '400':
    $ref: '#/components/responses/Problem'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_tokens
x-piece: M.11d

operationId: delete_tokens_by_id
summary: Revoke a token.
tags:
- Tokens
security:
- bearerAuth:
  - admin
parameters:
- $ref: '#/components/parameters/Path_id'
responses:
  '200':
    description: Written. One transaction, one events row.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenToken'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '401':
    $ref: '#/components/responses/Unauthorized'
  '503':
    $ref: '#/components/responses/Problem'
  '403':
    $ref: '#/components/responses/Forbidden'
  default:
    $ref: '#/components/responses/Problem'
x-v1: delete_tokens_by_id
x-piece: M.11d

operationId: post_copies_by_id_photos
summary: Upload an own photo (image, up to 15 MB). Undo archives it.
tags:
- Copies
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: true
  content:
    multipart/form-data:
      schema:
        type: object
        additionalProperties: false
        properties:
          file:
            type: string
            format: binary
          caption:
            type: string
        required:
        - file
responses:
  '200':
    description: OK; writes include event_id and undo_url.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenCopy'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_copies_id_photos
x-piece: M.11c

operationId: post_stock_by_id_photos
summary: Upload an own photo (image, up to 15 MB). Undo archives it.
tags:
- Loose stock
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
  required: true
  content:
    multipart/form-data:
      schema:
        type: object
        additionalProperties: false
        properties:
          file:
            type: string
            format: binary
          caption:
            type: string
        required:
        - file
responses:
  '200':
    description: OK; writes include event_id and undo_url.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenStock'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_stock_id_photos
x-piece: M.11c

operationId: delete_identifications_by_id
summary: Archive identification; Undo restores it.
tags:
- Admin
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/IdempotencyKey'
responses:
  '200':
    description: Archived.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenIdentification'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  default:
    $ref: '#/components/responses/Problem'
x-v1: delete_identifications_id
x-piece: M.11d

operationId: get_identifications_by_id
summary: Read identification result.
tags:
- Admin
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Path_id'
responses:
  '200':
    description: OK; writes include event_id and undo_url.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/OneIdentification'
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_identifications_id
x-piece: M.11d

operationId: get_identifications_by_id_thumb
summary: Download identification thumbnail.
tags:
- Admin
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Path_id'
responses:
  '200':
    description: OK; writes include event_id and undo_url.
    content:
      image/jpeg:
        schema:
          type: string
          format: binary
  default:
    $ref: '#/components/responses/Problem'
x-v1: get_identifications_id_thumb
x-piece: M.11d

operationId: post_storages_by_id_restore
summary: Restore an archived record.
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/IdempotencyKey'
responses:
  '200':
    description: Restored.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenStorage'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_storages_by_id_restore
x-piece: M.11c

operationId: post_lots_by_id_restore
summary: Restore an archived record.
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/IdempotencyKey'
responses:
  '200':
    description: Restored.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenLot'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_lots_by_id_restore
x-piece: M.11c

operationId: post_places_by_id_restore
summary: Restore an archived record.
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/IdempotencyKey'
responses:
  '200':
    description: Restored.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenPlace'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_places_by_id_restore
x-piece: M.11c

operationId: post_flags_by_id_restore
summary: Restore an archived record.
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/IdempotencyKey'
responses:
  '200':
    description: Restored.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenFlag'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_flags_by_id_restore
x-piece: M.11c

operationId: post_instruction_files_by_id_restore
summary: Restore an archived record.
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id_int'
- $ref: '#/components/parameters/IdempotencyKey'
responses:
  '200':
    description: Restored.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenInstructionFile'
  default:
    $ref: '#/components/responses/Problem'
x-v1: post_instruction_files_by_id_restore
x-piece: M.11c

operationId: get_items_by_id_detail
summary: 'Item detail: properties, counts, owned and wished summary, prices, matches
  (what v1''s GET /items/{type}/{no} returned).'
tags:
- Items
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Path_item_id'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/OneItemDetail'
  '307':
    $ref: '#/components/responses/Moved'
  '404':
    $ref: '#/components/responses/NotFound'
  default:
    $ref: '#/components/responses/Problem'
x-piece: M.11b

operationId: get_sets_by_number_by_no
summary: Find the item for a set number; the same item body as /items/{id} (decision
  2). A set number is the same at both providers. Several items answer 409 ambiguous
  with the candidates, none 404.
tags:
- Identity
security:
- bearerAuth:
  - read
parameters:
- name: 'no'
  in: path
  required: true
  schema:
    type: string
    maxLength: 64
  description: The number in the provider space.
- $ref: '#/components/parameters/Q_provider'
- $ref: '#/components/parameters/Q_color'
responses:
  '200':
    description: The item. With a color, data.color is the resolved Brick Work colour.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/OneItem'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Ambiguous'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-mcp-tool: get_set_by_number
x-piece: M.11a

operationId: get_parts_by_number_by_no
summary: Find the item for a part number; the same item body as /items/{id} (decision
  2). Default provider bricklink; provider=rebrickable for Rebrickable numbers. Several
  items answer 409 ambiguous with the candidates, none 404.
tags:
- Identity
security:
- bearerAuth:
  - read
parameters:
- name: 'no'
  in: path
  required: true
  schema:
    type: string
    maxLength: 64
  description: The number in the provider space.
- $ref: '#/components/parameters/Q_provider'
- $ref: '#/components/parameters/Q_color'
responses:
  '200':
    description: The item. With a color, data.color is the resolved Brick Work colour.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/OneItem'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Ambiguous'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-mcp-tool: get_part_by_number
x-piece: M.11a

operationId: get_minifigures_by_number_by_no
summary: Find the item for a minifigure number; the same item body as /items/{id}
  (decision 2). Default provider bricklink; provider=rebrickable for Rebrickable numbers.
  Several items answer 409 ambiguous with the candidates, none 404.
tags:
- Identity
security:
- bearerAuth:
  - read
parameters:
- name: 'no'
  in: path
  required: true
  schema:
    type: string
    maxLength: 64
  description: The number in the provider space.
- $ref: '#/components/parameters/Q_provider'
- $ref: '#/components/parameters/Q_color'
responses:
  '200':
    description: The item. With a color, data.color is the resolved Brick Work colour.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/OneItem'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Ambiguous'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-mcp-tool: get_minifigure_by_number
x-piece: M.11a

operationId: get_lookup
summary: 'Find the item for any provider number: provider, kind and key (and a colour
  in the provider space). Same body and errors as the by-number paths.'
tags:
- Identity
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Q_provider'
- name: kind
  in: query
  required: true
  schema:
    $ref: '#/components/schemas/Kind'
- name: key
  in: query
  required: true
  schema:
    type: string
    maxLength: 64
- $ref: '#/components/parameters/Q_color'
responses:
  '200':
    description: The item. With a color, data.color is the resolved Brick Work colour.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/OneItem'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Ambiguous'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-mcp-tool: lookup_item
x-piece: M.11a

operationId: get_items_by_id_links
summary: The item's provider links with status, method, origin, preferred and colour
  scope (design 3.2), to-check candidates included.
tags:
- Identity
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Path_item_id'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ListOfItemLink'
  '307':
    $ref: '#/components/responses/Moved'
  '404':
    $ref: '#/components/responses/NotFound'
  default:
    $ref: '#/components/responses/Problem'
x-piece: M.11b

operationId: put_items_by_id_links
summary: Set one manual link of the item, or make one preferred for its colour scope
  (design 3.2). Idempotent per (provider, type, number, colour).
tags:
- Identity
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_item_id'
- $ref: '#/components/parameters/IdempotencyKeyRequired'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/ItemLinkWrite'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenItemLink'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Merged'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-piece: M.11c

operationId: get_items_by_id_provider_status
summary: 'What is known about the item at a provider when there is no key: looked
  and nothing found, to check without candidate, kind differs (design 3.2).'
tags:
- Identity
security:
- bearerAuth:
  - read
parameters:
- $ref: '#/components/parameters/Path_item_id'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ListOfItemProviderStatus'
  '307':
    $ref: '#/components/responses/Moved'
  '404':
    $ref: '#/components/responses/NotFound'
  default:
    $ref: '#/components/responses/Problem'
x-piece: M.11b

operationId: get_links
summary: 'Links and provider statuses across items, by status: status=to_check is
  the list that replaces v1''s /unresolved.'
tags:
- Identity
security:
- bearerAuth:
  - read
parameters:
- name: status
  in: query
  schema:
    type: string
    enum:
    - matched
    - inferred
    - manual
    - to_check
- name: provider
  in: query
  schema:
    type: string
- $ref: '#/components/parameters/Q_item_kind'
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ListOfLinkRow'
  default:
    $ref: '#/components/responses/Problem'
x-piece: M.11b

operationId: post_items_by_id_merge
summary: 'Merge this local item into a survivor (design 3.6): every reference moves,
  the id answers 307 to the survivor afterwards. Refused for a live catalogue item.'
tags:
- Identity
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_item_id'
- $ref: '#/components/parameters/IdempotencyKeyRequired'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/MergeRequest'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenMerge'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-piece: M.11c

operationId: post_items_by_id_unmerge
summary: 'Undo a merge by its receipt (design 3.6): the merged id answers for itself
  again. Refused if a moved row changed since.'
tags:
- Identity
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_item_id'
- $ref: '#/components/parameters/IdempotencyKeyRequired'
requestBody:
  required: false
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/UnmergeRequest'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenMerge'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  default:
    $ref: '#/components/responses/Problem'
x-piece: M.11c

operationId: post_items_by_id_change_variant
summary: 'Change the variant (#151): everything owned of this catalogue item (loose
  stock, wishes, figure lines of copies with their part lists) moves to another item
  of the same kind, and BrickLink''s number becomes the other item''s preferred link.
  One event; Undo puts every row back. Refused for a merged item, another kind, a
  set, a job in flight, and rows that would meet on a key.'
tags:
- Identity
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_item_id'
- $ref: '#/components/parameters/IdempotencyKeyRequired'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/ChangeVariantRequest'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenVariantChange'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-piece: M.11c

operationId: post_items_by_id_build
summary: 'Build it (#9): make a copy of this set from the loose stock, moving the
  matching parts and whole figures into it; one event, Undo puts the stock back and
  archives the copy.'
description: 'Builds one copy of the set from the catalogue''s latest Rebrickable
  part list: every part line and whole figure the chosen stock covers is moved out
  of it into the copy (the largest usable row first, then the lowest id), the rest
  is recorded as missing on the copy, and one `stock_transfer` row per move is kept.
  The stock is the one Build Scout counts (`GET /planning/build-scout`): damaged rows
  give nothing unless `damaged` is true. Refused with 422 for a set made of other
  sets, a set with no part list and sources that hold nothing the set needs. The event
  is `copy` / `make_from_stock`; Undo (`POST /events/{id}/undo`) puts the stock back
  and archives the copy, and is refused when the copy or the stock changed since.'
tags:
- Copies
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_item_id'
- $ref: '#/components/parameters/IdempotencyKeyRequired'
requestBody:
  required: false
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/BuildFromStockRequest'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenBuild'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-piece: M.11c

operationId: post_copies_by_id_inventory
summary: 'Switch the copy''s part list in place (design 4.4): to Rebrickable (a version)
  or BrickLink. A BrickLink switch is pending until its fetch job lands.'
tags:
- Copies
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/IdempotencyKeyRequired'
- $ref: '#/components/parameters/IfMatch'
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/CopyInventorySwitch'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenCopy'
  '202':
    description: 'Pending: the BrickLink list is being fetched (the Job is data.inventory.pending).'
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenCopy'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  '412':
    $ref: '#/components/responses/PreconditionFailed'
  '422':
    $ref: '#/components/responses/Invalid'
  default:
    $ref: '#/components/responses/Problem'
x-piece: M.11c

operationId: delete_copies_by_id_inventory_pending
summary: 'Cancel a pending BrickLink switch (design 4.4): the copy keeps its current
  list.'
tags:
- Copies
security:
- bearerAuth:
  - write
parameters:
- $ref: '#/components/parameters/Path_id'
- $ref: '#/components/parameters/IdempotencyKey'
responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/WrittenCopy'
  '404':
    $ref: '#/components/responses/NotFound'
  '409':
    $ref: '#/components/responses/Conflict'
  default:
    $ref: '#/components/responses/Problem'
x-piece: M.11c