ARCNM Remnants API

openapi: 3.2.0
info:
  title: Arcnm Io Remnants API
  version: 0.1.0
  description: 'Operations tagged remnants across 2 of this provider''s published API definitions: openapi-public.json, arcnm-io-openapi.yml. Each path carries the servers of the definition it was published in.'
security:
- ApiKeyAuth: []
- OAuth2PasswordBearer: []
tags:
- name: remnants
paths:
  /api/v1/remnants:
    get:
      tags:
      - remnants
      summary: List Remnants
      description: 'Your organization''s remnants, newest first.


        A plain array: the page position travels in the `Link`,

        `X-Next-Cursor` and `X-Has-More` response headers.'
      operationId: remnants-list_remnants
      security:
      - ApiKeyAuth: []
      - OAuth2PasswordBearer: []
      parameters:
      - name: env_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: 'Only this environment''s remnants. A filter narrows the list: an id that matches no environment of your organization lists nothing.'
          title: Env Id
        description: 'Only this environment''s remnants. A filter narrows the list: an id that matches no environment of your organization lists nothing.'
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - enum:
            - available
            - reserved
            - consumed
            - scrapped
            type: string
          - type: 'null'
          description: Only remnants in this state; every state when omitted.
          title: Status
        description: Only remnants in this state; every state when omitted.
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Opaque position token from the previous page's `next_cursor` (or the `Link` / `X-Next-Cursor` response header). Omit it for the first page. Keep every other query parameter identical for the whole walk — a cursor replayed against different filters is rejected.
          title: Cursor
        description: Opaque position token from the previous page's `next_cursor` (or the `Link` / `X-Next-Cursor` response header). Omit it for the first page. Keep every other query parameter identical for the whole walk — a cursor replayed against different filters is rejected.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 500
          minimum: 1
          description: Maximum rows to return in one page.
          default: 200
          title: Limit
        description: Maximum rows to return in one page.
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: X-Org-Slug
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Org-Slug
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RemnantPublic'
                title: Response Remnants-List Remnants
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - remnants
      summary: Create Remnant
      description: 'State a remnant your shop holds.


        A job nest in that environment cuts parts of its material and

        thickness from it before it buys a sheet.'
      operationId: remnants-create_remnant
      security:
      - ApiKeyAuth: []
      - OAuth2PasswordBearer: []
      parameters:
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: X-Org-Slug
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Org-Slug
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RemnantCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RemnantPublic'
        '422':
          description: The environment or the material grade is not one of your organization's (`remnant_unresolved`).
  /api/v1/remnants/{remnant_id}/scrap:
    post:
      tags:
      - remnants
      summary: Scrap Remnant
      description: 'Take a remnant out of stock — sold, thrown away, or cut by hand.


        It stays on record, so a job nest that used or left it still names

        it. Scrapping part of a stack of one size takes out that many pieces.'
      operationId: remnants-scrap_remnant
      security:
      - ApiKeyAuth: []
      - OAuth2PasswordBearer: []
      parameters:
      - name: remnant_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Remnant Id
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: X-Org-Slug
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Org-Slug
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/RemnantScrap'
              - type: 'null'
              title: Payload
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RemnantPublic'
        '404':
          description: No remnant with this id in your organization (`remnant_not_found`).
        '409':
          description: 'The remnant is not in stock: a job nest holds it while it runs, or it was consumed or scrapped already, or fewer pieces are in stock than you named (`remnant_not_in_stock`).'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/remnants/by-code/{code}:
    get:
      tags:
      - remnants
      summary: Find Remnant By Code
      description: 'The remnant a scanned or typed label code names.


        Any state: a scanned piece that was consumed or scrapped is still

        found, and its `status` says so.'
      operationId: remnants-find_remnant_by_code
      security:
      - ApiKeyAuth: []
      - OAuth2PasswordBearer: []
      parameters:
      - name: code
        in: path
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 40
          description: The code a label carries — the first 12 hexadecimal digits of the remnant's id — or the whole id. Case does not matter.
          title: Code
        description: The code a label carries — the first 12 hexadecimal digits of the remnant's id — or the whole id. Case does not matter.
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: X-Org-Slug
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Org-Slug
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RemnantPublic'
        '404':
          description: No remnant with this id in your organization (`remnant_not_found`).
        '409':
          description: More than one remnant of your organization begins with this code — scan or type more of the id (`remnant_code_ambiguous`).
        '422':
          description: 'The code is not a remnant code: hexadecimal digits of the id, at least 8 of them, or the whole id (`remnant_code_invalid`).'
  /api/v1/remnants/{remnant_id}/label:
    get:
      tags:
      - remnants
      summary: Remnant Label
      description: 'The remnant''s rack label: size, thickness, material, pieces, origin

        and date, with a Code 128 barcode of its code.


        Print it at 100 %: the SVG is sized in millimetres. The barcode reads

        back through `GET /remnants/by-code/{code}`.'
      operationId: remnants-remnant_label
      security:
      - ApiKeyAuth: []
      - OAuth2PasswordBearer: []
      parameters:
      - name: remnant_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Remnant Id
      - name: lang
        in: query
        required: false
        schema:
          enum:
          - de
          - en
          type: string
          description: The label's language.
          default: de
          title: Lang
        description: The label's language.
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: X-Org-Slug
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Org-Slug
      responses:
        '200':
          description: The rack label, an SVG at true size (100 × 50 mm).
          content:
            image/svg+xml: {}
        '404':
          description: No remnant with this id in your organization (`remnant_not_found`).
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/nest-runs/{run_id}/remnant-labels:
    get:
      tags:
      - remnants
      summary: Nest Run Remnant Labels
      description: 'Rack labels for the rests a released job nest put into stock, one

        per row in one SVG sized in millimetres — print it when the sheets

        come off the cutter.'
      operationId: remnants-nest_run_remnant_labels
      security:
      - ApiKeyAuth: []
      - OAuth2PasswordBearer: []
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Run Id
      - name: lang
        in: query
        required: false
        schema:
          enum:
          - de
          - en
          type: string
          description: The labels' language.
          default: de
          title: Lang
        description: The labels' language.
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: X-Org-Slug
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Org-Slug
      responses:
        '200':
          description: One label per rest the released job nest put into stock.
          content:
            image/svg+xml: {}
        '402':
          description: An assembly calculation ran this job nest for its own sheet components, and your organization has no active Nesting add-on (`addon_required`).
        '404':
          description: No job nest with this id in your organization (`nest_run_not_found`), or it put no rest into stock — not released, or its sheets leave no reusable rest (`nest_run_no_rests`).
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    RemnantScrap:
      properties:
        quantity:
          anyOf:
          - type: integer
            maximum: 10000.0
            minimum: 1.0
          - type: 'null'
          title: Quantity
          description: Pieces to take out of stock; all of them when omitted.
      additionalProperties: false
      type: object
      title: RemnantScrap
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    RemnantPublic:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        env_id:
          type: string
          format: uuid
          title: Env Id
          description: The costing environment that holds it.
        length_mm:
          type: number
          title: Length Mm
          description: Longer edge, in millimetres.
        width_mm:
          type: number
          title: Width Mm
          description: Shorter edge, in millimetres.
        gauge_mm:
          type: number
          title: Gauge Mm
          description: Thickness, in millimetres.
        material_grade_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Material Grade Id
          description: The material grade; null when the remnant is stated for a whole material category.
        material_category:
          anyOf:
          - type: string
          - type: 'null'
          title: Material Category
          description: The material category.
        quantity:
          type: integer
          title: Quantity
          description: Pieces of this size.
        status:
          type: string
          enum:
          - available
          - reserved
          - consumed
          - scrapped
          title: Status
          description: '`available`: in stock. `reserved`: held by a job nest while it runs. `consumed`: cut into parts by a job nest. `scrapped`: taken out of stock.'
        origin_group_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Origin Group Id
          description: The job nest group whose sheet left it; null for a remnant you stated.
        reserved_by_run_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Reserved By Run Id
          description: The job nest that holds or consumed it.
        created_at:
          type: string
          format: date-time
          title: Created At
        consumed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Consumed At
          description: When it left stock — consumed or scrapped.
      type: object
      required:
      - id
      - env_id
      - length_mm
      - width_mm
      - gauge_mm
      - material_grade_id
      - material_category
      - quantity
      - status
      - origin_group_id
      - reserved_by_run_id
      - created_at
      - consumed_at
      title: RemnantPublic
      description: 'Rectangular rests of one thickness and material in one environment''s

        stock.'
    RemnantCreate:
      properties:
        env_id:
          type: string
          format: uuid
          title: Env Id
        length_mm:
          type: number
          maximum: 20000.0
          minimum: 10.0
          title: Length Mm
        width_mm:
          type: number
          maximum: 20000.0
          minimum: 10.0
          title: Width Mm
        gauge_mm:
          type: number
          maximum: 1000.0
          exclusiveMinimum: 0.0
          title: Gauge Mm
        material_grade_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Material Grade Id
        material_category:
          anyOf:
          - $ref: '#/components/schemas/MaterialCategory'
          - type: 'null'
        quantity:
          type: integer
          maximum: 10000.0
          minimum: 1.0
          title: Quantity
          default: 1
      additionalProperties: false
      type: object
      required:
      - env_id
      - length_mm
      - width_mm
      - gauge_mm
      title: RemnantCreate
      description: 'A remnant your shop holds: its size, thickness and material, in one

        environment. Name the material by grade, or by category.'
    MaterialCategory:
      type: string
      enum:
      - carbon_steel
      - alloy_steel
      - stainless_steel
      - tool_steel
      - cast_iron
      - aluminium
      - copper_alloy
      - nickel_alloy
      - titanium_alloy
      - magnesium_alloy
      - zinc_alloy
      - thermoplastic
      - thermoset
      - elastomer
      - composite
      - other
      title: MaterialCategory
      description: 'Top-level material family. Drives ISO machining group defaults and

        UI filtering. Values are stable identifiers — adding a new category is

        additive; renaming is a breaking change.'
  securitySchemes:
    OAuth2PasswordBearer:
      type: oauth2
      flows:
        password:
          scopes: {}
          tokenUrl: /api/v1/sessions/login
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'Server-to-server API key in the ``X-API-Key`` header, e.g. ``ak_live_…``. See the Authentication guide. Do not send it as ``Authorization: Bearer`` — that header is reserved for session / MCP JWTs.'
x-refined-from:
- openapi-public.json
- arcnm-io-openapi.yml