ai& Files API

openapi: 3.2.0
info:
  title: ai& Files 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: Files
paths:
  /v1/files:
    post:
      operationId: uploadFile
      tags:
      - Files
      summary: Upload a file
      description: Multipart form upload.
      requestBody:
        description: The file bytes plus optional purpose hint
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CreateFileRequest'
      responses:
        '200':
          description: The uploaded file's metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileObject'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
    get:
      operationId: listFiles
      tags:
      - Files
      summary: List files
      description: Returns files in reverse-chronological order (newest first).
      responses:
        '200':
          description: Paginated list of files
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v1/files/{id}:
    get:
      operationId: getFile
      tags:
      - Files
      summary: Retrieve a file
      description: Returns metadata for a single file.
      responses:
        '200':
          description: The file's metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileObject'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      parameters:
      - schema:
          type: string
        in: path
        name: id
        required: true
    delete:
      operationId: deleteFile
      tags:
      - Files
      summary: Delete a file
      description: Soft-deletes the file row and best-effort removes the underlying stored object.
      responses:
        '200':
          description: The deleted file marker
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileDeleted'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      parameters:
      - schema:
          type: string
        in: path
        name: id
        required: true
  /v1/files/{id}/content:
    get:
      operationId: getFileContent
      tags:
      - Files
      summary: Download file content
      description: Returns the raw bytes with `Content-Type` and `Content-Disposition` headers set from the upload metadata.
      responses:
        '200':
          description: The file bytes
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      parameters:
      - schema:
          type: string
        in: path
        name: id
        required: true
components:
  schemas:
    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
    FileList:
      type: object
      properties:
        object:
          type: string
          const: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/FileObject'
        has_more:
          type: boolean
        first_id:
          type:
          - string
          - 'null'
        last_id:
          type:
          - string
          - 'null'
      required:
      - object
      - data
      - has_more
      - first_id
      - last_id
    CreateFileRequest:
      type: object
      properties:
        file:
          type: string
          format: binary
          description: The asset bytes (multipart/form-data field)
        purpose:
          type: string
          enum:
          - vision
          - video
          - audio
          - document
          description: One of `vision`, `video`, `audio`, or `document`. Determines size + mime limits and which models can reference the file. Optional — if omitted, inferred from the file's MIME type.
      required:
      - file
    FileDeleted:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          const: file
        deleted:
          type: boolean
          description: Always true on a successful delete
      required:
      - id
      - object
      - deleted
    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
  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>'