openapi: 3.0.1
info:
  title: Chunkr Files API
  description: The Chunkr Cloud API turns complex documents (PDF, Office, images) into RAG- and LLM-ready data. It exposes asynchronous parse and extract tasks that run layout analysis, OCR, segmentation, and chunking, plus file management and utility endpoints. Tasks are created and then polled until they reach a terminal status. Authentication uses an API key passed in the Authorization header.
  termsOfService: https://chunkr.ai/terms
  contact:
    name: Chunkr Support
    url: https://chunkr.ai
  license:
    name: AGPL-3.0 (open-source release) / Commercial (Cloud)
    url: https://github.com/lumina-ai-inc/chunkr/blob/main/LICENSE
  version: '1.0'
servers:
- url: https://api.chunkr.ai
  description: Chunkr Cloud API
- url: https://localhost:8000
  description: Self-hosted (Docker Compose) deployment
security:
- apiKey: []
tags:
- name: Files
  description: Upload and manage files referenced by tasks.
paths:
  /files:
    post:
      operationId: uploadFile
      tags:
      - Files
      summary: Upload a file
      description: Uploads a file that can later be referenced from a parse or extract task via a ch://files/{file_id} reference.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: File uploaded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileResponse'
    get:
      operationId: listFiles
      tags:
      - Files
      summary: List files
      description: Returns a paginated list of uploaded files.
      parameters:
      - name: page
        in: query
        schema:
          type: integer
          default: 1
      - name: limit
        in: query
        schema:
          type: integer
          default: 10
      responses:
        '200':
          description: A list of files.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FileResponse'
  /files/{file_id}:
    get:
      operationId: getFile
      tags:
      - Files
      summary: Get a file
      parameters:
      - $ref: '#/components/parameters/FileId'
      responses:
        '200':
          description: The file record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileResponse'
    delete:
      operationId: deleteFile
      tags:
      - Files
      summary: Delete a file
      parameters:
      - $ref: '#/components/parameters/FileId'
      responses:
        '200':
          description: File deleted.
  /files/{file_id}/download:
    get:
      operationId: downloadFileContent
      tags:
      - Files
      summary: Download file content
      parameters:
      - $ref: '#/components/parameters/FileId'
      responses:
        '200':
          description: The file content.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
  /files/{file_id}/url:
    get:
      operationId: getFileUrl
      tags:
      - Files
      summary: Get a file URL
      description: Returns a presigned URL for the stored file.
      parameters:
      - $ref: '#/components/parameters/FileId'
      responses:
        '200':
          description: A presigned URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
components:
  parameters:
    FileId:
      name: file_id
      in: path
      required: true
      description: The unique identifier of the file.
      schema:
        type: string
  schemas:
    FileResponse:
      type: object
      properties:
        file_id:
          type: string
        file_name:
          type: string
        mime_type:
          type: string
        size:
          type: integer
        created_at:
          type: string
          format: date-time
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization
      description: 'API key issued from the Chunkr dashboard, sent as the raw value of the Authorization header (e.g. "Authorization: lu_...").'