ARCNM Import API

openapi: 3.2.0
info:
  title: Arcnm Io Import API
  version: 0.1.0
  description: 'Operations tagged import 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: Import
paths:
  /api/v1/import/machines/preview:
    post:
      tags:
      - Import
      summary: Preview Machine Import
      description: 'Preview a machine-park import: per row, the values as read, any

        errors, and what the import would do — create the machine and attach

        it, attach a machine you already have under that name, or skip one

        already in the environment. Nothing is written.'
      operationId: import-preview_machine_import
      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/MachineImportRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportReportPublic'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/import/machines:
    post:
      tags:
      - Import
      summary: Import Machines
      description: 'Import your machine park from CSV. Machines are created with their

        class''s standard capabilities (your envelope / spindle columns

        override them) at the rate you state, and attached to the target

        environment. Re-uploading the same file is safe: existing machines

        are recognised by name and never duplicated.'
      operationId: import-import_machines
      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/MachineImportRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportReportPublic'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/import/tools/preview:
    post:
      tags:
      - Import
      summary: Preview Tool Import
      description: 'Preview a tool-crib import: per row, the values as read (including

        the kind-specific properties), any errors, and what the import would

        do. Nothing is written.'
      operationId: import-preview_tool_import
      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/ToolImportRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportReportPublic'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/import/tools:
    post:
      tags:
      - Import
      summary: Import Tools
      description: 'Import your tool crib from CSV. Tools are created with their

        kind-specific properties validated (a saw blade needs its kerf and

        construction; rotating cutters need nothing extra) and attached to

        the target environment (your default one unless `env_id` names

        another). Re-uploading the same file is safe:

        existing tools are recognised by name and kind, never duplicated.'
      operationId: import-import_tools
      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/ToolImportRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportReportPublic'
        '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
    MachineImportRequest:
      properties:
        csv:
          type: string
          maxLength: 512000
          minLength: 1
          title: Csv
          description: 'The machine list as CSV text (headered; comma, semicolon or tab separated). Columns: name, class, hourly_rate_eur — plus optional operator_eur_per_h, envelope_x_mm / envelope_y_mm / envelope_z_mm, spindle_power_kw and priority. Header spellings are matched tolerantly; at most 500 data rows.'
        env_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Env Id
          description: Costing environment the machines join; omit for your default environment.
      additionalProperties: false
      type: object
      required:
      - csv
      title: MachineImportRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ImportRowPublic:
      properties:
        row:
          type: integer
          title: Row
          description: 1-based line number in the uploaded file.
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: The row's name, when one could be read.
        action:
          type: string
          enum:
          - create+attach
          - attach-existing-by-name
          - skip-duplicate
          - error
          title: Action
          description: 'What this row does (preview) or did (commit): create the item and attach it to the environment; attach an item you already have under this name; skip because it is already attached (or repeated in the file); or nothing, because the row has errors.'
        errors:
          items:
            type: string
          type: array
          title: Errors
          description: Why this row cannot be imported; empty when it can.
        id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Id
          description: The machine or tool this row maps to — the one that would be (or was) created or attached; null on error rows.
        parsed:
          additionalProperties: true
          type: object
          title: Parsed
          description: The values as read from the row, normalised.
      type: object
      required:
      - row
      - action
      title: ImportRowPublic
    ImportReportPublic:
      properties:
        applied:
          type: boolean
          title: Applied
          description: False for a preview (nothing written); true for a commit.
        env_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Env Id
          description: The costing environment the import targets; null in a preview when your organization has no default environment yet.
        total_rows:
          type: integer
          title: Total Rows
          description: Data rows read from the file.
        created:
          type: integer
          title: Created
          description: Rows that create (or would create) a new item.
        attached:
          type: integer
          title: Attached
          description: Rows that attach (or would attach) an existing item.
        skipped:
          type: integer
          title: Skipped
          description: Rows skipped as already present.
        errored:
          type: integer
          title: Errored
          description: Rows with errors; nothing happens for them.
        rows:
          items:
            $ref: '#/components/schemas/ImportRowPublic'
          type: array
          title: Rows
          description: Per-row detail, in file order.
      type: object
      required:
      - applied
      - total_rows
      - created
      - attached
      - skipped
      - errored
      - rows
      title: ImportReportPublic
    ToolImportRequest:
      properties:
        csv:
          type: string
          maxLength: 1000000
          minLength: 1
          title: Csv
          description: 'The tool list as CSV text (headered). Columns: name, kind — plus optional diameter_mm, teeth, cutting_material, price_eur, tool_life_min, vendor, item_no, coating, notes, and any kind-specific property as its own column (e.g. kerf_mm, blade_type and format for a saw blade, life_quantity for non-rotating tools). An empty cutting_material is read as carbide for every kind, saw blades included — state it (e.g. hss_e) for a tool that is not carbide. At most 1000 data rows.'
        env_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Env Id
          description: Costing environment the tools join; omit for your default environment.
      additionalProperties: false
      type: object
      required:
      - csv
      title: ToolImportRequest
  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