ARCNM Machines API

openapi: 3.2.0
info:
  title: Arcnm Io Machines API
  version: 0.1.0
  description: 'Operations tagged machines 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: Machines
paths:
  /api/v1/machines/{machine_id}:
    get:
      tags:
      - Machines
      summary: One machine record, with the number of environments it is in
      description: 'The machine as its record states it — rates, class, capabilities — plus `environment_count`: how many of your costing environments hold it in their fleet today, which is how far an edit to its rates reaches.'
      operationId: machines-get_machine
      security:
      - ApiKeyAuth: []
      - OAuth2PasswordBearer: []
      parameters:
      - name: machine_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Machine 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
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MachinePublic'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Machines
      summary: Update Machine
      description: 'Change one of your machines: its name, machine class, hourly rates (machine,

        burden, programming, setup, operator) and capability overrides. Calculations run

        afterwards use the new values.'
      operationId: machines-update_machine
      security:
      - ApiKeyAuth: []
      - OAuth2PasswordBearer: []
      parameters:
      - name: machine_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Machine 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:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MachinePatch'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MachinePublic'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/machines/{machine_id}/usage:
    get:
      tags:
      - Machines
      summary: The costing environments whose fleet holds a machine
      description: A machine record is shared by every environment whose fleet holds it, so a change to its hourly rate moves every part priced on it in each of them. This says how many, and which, so a save from one calculation's cost sheet can state its scope before it writes.
      operationId: machines-get_machine_usage
      security:
      - ApiKeyAuth: []
      - OAuth2PasswordBearer: []
      parameters:
      - name: machine_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Machine 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
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MachineUsage'
        '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
    MachineUsageEnv:
      properties:
        env_id:
          type: string
          title: Env Id
          description: Identifier of the environment.
        env_name:
          type: string
          title: Env Name
          description: Human-readable environment name.
        is_enabled:
          type: boolean
          title: Is Enabled
          description: Whether the machine is active in that environment's fleet. Only enabled machines take part in calculations.
      type: object
      required:
      - env_id
      - env_name
      - is_enabled
      title: MachineUsageEnv
      description: One costing environment whose fleet holds this machine.
    MachineUsage:
      properties:
        machine_id:
          type: string
          title: Machine Id
          description: Identifier of the machine.
        environment_count:
          type: integer
          title: Environment Count
          description: Number of your costing environments whose fleet holds this machine today. An edit to the machine's own rate reaches every one of them.
        environments:
          items:
            $ref: '#/components/schemas/MachineUsageEnv'
          type: array
          title: Environments
          description: Those environments, enabled and disabled memberships alike.
      type: object
      required:
      - machine_id
      - environment_count
      - environments
      title: MachineUsage
      description: Where a machine record is in use — the scope of an edit to it.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    MachinePublic:
      properties:
        id:
          type: string
          title: Id
          description: Unique identifier of the machine definition.
        name:
          type: string
          title: Name
          description: Human-readable name of the machine.
        vendor:
          type: string
          title: Vendor
          description: Manufacturer or vendor of the machine.
        model_no:
          type: string
          title: Model No
          description: Vendor model number of the machine.
        library_entry_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Library Entry Id
          description: Machine-library entry this machine was instantiated from; null if bespoke.
        source:
          type: string
          title: Source
          description: '''library'' if instantiated from a catalog entry, else ''custom''.'
          default: custom
        klass:
          type: string
          title: Klass
          description: Machine class (e.g. milling, turning, laser_cutter).
        hourly_rate_eur:
          type: number
          title: Hourly Rate Eur
          description: Machine-hour rate in EUR per hour.
        burden_rate_eur:
          type: number
          title: Burden Rate Eur
          description: Overhead burden added on top of the machine-hour rate, in EUR per hour.
        programming_rate_eur:
          anyOf:
          - type: number
          - type: 'null'
          title: Programming Rate Eur
          description: Programming rate in EUR/h; null = the environment labour rate applies.
        environment_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Environment Count
          description: Number of your costing environments whose fleet holds this machine today — the scope of an edit to its rates. Present on `GET /machines/{machine_id}`; absent on fleet rows.
        setup_rate_eur:
          anyOf:
          - type: number
          - type: 'null'
          title: Setup Rate Eur
          description: Setup rate in EUR/h; null = the machine hourly rate applies.
        rate_operator_eur_per_h:
          type: number
          title: Rate Operator Eur Per H
          description: Operator wage already contained in hourly_rate_eur, in EUR per hour. 0 means the rate covers the machine only and operator labour is billed separately.
          default: 0.0
        rate_operator_share:
          anyOf:
          - type: number
          - type: 'null'
          title: Rate Operator Share
          description: Share of an operator this machine consumes while it runs (0-1); setup is always fully attended. Null falls back to the machine class default.
        capabilities:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Capabilities
          description: Raw stored capability matrix; empty for library-derived instances (see effective_capabilities).
        valid_from:
          type: string
          title: Valid From
          description: ISO date (YYYY-MM-DD) from which this machine definition is effective.
        valid_to:
          anyOf:
          - type: string
          - type: 'null'
          title: Valid To
          description: ISO date (YYYY-MM-DD) the machine stops being effective; null = open-ended.
      type: object
      required:
      - id
      - name
      - vendor
      - model_no
      - klass
      - hourly_rate_eur
      - burden_rate_eur
      - valid_from
      title: MachinePublic
      description: A machine in a costing environment.
    MachineClass:
      type: string
      enum:
      - milling.3axis_vmc
      - milling.5axis_full
      - milling.indexable_3plus2
      - turning.2axis_cnc
      - turning.live_tool
      - turning.swiss_type
      - turning.mill_integrex
      - press_brake
      - laser_cutter
      - plasma_cutter
      - guillotine_shear
      - tube_bender
      - turret_punch
      - waterjet
      - wire_edm
      - sinter.dmls
      - fdm_industrial
      - injection_molding_press
      - grinder.surface
      - grinder.cylindrical
      - slotter
      - sink_edm
      - weld_station
      - saw.band
      - saw.circular
      - drill.pillar
      title: MachineClass
    MachinePatch:
      properties:
        name:
          anyOf:
          - type: string
            maxLength: 255
          - type: 'null'
          title: Name
          description: New machine name; omit to leave.
        hourly_rate_eur:
          anyOf:
          - type: number
            maximum: 100000.0
            minimum: 0.0
          - type: 'null'
          title: Hourly Rate Eur
          description: New flat machine-hour rate in EUR/h; omit to leave.
        burden_rate_eur:
          anyOf:
          - type: number
            maximum: 100000.0
            minimum: 0.0
          - type: 'null'
          title: Burden Rate Eur
          description: Capital/overhead burden charged alongside the machine-hour rate in EUR/h, on run time and setup time alike; 0 = none. Omit to leave.
        programming_rate_eur:
          anyOf:
          - type: number
            maximum: 100000.0
            minimum: -1.0
          - type: 'null'
          title: Programming Rate Eur
          description: Programming rate in EUR/h; -1 clears it (fall back to the environment labour rate); omit to leave.
        setup_rate_eur:
          anyOf:
          - type: number
            maximum: 100000.0
            minimum: -1.0
          - type: 'null'
          title: Setup Rate Eur
          description: Setup rate in EUR/h; -1 clears it (fall back to the machine hourly rate); omit to leave.
        rate_operator_eur_per_h:
          anyOf:
          - type: number
            maximum: 100000.0
            minimum: 0.0
          - type: 'null'
          title: Rate Operator Eur Per H
          description: Operator wage already contained in hourly_rate_eur — and in setup_rate_eur, which is the same rate on the setup envelope — in EUR/h; omit to leave. 0 means the rate covers the machine only and operator labour is billed separately — the default. Set it when the rate is all-in, so the operator is not charged twice. It cannot exceed either rate it is declared inside.
        rate_operator_share:
          anyOf:
          - type: number
            maximum: 1.0
            minimum: 0.0
          - type: 'null'
          title: Rate Operator Share
          description: Share of an operator this machine consumes while it runs (0-1); omit to leave. Setup is always fully attended. Unset falls back to the machine class default.
        capability_overrides:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Capability Overrides
          description: Capability fields to change. For a library-derived machine these merge over the library default (sparse override); for a bespoke machine they merge into its own capability matrix.
        klass:
          anyOf:
          - $ref: '#/components/schemas/MachineClass'
          - type: 'null'
          description: Correct the machine's process class (e.g. a lathe entered from a milling template). The machine is re-based on the new class's standard capability matrix and detached from its catalogue entry, because that entry describes a different kind of machine; name, rates and fleet memberships are kept. Omit to leave.
      additionalProperties: false
      type: object
      title: MachinePatch
  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