openapi: 3.1.0
info:
  title: Dropbox File Access API
  description: |
    API to access and search files in Dropbox. Supports multiple Dropbox accounts.

    ## Authentication

    API key format: `{account}:{secret}`

    - `account`: The account identifier (matches config filename)
    - `secret`: The api_key from the account config

    Example: `domaza:a826c5461ef92f5f67c004c8ffdb80ab74ffb7b1b4d67789148af96a659dacdc`
  version: 1.4.0

servers:
  - url: https://demo1-php-mcp-dropbox.projects.domaza.net
    description: Production server

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: "API key in format: {account}:{secret}"

  schemas:
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          example: "Error message"

    FileEntry:
      type: object
      properties:
        name:
          type: string
          description: File or folder name
        path:
          type: string
          description: Full path in Dropbox
        type:
          type: string
          enum: [file, folder]
        size:
          type: integer
          description: File size in bytes (only for files)
        size_human:
          type: string
          description: Human-readable file size
        modified:
          type: string
          description: Last modification date

    AccountInfo:
      type: object
      properties:
        success:
          type: boolean
        account:
          type: object
          properties:
            name:
              type: string
            email:
              type: string
            account_type:
              type: string
            country:
              type: string
        storage:
          type: object
          properties:
            used:
              type: integer
            used_human:
              type: string
            allocated:
              type: integer
            allocated_human:
              type: string
            percent_used:
              type: number

security:
  - ApiKeyAuth: []

paths:
  /health:
    get:
      operationId: healthCheck
      summary: Health check
      description: Check if the API is running
      security: []
      responses:
        '200':
          description: API is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok

  /account:
    get:
      operationId: getAccountInfo
      summary: Get Dropbox account information
      description: Returns account details and storage usage information for the authenticated account
      responses:
        '200':
          description: Account information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountInfo'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /files:
    get:
      operationId: listFiles
      summary: List files and folders
      description: List all files and folders in a Dropbox directory
      parameters:
        - name: path
          in: query
          description: Path to the folder. Use empty string or "/" for root folder.
          required: false
          schema:
            type: string
            default: ""
        - name: recursive
          in: query
          description: If true, list all files recursively including subfolders
          required: false
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: List of files and folders
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  path:
                    type: string
                  count:
                    type: integer
                  entries:
                    type: array
                    items:
                      $ref: '#/components/schemas/FileEntry'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /files/info:
    get:
      operationId: getFileInfo
      summary: Get file or folder metadata
      description: Get detailed information about a specific file or folder without downloading it
      parameters:
        - name: path
          in: query
          description: Full path to the file or folder (e.g., "/documents/report.pdf")
          required: true
          schema:
            type: string
      responses:
        '200':
          description: File metadata
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  name:
                    type: string
                  path:
                    type: string
                  type:
                    type: string
                  size:
                    type: integer
                  size_human:
                    type: string
                  modified:
                    type: string
                  content_hash:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /files/read:
    get:
      operationId: readFile
      summary: Read text file contents
      description: Read and return the contents of a text file as JSON. Best for text files, code, configs, markdown, etc. Maximum 10MB file size. For binary files, use /files/download instead.
      parameters:
        - name: path
          in: query
          description: Full path to the file (e.g., "/documents/notes.txt")
          required: true
          schema:
            type: string
      responses:
        '200':
          description: File contents
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  path:
                    type: string
                  name:
                    type: string
                  size:
                    type: integer
                  modified:
                    type: string
                  content:
                    type: string
                    description: The text content of the file
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /files/download:
    get:
      operationId: downloadFile
      summary: Download file (binary support)
      description: Download a file from Dropbox with full binary support. Returns raw file content with appropriate Content-Type header. Use this for images, PDFs, documents, and other binary files.
      parameters:
        - name: path
          in: query
          description: Full path to the file (e.g., "/photos/image.jpg")
          required: true
          schema:
            type: string
      responses:
        '200':
          description: File content
          headers:
            Content-Type:
              description: MIME type of the file
              schema:
                type: string
            Content-Length:
              description: File size in bytes
              schema:
                type: integer
            Content-Disposition:
              description: Suggested filename
              schema:
                type: string
            X-File-Name:
              description: Original filename
              schema:
                type: string
            X-File-Path:
              description: Full path in Dropbox
              schema:
                type: string
            X-File-Size:
              description: File size in bytes
              schema:
                type: integer
            X-File-Modified:
              description: Last modification date
              schema:
                type: string
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /files/content:
    get:
      operationId: extractFileContent
      summary: Extract file content for AI processing
      description: "Extract content from files. Images (jpg/png/gif/webp) return base64 data URIs. PDFs and Office docs (docx/xlsx) return extracted text. Text files return content as-is. Limits: images/PDFs 20MB, Office 10MB."
      parameters:
        - name: path
          in: query
          description: Full path to the file (e.g., "/photos/image.jpg" or "/documents/report.pdf")
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Extracted content
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  path:
                    type: string
                  name:
                    type: string
                  size:
                    type: integer
                  size_human:
                    type: string
                  modified:
                    type: string
                  type:
                    type: string
                    enum: [image, pdf, docx, xlsx, text]
                    description: Type of content extracted
                  content_type:
                    type: string
                    description: MIME type (for images)
                  content:
                    type: string
                    description: Extracted content (base64 data URI for images, text for documents)
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /search:
    get:
      operationId: searchFiles
      summary: Search for files
      description: Search for files and folders in Dropbox by name or content
      parameters:
        - name: query
          in: query
          description: Search query string
          required: true
          schema:
            type: string
        - name: path
          in: query
          description: Path to search within. Empty for entire Dropbox.
          required: false
          schema:
            type: string
            default: ""
        - name: max_results
          in: query
          description: Maximum number of results to return
          required: false
          schema:
            type: integer
            default: 100
            minimum: 1
            maximum: 1000
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  query:
                    type: string
                  count:
                    type: integer
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        path:
                          type: string
                        type:
                          type: string
                        size:
                          type: integer
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'