ARCNM Uploads API

openapi: 3.2.0
info:
  title: Arcnm Io Uploads API
  version: 0.1.0
  description: 'Operations tagged uploads 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: Uploads
paths:
  /api/v1/uploads/presign:
    post:
      tags:
      - Uploads
      summary: Presign
      description: 'Start a direct file upload: answers where and how to send the file.


        Send the file to `url` the way `method` says — `PUT`: the raw bytes as

        the body, with the `headers` named; `POST`: a multipart form with every

        `fields` entry, then the file as the last field, named `file` — and then

        call `POST /uploads/confirm`. Until it is confirmed, the upload reserves

        its declared `size_bytes` (the most its file type allows, when none is

        declared) of the plan''s storage; if `url` expires with no file sent, the

        reservation is released. This is the upload path for a file of any size,

        and the one a client that can only send JSON (every MCP client) uses:

        the multipart upload routes cannot carry a file in a JSON argument.'
      operationId: uploads-presign
      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/PresignRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PresignResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/uploads/confirm:
    post:
      tags:
      - Uploads
      summary: Confirm
      description: 'Finish a direct upload once the file is sent: checks and keeps it.


        Answers the upload''s id and its `status`. The file is checked after this

        call answers, so a first confirm answers `pending`; the upload can be

        attached to a part revision

        (``POST /parts/{part_id}/revisions/{revision_id}/datasets``) once it is

        `confirmed`. Confirming again is safe and answers the current status.

        A confirm before the file has arrived answers 409 `upload_not_received`

        (send the file the way presign''s `method` says, then confirm again); an

        upload that was refused, could not be checked or was cancelled answers

        409 `upload_rejected`, `upload_failed` or `upload_cancelled`.'
      operationId: uploads-confirm
      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/ConfirmRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfirmResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/uploads/:
    get:
      tags:
      - Uploads
      summary: List Uploads
      description: 'List the org''s uploads, newest first, hiding cancelled rows by default.


        Cancelled uploads are useless — the file may have been written to

        storage but the download endpoint refuses to serve it (status gate

        is ``confirmed`` only). They just clutter the picker, so the UI gets

        them filtered out unless an admin explicitly opts in via

        ``?include_cancelled=true`` (e.g. for an audit view).


        The response is a plain array, so the page position travels in the

        `Link` (RFC 8288) and `X-Next-Cursor` / `X-Has-More` response headers:

        follow `Link rel="next"` until it stops being sent.'
      operationId: uploads-list_uploads
      security:
      - ApiKeyAuth: []
      - OAuth2PasswordBearer: []
      parameters:
      - name: include_cancelled
        in: query
        required: false
        schema:
          type: boolean
          description: Include cancelled uploads in the list (hidden by default).
          default: false
          title: Include Cancelled
        description: Include cancelled uploads in the list (hidden by default).
      - 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: order
        in: query
        required: false
        schema:
          enum:
          - asc
          - desc
          type: string
          description: 'Sort direction over the collection''s ordering key. Use `asc` to reconcile a batch: rows come oldest-first, so work created while you page lands after your position instead of shifting rows under it.'
          default: desc
          title: Order
        description: 'Sort direction over the collection''s ordering key. Use `asc` to reconcile a batch: rows come oldest-first, so work created while you page lands after your position instead of shifting rows under it.'
      - name: created_after
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: Only rows created at or after this instant (RFC 3339, e.g. `2026-07-20T09:00:00Z`). Inclusive.
          title: Created After
        description: Only rows created at or after this instant (RFC 3339, e.g. `2026-07-20T09:00:00Z`). Inclusive.
      - name: created_before
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: Only rows created strictly before this instant (RFC 3339). Exclusive, so an `after`/`before` pair tiles a range without overlap.
          title: Created Before
        description: Only rows created strictly before this instant (RFC 3339). Exclusive, so an `after`/`before` pair tiles a range without overlap.
      - 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/DataSourcePublic'
                title: Response Uploads-List Uploads
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/uploads/{data_source_id}/cancel:
    post:
      tags:
      - Uploads
      summary: Cancel Upload
      description: 'Mark a pending upload as ``cancelled``.


        Idempotent for already-cancelled rows; rejects rows that have moved

        past ``pending`` since cancelling a confirmed file would silently

        delete a valid artefact.'
      operationId: uploads-cancel_upload
      security:
      - ApiKeyAuth: []
      - OAuth2PasswordBearer: []
      parameters:
      - name: data_source_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Data Source 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/DataSourcePublic'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/uploads/{data_source_id}/retry:
    post:
      tags:
      - Uploads
      summary: Retry Upload
      description: Re-queue the confirm worker for a non-confirmed upload.
      operationId: uploads-retry_upload
      security:
      - ApiKeyAuth: []
      - OAuth2PasswordBearer: []
      parameters:
      - name: data_source_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Data Source 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/DataSourcePublic'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/uploads/bulk-cancel:
    post:
      tags:
      - Uploads
      summary: Bulk Cancel Uploads
      description: 'Cancel many pending uploads at once.


        Per-row failures are reported in ``skipped`` so the UI can render a

        summary toast — the whole batch isn''t rolled back if a single id is

        already confirmed. The batch size is capped on ``BulkUploadIds``.'
      operationId: uploads-bulk_cancel_uploads
      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/BulkUploadIds'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkUploadResult'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/uploads/bulk-retry:
    post:
      tags:
      - Uploads
      summary: Bulk Retry Uploads
      description: 'Re-queue processing for several uploads at once, for example after a failure.

        Uploads that cannot be retried or are busy are listed in `skipped` with the

        reason.'
      operationId: uploads-bulk_retry_uploads
      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/BulkUploadIds'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkUploadResult'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/uploads/{data_source_id}:
    patch:
      tags:
      - Uploads
      summary: Update Upload
      description: 'Rename an upload and/or move it to a folder.


        The folder lives in ``metadata_json["folder"]`` — sending ``folder: null``

        clears it, omitting the field leaves it untouched (``model_fields_set``

        distinguishes the two). Renaming changes the display name only; the

        storage key is immutable once presigned.'
      operationId: uploads-update_upload
      security:
      - ApiKeyAuth: []
      - OAuth2PasswordBearer: []
      parameters:
      - name: data_source_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Data Source 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/UploadUpdateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSourcePublic'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Uploads
      summary: Delete Upload
      description: 'Delete an upload: storage object (best-effort) plus the row.


        ``part_revision_dataset.data_source_id`` carries ``ondelete=CASCADE``,

        so any part/revision attachments of this file are removed with it —

        the UI warns about exactly that before calling here. An upload URL

        cannot be revoked: a file still sent through it after the delete is

        removed once the URL has expired.'
      operationId: uploads-delete_upload
      security:
      - ApiKeyAuth: []
      - OAuth2PasswordBearer: []
      parameters:
      - name: data_source_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Data Source 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/Message'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/uploads/bulk-delete:
    post:
      tags:
      - Uploads
      summary: Bulk Delete Uploads
      description: 'Delete many uploads at once.


        Mirrors bulk-cancel: per-row failures land in ``skipped`` instead of

        rolling back the batch; the batch size is capped on ``BulkUploadIds``.'
      operationId: uploads-bulk_delete_uploads
      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/BulkUploadIds'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkUploadDeleteResult'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/uploads/{data_source_id}/download-url:
    get:
      tags:
      - Uploads
      summary: Download Url
      description: 'Get a short-lived link to download the original file of a processed upload. An

        upload that is still processing or failed answers 404.'
      operationId: uploads-download_url
      security:
      - ApiKeyAuth: []
      - OAuth2PasswordBearer: []
      parameters:
      - name: data_source_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Data Source 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/DownloadUrlResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    PresignResponse:
      properties:
        data_source_id:
          type: string
          format: uuid
          title: Data Source Id
          description: Identifier of the data source record; pass it to /uploads/confirm.
        url:
          type: string
          title: Url
          description: Presigned URL to send the file to, as `method` says.
        method:
          type: string
          enum:
          - PUT
          - POST
          title: Method
          description: 'How to send the file to `url`. `PUT`: the file''s raw bytes as the request body, with exactly the `headers` named. `POST`: a `multipart/form-data` form with every entry of `fields` as a form field, followed by the file itself as the last field, named `file`. Always branch on this value: a file sent the other way is refused by storage and never arrives.'
        headers:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Headers
          description: Headers to send with a `PUT`; null for a `POST`.
        fields:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Fields
          description: Form fields to send, verbatim, ahead of the file in a `POST`; null for a `PUT`.
        expires_in:
          type: integer
          title: Expires In
          description: Seconds until `url` stops accepting the file.
      type: object
      required:
      - data_source_id
      - url
      - method
      - expires_in
      title: PresignResponse
    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
    ConfirmRequest:
      properties:
        data_source_id:
          type: string
          format: uuid
          title: Data Source Id
          description: UUID of the presigned upload to validate and ingest.
      additionalProperties: false
      type: object
      required:
      - data_source_id
      title: ConfirmRequest
    ConfirmResponse:
      properties:
        data_source_id:
          type: string
          format: uuid
          title: Data Source Id
          description: 'UUID of the confirmed upload, as presign returned it: the handle it is listed by in GET /uploads, with its status, and attached to a revision by.'
        status:
          type: string
          enum:
          - pending
          - confirmed
          title: Status
          description: '`pending`: the file arrived and is being checked; attaching it now answers 409 `upload_pending` with `Retry-After`, and calling confirm again answers the current status. `confirmed`: the file was checked and kept, and can be attached to a part revision.'
      type: object
      required:
      - data_source_id
      - status
      title: ConfirmResponse
    Message:
      properties:
        message:
          type: string
          title: Message
      type: object
      required:
      - message
      title: Message
    BulkUploadIds:
      properties:
        ids:
          items:
            type: string
            format: uuid
          type: array
          maxItems: 200
          minItems: 1
          title: Ids
          description: Upload (data source) IDs to cancel or retry in bulk (1–200).
      additionalProperties: false
      type: object
      required:
      - ids
      title: BulkUploadIds
      description: 'Payload for bulk-cancel / bulk-retry.


        Bounded on the model, like ``BulkCalculationRequest``, so the limit is

        part of the published schema and a client sees which field was wrong —

        rather than a bare 400 from a check the OpenAPI spec never mentioned.'
    UploadUpdateRequest:
      properties:
        folder:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Folder
          description: Folder name to file this upload under; null clears the folder.
        name:
          anyOf:
          - type: string
            maxLength: 255
          - type: 'null'
          title: Name
          description: New filename for the upload; omit to keep the current name.
      additionalProperties: false
      type: object
      title: UploadUpdateRequest
    DataSourcePublic:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: Unique identifier of the uploaded data source.
        name:
          type: string
          title: Name
          description: Original filename of the uploaded file.
        content_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Content Type
          description: MIME type of the file (e.g. 'application/pdf'); null if unknown.
        size_bytes:
          anyOf:
          - type: integer
          - type: 'null'
          title: Size Bytes
          description: Size of the file in bytes; null until the upload is confirmed.
        sha256:
          anyOf:
          - type: string
          - type: 'null'
          title: Sha256
          description: Hex-encoded SHA-256 checksum of the file; null until confirmed.
        status:
          type: string
          title: Status
          description: 'Upload lifecycle state: pending, confirmed, rejected (refused when checked: content not of its declared type, larger than declared, or past the plan''s storage), failed, or cancelled.'
        created_at:
          type: string
          format: date-time
          title: Created At
          description: ISO 8601 timestamp when the upload record was created.
        folder:
          anyOf:
          - type: string
          - type: 'null'
          title: Folder
          description: User-assigned folder name for organising files; null if unfiled.
        system_folder:
          anyOf:
          - type: string
          - type: 'null'
          title: System Folder
          description: 'Folder assigned by the platform: ''parts_uploads'' for files that belong to a part, revision, or calculation workflow; null otherwise.'
        linked_datasets:
          type: integer
          title: Linked Datasets
          description: Number of part revision dataset attachments that reference this file.
          default: 0
        failure_reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Failure Reason
          description: Why the upload check failed or refused the file, as a reason code (e.g. 'object_missing' when no file ever arrived, 'content_type_magic_mismatch' when the bytes are not of the declared type); null unless status is failed or rejected.
      type: object
      required:
      - id
      - name
      - status
      - created_at
      title: DataSourcePublic
    BulkUploadDeleteResult:
      properties:
        deleted:
          items:
            type: string
            format: uuid
          type: array
          title: Deleted
          description: Upload IDs that were successfully deleted.
        skipped:
          items:
            additionalProperties:
              type: string
            type: object
          type: array
          title: Skipped
          description: Uploads that were skipped, each as ``{id, reason}``.
      type: object
      title: BulkUploadDeleteResult
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PresignRequest:
      properties:
        name:
          type: string
          title: Name
          description: Original filename of the file to upload.
        content_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Content Type
          description: MIME type of the file (e.g. application/pdf).
        size_bytes:
          anyOf:
          - type: integer
          - type: 'null'
          title: Size Bytes
          description: Size of the file in bytes, if known. Until the upload is confirmed it reserves this much of the plan's storage (the most its file type allows, when omitted), and a larger file is refused.
      additionalProperties: false
      type: object
      required:
      - name
      title: PresignRequest
    BulkUploadResult:
      properties:
        cancelled:
          items:
            type: string
            format: uuid
          type: array
          title: Cancelled
          description: Upload IDs that were successfully cancelled.
        retried:
          items:
            type: string
            format: uuid
          type: array
          title: Retried
          description: Upload IDs that were successfully re-queued for confirmation.
        skipped:
          items:
            additionalProperties:
              type: string
            type: object
          type: array
          title: Skipped
          description: Uploads that were skipped, each as ``{id, reason}``.
      type: object
      title: BulkUploadResult
    DownloadUrlResponse:
      properties:
        url:
          type: string
          title: Url
          description: Short-lived presigned URL to download the confirmed file.
      type: object
      required:
      - url
      title: DownloadUrlResponse
  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