ai& Uploads API

openapi: 3.2.0
info:
  title: ai& Uploads API
  version: 1.0.0
  description: Unified spec covering inference, files, and other public surfaces. Drop-in compatible with OpenAI and Anthropic SDKs.
servers:
- url: https://api.aiand.com
  description: ai& API
security:
- bearerAuth: []
tags:
- name: Uploads
paths:
  /v1/uploads:
    post:
      operationId: createUpload
      tags:
      - Uploads
      summary: Create an upload session
      description: Creates a chunked upload session for files larger than the single-shot `/v1/files` cap. Sessions expire 1 hour after creation.
      requestBody:
        description: Upload metadata declared up front
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUploadRequest'
      responses:
        '200':
          description: The upload session in `pending` status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadObject'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/uploads/{id}/parts:
    post:
      operationId: addUploadPart
      tags:
      - Uploads
      summary: Add a part to an upload
      description: Uploads one part of a pending session. Parts are numbered in the order they arrive and assembled in that order. Every part except the last must be at least 5 MiB; no part may exceed 64 MB. A part larger than the declared `bytes`, or a first part under 5 MiB that is not the whole file, is refused with a 400.
      requestBody:
        description: Bytes for this part
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/AddUploadPartRequest'
      responses:
        '200':
          description: The part record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadPartObject'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
      - schema:
          type: string
        in: path
        name: id
        required: true
  /v1/uploads/{id}/complete:
    post:
      operationId: completeUpload
      tags:
      - Uploads
      summary: Complete an upload
      description: Assembles the listed parts and materializes the upload as a regular `file-...` object referenced via the returned `file` field. `part_ids` must follow upload order and sum to the declared `bytes`; any other order is refused with a 400 rather than reordered. Completing an already completed session returns the same `file`.
      requestBody:
        description: Ordered part_ids to assemble
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompleteUploadRequest'
      responses:
        '200':
          description: The completed upload, with `file` populated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadObject'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
      - schema:
          type: string
        in: path
        name: id
        required: true
  /v1/uploads/{id}/cancel:
    post:
      operationId: cancelUpload
      tags:
      - Uploads
      summary: Cancel an upload
      description: Aborts the underlying multipart upload and marks the session `cancelled`. Idempotent — already-completed or already-cancelled sessions return 404.
      responses:
        '200':
          description: The cancelled upload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadObject'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      parameters:
      - schema:
          type: string
        in: path
        name: id
        required: true
components:
  schemas:
    UploadObject:
      type: object
      properties:
        id:
          type: string
          description: Stable upload session id with `upload-` prefix
        object:
          type: string
          const: upload
        bytes:
          type: integer
          description: Declared total size of the file being uploaded
        created_at:
          type: integer
          description: Unix timestamp
        expires_at:
          type: integer
          description: Unix timestamp (1 hour from creation by default)
        filename:
          type:
          - string
          - 'null'
        purpose:
          type: string
          enum:
          - vision
          - video
          - audio
          - document
        status:
          type: string
          enum:
          - pending
          - completed
          - cancelled
          - expired
          - failed
        file:
          oneOf:
          - $ref: '#/components/schemas/FileObject'
          - type: 'null'
          description: Populated once status is `completed`
      required:
      - id
      - object
      - bytes
      - created_at
      - expires_at
      - filename
      - purpose
      - status
      - file
    FileObject:
      type: object
      properties:
        id:
          type: string
          description: Stable file id with `file-` prefix
        object:
          type: string
          const: file
        bytes:
          type: integer
        created_at:
          type: integer
          description: Unix timestamp
        expires_at:
          type:
          - integer
          - 'null'
          description: Unix timestamp; defaults to 30 days from upload
        filename:
          type:
          - string
          - 'null'
        purpose:
          type: string
          enum:
          - vision
          - video
          - audio
          - document
        page_count:
          type: integer
          description: Rendered page count; present only for `document` files
      required:
      - id
      - object
      - bytes
      - created_at
      - expires_at
      - filename
      - purpose
    UploadPartObject:
      type: object
      properties:
        id:
          type: string
          description: Stable part id with `part-` prefix
        object:
          type: string
          const: upload.part
        upload_id:
          type: string
        created_at:
          type: integer
          description: Unix timestamp
      required:
      - id
      - object
      - upload_id
      - created_at
    CreateUploadRequest:
      type: object
      properties:
        filename:
          type: string
        purpose:
          type: string
          enum:
          - vision
          - video
          - audio
          - document
        bytes:
          type: integer
          minimum: 0
          description: Declared total size in bytes; checked against `purpose` limits
        mime_type:
          type: string
          description: Mime type; checked against `purpose` allowlist
      required:
      - filename
      - purpose
      - bytes
      - mime_type
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            type:
              type: string
            param:
              type: string
            code:
              type: string
          required:
          - message
          - type
      required:
      - error
    CompleteUploadRequest:
      type: object
      properties:
        part_ids:
          type: array
          items:
            type: string
          minItems: 1
          description: Part ids returned by /parts, in the order the parts were uploaded. Their sizes must sum to the declared `bytes`.
        md5:
          type: string
          description: Optional MD5 of the assembled file
      required:
      - part_ids
    AddUploadPartRequest:
      type: object
      properties:
        data:
          type: string
          format: binary
          description: Bytes for this part (multipart/form-data field). Every part except the last must be at least 5 MiB; no part may exceed 64 MB.
      required:
      - data
  responses:
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'Authorization: Bearer <API_KEY>'