openapi: 3.2.0
info:
  title: xAI's REST Files API
  description: REST API for xAI compatible with other providers.
  license:
    name: ''
  version: 1.0.0
tags:
- name: Files
paths:
  /v1/files:
    get:
      tags:
      - Files
      summary: List files owned by the authenticated team, paginated.
      operationId: handle_list_files_request
      parameters:
      - name: limit
        in: query
        description: The maximum number of objects to be returned in a single response.
        required: false
        schema:
          type: integer
          format: int32
      - name: order
        in: query
        description: The ordering to sort the returned files. Use `asc` for ascending and `desc` for descending order.
        required: false
        schema:
          type: string
      - name: sort_by
        in: query
        description: 'The field to sort by. Valid options: `created_at`, `filename`, `size`. Defaults to `created_at`.'
        required: false
        schema:
          type: string
      - name: pagination_token
        in: query
        description: The pagination token returned by the previous list files request.
        required: false
        schema:
          type: string
      - name: after
        in: query
        description: Only included for compatibility. Use `pagination_token` instead.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListFilesResponse'
              example:
                data:
                - id: file_a128090d-f0c9-4873-bd84-e499777e7417
                  object: file
                  bytes: 12345
                  created_at: 1762345678
                  expires_at: null
                  filename: document.pdf
                  purpose: ''
                pagination_token: file_a128090d-f0c9-4873-bd84-e499777e7417
      security:
      - bearerAuth: []
    post:
      tags:
      - Files
      summary: Upload a file to xAI's storage.
      operationId: handle_upload_file_request
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/UploadFileMultipartRequest'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/File'
              example:
                id: file_a128090d-f0c9-4873-bd84-e499777e7417
                object: file
                bytes: 12345
                created_at: 1762345678
                expires_at: 1762432078
                filename: document.pdf
                purpose: ''
        '400':
          description: 'Bad request. Common causes: `expires_after` outside [3600, 2592000], `expires_after` field appearing after `file` in the multipart body, missing or unnamed `file` part, invalid filename.'
        '413':
          description: Payload too large -- file exceeds 50 MB.
      security:
      - bearerAuth: []
  /v1/files/{file_id}:
    get:
      tags:
      - Files
      summary: Retrieve metadata for a single file by ID.
      operationId: handle_retrieve_file_request
      parameters:
      - name: file_id
        in: path
        description: The file's `id` returned by upload or list.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/File'
        '404':
          description: File not found, deleted, or expired.
      security:
      - bearerAuth: []
    delete:
      tags:
      - Files
      summary: Delete a file by ID.
      operationId: handle_delete_file_request
      parameters:
      - name: file_id
        in: path
        description: The file's `id` to delete.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteFileResponse'
              example:
                id: file_a128090d-f0c9-4873-bd84-e499777e7417
                deleted: true
        '404':
          description: File not found or already deleted.
      security:
      - bearerAuth: []
  /v1/files/{file_id}/content:
    get:
      tags:
      - Files
      summary: Download the contents of a file as a stream of raw bytes.
      operationId: handle_download_file_content_request
      parameters:
      - name: file_id
        in: path
        description: The file's `id` to download.
        required: true
        schema:
          type: string
      - name: format
        in: query
        description: Format of the downloaded content.
        required: false
        schema:
          $ref: '#/components/schemas/ContentFormat'
      responses:
        '200':
          description: Success -- raw file bytes streamed in chunks.
          content:
            application/octet-stream:
              schema:
                type: string
        '404':
          description: File not found, deleted, or expired.
      security:
      - bearerAuth: []
components:
  schemas:
    UploadFileMultipartRequest:
      type: object
      description: 'Multipart form fields accepted by `POST /v1/files`. The `expires_after`

        field MUST appear before `file` in the multipart body when both are

        present (the upload handler streams `file` straight to gRPC and cannot

        rewind to read metadata after).'
      required:
      - file
      properties:
        expires_after:
          type:
          - integer
          - 'null'
          format: int64
          description: 'Optional TTL in seconds (measured from upload time). Must be between

            3600 (1 hour) and 2592000 (30 days). If unset the file does not expire.


            Accepts either a plain integer or the OpenAI SDK deepObject form

            (`expires_after[anchor]=created_at` + `expires_after[seconds]=N`)

            as separate multipart fields. The anchor+seconds form must arrive

            before the `file` part.'
        file:
          type: string
          format: binary
          description: 'The file to upload. The filename from the multipart

            `Content-Disposition: filename=` header is recorded as the file''s

            `filename`.'
        purpose:
          type:
          - string
          - 'null'
          description: 'Optional purpose label, accepted for OpenAI SDK compatibility. xAI

            does not enforce or interpret this field. Setting `"assistants"`

            is the conventional choice.'
    ListFilesResponse:
      type: object
      required:
      - data
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/File'
          description: List of files.
        pagination_token:
          type:
          - string
          - 'null'
          description: Pagination token to use with next request.
    ContentFormat:
      type: string
      description: Format of the downloaded file content.
      enum:
      - original
      - text
    File:
      type: object
      description: An uploaded file.
      required:
      - bytes
      - created_at
      - filename
      - id
      - object
      properties:
        bytes:
          type: integer
          format: int64
          description: The size of the file, in bytes.
        created_at:
          type: integer
          format: int64
          description: The Unix timestamp (in seconds) for file creation time.
        expires_at:
          type:
          - integer
          - 'null'
          format: int64
          description: The Unix timestamp (in seconds) for file expiry time. null if file does not expire.
        filename:
          type: string
          description: The name of the file.
        id:
          type: string
          description: The file identifier, which can be used in other API requests.
        object:
          type: string
          description: The object type, which is always `file`. Only included for compatability.
        purpose:
          type: string
          description: The intended purpose of the uploaded file. Only included for OAI compatability.
    DeleteFileResponse:
      type: object
      required:
      - id
      - deleted
      - object
      properties:
        deleted:
          type: boolean
          description: Whether the file was deleted.
        id:
          type: string
          description: The ID of the file.
        object:
          type: string
          description: The object type, which is always "file". Only included for compatibility.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer