ARCNM Folders API

openapi: 3.2.0
info:
  title: Arcnm Io Folders API
  version: 0.1.0
  description: 'Operations tagged folders 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: Folders
paths:
  /api/v1/folders:
    get:
      tags:
      - Folders
      summary: List folders
      description: 'All folders for the org, each with its direct (non-recursive) part count.


        The tree is small enough to ship flat — the client assembles parent/child

        structure from ``parent_id``.'
      operationId: folders-list_folders
      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
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartFoldersPublic'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - Folders
      summary: Create a folder
      description: 'Create a folder for organising parts, at the top level or inside a parent

        folder. Folders that share a parent need distinct names.'
      operationId: folders-create_folder
      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/PartFolderCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartFolderPublic'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/folders/{folder_id}:
    get:
      tags:
      - Folders
      summary: Get a folder
      description: 'Fetch a single folder.


        Parts carry a ``folder_id``, so a client holding one previously had to

        list the whole tree to resolve it to a name.'
      operationId: folders-get_folder
      security:
      - ApiKeyAuth: []
      - OAuth2PasswordBearer: []
      parameters:
      - name: folder_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Folder 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/PartFolderPublic'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Folders
      summary: Rename or move a folder
      description: Rename a folder or move it under another parent folder.
      operationId: folders-update_folder
      security:
      - ApiKeyAuth: []
      - OAuth2PasswordBearer: []
      parameters:
      - name: folder_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Folder 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/PartFolderUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartFolderPublic'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Folders
      summary: Delete a folder
      description: 'Delete a folder and its subfolders. The parts inside are not deleted; they are

        left without a folder.'
      operationId: folders-delete_folder
      security:
      - ApiKeyAuth: []
      - OAuth2PasswordBearer: []
      parameters:
      - name: folder_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Folder 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/app__routes__folders__DeleteMessage'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/folders/move-parts:
    post:
      tags:
      - Folders
      summary: Move parts into a folder
      description: 'Move parts into a folder, or out of every folder when `folder_id` is null. Ids

        that are not found are listed in the result.'
      operationId: folders-move_parts
      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/MovePartsRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MovePartsResult'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/folders/summary:
    get:
      tags:
      - Folders
      summary: Workspace spend rollup
      description: Rollup over the entire workspace (all parts, filed or not).
      operationId: folders-workspace_summary
      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
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderSummaryPublic'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/folders/{folder_id}/summary:
    get:
      tags:
      - Folders
      summary: Folder spend rollup
      description: Rollup scoped to a folder and all of its subfolders.
      operationId: folders-folder_summary
      security:
      - ApiKeyAuth: []
      - OAuth2PasswordBearer: []
      parameters:
      - name: folder_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Folder 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/FolderSummaryPublic'
        '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
    PartFolderUpdate:
      properties:
        name:
          anyOf:
          - type: string
            maxLength: 128
          - type: 'null'
          title: Name
          description: New folder name.
        parent_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Parent Id
          description: New parent folder; null moves the folder to the workspace root.
      additionalProperties: false
      type: object
      title: PartFolderUpdate
    MovePartsResult:
      properties:
        moved:
          type: integer
          title: Moved
          description: Number of parts actually re-filed.
        requested:
          type: integer
          title: Requested
          description: Number of distinct part ids you asked about.
          default: 0
        not_found:
          items:
            type: string
            format: uuid
          type: array
          title: Not Found
          description: Ids that were skipped because no such part exists in this workspace, capped at 100 entries. Empty on a fully successful move. Compare ``moved`` against ``requested`` for the true count — that pair is never truncated.
      type: object
      required:
      - moved
      title: MovePartsResult
      description: 'What the move actually did — not what was asked for.


        ``moved`` can be lower than ``requested``: ids that do not exist, or belong

        to another workspace, are skipped. That used to be invisible, and the

        caller''s only honest option was to assume everything worked — which the

        bulk-upload remedy did, reporting "12 parts moved" from its own request

        length while the server had moved nine.'
    PartFolderPublic:
      properties:
        name:
          type: string
          maxLength: 128
          title: Name
          description: Folder name, shown in the workspace tree. Unique among its siblings.
        id:
          type: string
          format: uuid
          title: Id
          description: Unique identifier of the folder.
        parent_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Parent Id
          description: ID of the parent folder; null for a top-level folder.
        part_count:
          type: integer
          title: Part Count
          description: Number of parts filed directly in this folder (excludes subfolders).
          default: 0
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Timestamp when the folder was created (UTC, ISO 8601).
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: Timestamp when the folder was last updated (UTC, ISO 8601).
      type: object
      required:
      - name
      - id
      - created_at
      - updated_at
      title: PartFolderPublic
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    FolderSummaryPublic:
      properties:
        folder_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Folder Id
          description: The folder this rollup is scoped to; null means the whole workspace.
        part_count:
          type: integer
          title: Part Count
          description: Parts in this folder and all its subfolders.
          default: 0
        quoted_part_count:
          type: integer
          title: Quoted Part Count
          description: Parts in scope that have at least one succeeded calculation.
          default: 0
        calculation_count:
          type: integer
          title: Calculation Count
          description: Succeeded calculations counted in this rollup.
          default: 0
        total_annual_spend_eur:
          anyOf:
          - type: number
          - type: 'null'
          title: Total Annual Spend Eur
          description: Σ over scoped parts of (latest should-cost unit price × annual volume), in currency. Null when the scope holds more than one currency.
          default: 0.0
        potential_savings_eur:
          anyOf:
          - type: number
          - type: 'null'
          title: Potential Savings Eur
          description: Σ over scoped parts of the net annual saving of moving to the recommended (holding-aware) lot size, in currency — production plus inventory holding. Null when the scope holds more than one currency, or parts valued at the purchase price beside parts valued at the offer price (see effective_annual_cost_eur).
          default: 0.0
        effective_annual_cost_eur:
          anyOf:
          - type: number
          - type: 'null'
          title: Effective Annual Cost Eur
          description: 'Σ over scoped parts of the effective annual cost at the current lot — the purchase price after the supplier''s discounts where a cost sheet is stated, learning over the year and inventory holding — else the production spend, in currency. The denominator of a savings percentage. Null when the scope holds more than one currency, or when a calculation made before the purchase-price basis (valued at the offer price) sits beside one valued at the purchase price: the two are never summed.'
          default: 0.0
        currency:
          anyOf:
          - type: string
          - type: 'null'
          title: Currency
          description: 'Currency of the money totals: the one every quoted part in scope is priced in. Null when nothing in scope is quoted, or when the scope holds more than one currency (see currencies).'
        currencies:
          items:
            type: string
          type: array
          title: Currencies
          description: 'Every currency the quoted parts in scope are priced in, sorted. More than one means the money totals are null: amounts in different currencies are never summed.'
      type: object
      title: FolderSummaryPublic
      description: 'Scoped rollup over a folder''s whole subtree (or the entire workspace).


        Spend and savings are in ``currency`` — the currency every quoted part

        in scope is priced in, each figure on the basis of that part''s own

        calculated unit cost. Parts priced in different currencies have no

        common total: the money totals are then null and ``currencies`` names

        what the scope holds, rather than a sum across currencies under one

        label. Likewise, where one part''s lot-size figures are valued at the

        purchase price after discounts and another''s at the offer price (a

        calculation made before that basis), the savings and effective-cost

        totals are null rather than a sum across the two prices.'
    PartFoldersPublic:
      properties:
        data:
          items:
            $ref: '#/components/schemas/PartFolderPublic'
          type: array
          title: Data
          description: All folders for the org.
        count:
          type: integer
          title: Count
          description: Total number of folders.
      type: object
      required:
      - data
      - count
      title: PartFoldersPublic
    MovePartsRequest:
      properties:
        part_ids:
          items:
            type: string
            format: uuid
          type: array
          title: Part Ids
          description: Parts to (re-)file.
        folder_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Folder Id
          description: Destination folder; null unfiles the parts (moves them to the root).
      additionalProperties: false
      type: object
      required:
      - part_ids
      title: MovePartsRequest
    app__routes__folders__DeleteMessage:
      properties:
        message:
          type: string
          title: Message
      type: object
      required:
      - message
      title: DeleteMessage
    PartFolderCreate:
      properties:
        name:
          type: string
          maxLength: 128
          title: Name
          description: Folder name, shown in the workspace tree. Unique among its siblings.
        parent_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Parent Id
          description: ID of the parent folder; null creates a top-level folder.
      additionalProperties: false
      type: object
      required:
      - name
      title: PartFolderCreate
  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