openapi: 3.0.3
info:
  title: DocMake - AI Document Assistant API
  description: |
    AI-powered document processing API. Convert, merge, compress, split, summarize, analyze, and generate documents. Free tier with 10 API calls/day. Pro tier with 500 calls/day.

    ## Features
    - **Convert**: PDF↔Word, PDF↔Excel, PDF↔PPTX, PDF↔CSV, PDF↔EPUB, Image→PDF
    - **Combine**: Merge multiple files into one PDF, DOCX, XLSX, PPTX, or EPUB
    - **Split**: Split PDFs by page ranges
    - **Compress**: Reduce file sizes with smart compression
    - **Watermark**: Add text watermarks to documents
    - **Protect**: Add password protection to PDFs
    - **Summarize**: AI-powered document summarization with multiple levels
    - **Analyze**: AI data analysis with 13 analysis types (stats, anomalies, predictions, insights)
    - **Generate**: AI document generation from natural language descriptions
    - **Chat**: AI conversational assistant for document-related tasks
    - **Search**: Web search integration
    - **Slides**: AI presentation generation from documents

    ## Authentication
    - **Free tier**: 10 API calls/day, no API key required
    - **Pro tier**: 500 API calls/day, requires `X-API-Key` header

    ## Pricing
    - Free: GHS 0 (10 calls/day)
    - Pay as you go: From GHS 20 (extra Makes)
    - Developer: GHS 50/month (500 calls/day)
    - Business: GHS 100/month (500 calls/day + priority)
  version: 1.0.0
  contact:
    name: DocMake Support
    email: mireku.dev@gmail.com
    url: https://docmake.online
  license:
    name: Proprietary
    url: https://docmake.online/terms

servers:
  - url: https://docmake.online
    description: Production

tags:
  - name: Auth
    description: Authentication and API key management
  - name: Convert
    description: File format conversion
  - name: Process
    description: Document processing (combine, split, compress, watermark, protect)
  - name: AI
    description: AI-powered features (summarize, analyze, generate, chat, slides)
  - name: Batch
    description: Batch operations
  - name: Usage
    description: Usage tracking and pricing info

paths:
  /api/auth/signup:
    post:
      tags: [Auth]
      summary: Create account
      description: Create a new DocMake account. Requires email verification before sign-in.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password, name]
              properties:
                email:
                  type: string
                  format: email
                password:
                  type: string
                  minLength: 6
                name:
                  type: string
      responses:
        '200':
          description: Account created, verification email sent
        '400':
          description: Email already in use or validation error

  /api/auth/signin:
    post:
      tags: [Auth]
      summary: Sign in
      description: Sign in with email/password. Email must be verified first.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password]
              properties:
                email:
                  type: string
                password:
                  type: string
      responses:
        '200':
          description: Sign in successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  idToken:
                    type: string
                  email:
                    type: string
                  name:
                    type: string
                  tier:
                    type: string
                    enum: [free, pro]
                  dailyLimit:
                    type: integer
        '403':
          description: Email not verified
        '401':
          description: Invalid credentials

  /api/auth/me:
    get:
      tags: [Auth]
      summary: Get current user
      security:
        - apiKeyAuth: []
      responses:
        '200':
          description: User info
          content:
            application/json:
              schema:
                type: object
                properties:
                  email:
                    type: string
                  name:
                    type: string
                  tier:
                    type: string
                  dailyLimit:
                    type: integer

  /api/auth/forgot-password:
    post:
      tags: [Auth]
      summary: Request password reset
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email]
              properties:
                email:
                  type: string
      responses:
        '200':
          description: Reset email sent (always returns success)

  /api/convert:
    post:
      tags: [Convert]
      summary: Convert file format
      description: |
        Convert a file to a different format. Supports: PDF, DOCX, XLSX, PPTX, CSV, TXT, PNG, JPG, EPUB.
        Costs 1 Make per file.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file, output]
              properties:
                file:
                  type: string
                  format: binary
                  description: Input file
                output:
                  type: string
                  enum: [pdf, docx, xlsx, pptx, csv, txt, png, jpg, epub]
                  description: Target format
      responses:
        '200':
          description: Converted file (binary download)
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '402':
          description: Insufficient Makes

  /api/combine:
    post:
      tags: [Process]
      summary: Combine multiple files
      description: "Combine multiple files into one. Supports output (PDF, DOCX, XLSX, PPTX, EPUB). Costs 1 Make per input file."
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [files, output]
              properties:
                files:
                  type: array
                  items:
                    type: string
                    format: binary
                  description: Input files (2+)
                output:
                  type: string
                  enum: [pdf, docx, xlsx, pptx, epub]
                  description: Output format
      responses:
        '200':
          description: Combined file
        '402':
          description: Insufficient Makes

  /api/split:
    post:
      tags: [Process]
      summary: Split PDF
      description: Split a PDF into multiple files. Costs 1 Make.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
                  format: binary
                pages:
                  type: string
                  description: Page ranges (e.g., "1-5, 10, 15-20"). Empty = split all.
      responses:
        '200':
          description: Split files

  /api/compress:
    post:
      tags: [Process]
      summary: Compress file
      description: Reduce file size. Supports any file type. Costs 1 Make.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: Compressed file

  /api/watermark:
    post:
      tags: [Process]
      summary: Add watermark
      description: Add a text watermark to a document. Costs 2 Makes.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file, text]
              properties:
                file:
                  type: string
                  format: binary
                text:
                  type: string
                  description: Watermark text
      responses:
        '200':
          description: Watermarked file

  /api/protect:
    post:
      tags: [Process]
      summary: Password-protect PDF
      description: Add password protection to a PDF. Costs 1 Make.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file, password]
              properties:
                file:
                  type: string
                  format: binary
                password:
                  type: string
      responses:
        '200':
          description: Protected PDF

  /api/sign:
    post:
      tags: [Process]
      summary: Sign PDF
      description: Add signatures, initials, dates, or text to a PDF. Costs 2 Makes.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [file_path, elements]
              properties:
                file_path:
                  type: string
                elements:
                  type: array
                  items:
                    type: object
                    properties:
                      type:
                        type: string
                        enum: [signature, initial, date, text]
                      text:
                        type: string
                      page:
                        type: integer
                      x:
                        type: number
                        description: X position (0-100 percent)
                      y:
                        type: number
                        description: Y position (0-100 percent)
                      color:
                        type: string
                        default: "#000000"
      responses:
        '200':
          description: Signed PDF

  /api/summarize:
    post:
      tags: [AI]
      summary: AI summarize
      description: |
        AI-powered document summarization. Supports multiple summary levels:
        - bullets: Key points as bullet list
        - paragraph: Coherent paragraph summary
        - executive: High-level executive summary
        - detailed: Comprehensive detailed summary

        Costs 2 Makes.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
                  format: binary
                level:
                  type: string
                  enum: [bullets, paragraph, executive, detailed]
                  default: bullets
      responses:
        '200':
          description: Summary result
          content:
            application/json:
              schema:
                type: object
                properties:
                  summary:
                    type: string
                  level:
                    type: string
                  word_count:
                    type: integer

  /api/analyze:
    post:
      tags: [AI]
      summary: AI data analysis
      description: |
        AI-powered data analysis. Supports any data file (CSV, Excel, JSON, PDF, images with OCR, etc.).
        Automatically detects 13 analysis types: stats, correlations, anomalies, trends, predictions, clusters, comparisons, distributions, outliers, missing_data, time_series, what_if, insights.

        Costs 2 Makes.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
                  format: binary
                query:
                  type: string
                  description: Specific analysis question (optional)
                analysis_type:
                  type: string
                  description: Force specific analysis type (optional, auto-detected if omitted)
      responses:
        '200':
          description: Analysis result
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                  type:
                    type: string
                  confidence:
                    type: number

  /api/chat:
    post:
      tags: [AI]
      summary: AI chat
      description: |
        Conversational AI assistant. Ask questions about documents, get help with tasks, or just chat.
        The AI can generate documents, search the web, and answer questions.

        Costs 1 Make per message.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [message]
              properties:
                message:
                  type: string
                  description: Your message or question
                file_paths:
                  type: array
                  items:
                    type: string
                  description: Optional file paths for context
                tone:
                  type: string
                  enum: [professional, simple, casual, technical]
                  default: professional
      responses:
        '200':
          description: AI response
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: string
                  tools_used:
                    type: array
                    items:
                      type: string

  /api/generate:
    post:
      tags: [AI]
      summary: AI document generation
      description: |
        Generate documents from natural language. Create PDFs, DOCX, PPTX with AI.
        Just describe what you want and AI creates it.

        Costs: base 2 Makes + 1 per 10 pages.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [prompt]
              properties:
                prompt:
                  type: string
                  description: Describe what document to create
                format:
                  type: string
                  enum: [pdf, docx, pptx]
                  default: pdf
                pages:
                  type: integer
                  description: Approximate page count (AI decides if omitted)
                tone:
                  type: string
                  enum: [professional, simple, casual, technical]
                  default: professional
      responses:
        '200':
          description: Generated document
          content:
            application/json:
              schema:
                type: object
                properties:
                  result_path:
                    type: string
                  pages:
                    type: integer
                  message:
                    type: string

  /api/slides:
    post:
      tags: [AI]
      summary: AI presentation generation
      description: |
        Generate presentation slides from documents. AI reads your files and creates
        a professional presentation with images.

        Costs 3 Makes.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [files]
              properties:
                files:
                  type: array
                  items:
                    type: string
                    format: binary
                purpose:
                  type: string
                  description: What is this presentation for?
                num_slides:
                  type: integer
                  description: Number of slides (3-30, or let AI decide)
      responses:
        '200':
          description: Presentation file

  /api/search:
    post:
      tags: [AI]
      summary: Web search
      description: |
        Search the web for current information. Returns relevant results for any query.
        Costs 1 Make.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [query]
              properties:
                query:
                  type: string
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        title:
                          type: string
                        url:
                          type: string
                        snippet:
                          type: string

  /api/batch/convert:
    post:
      tags: [Batch]
      summary: Batch convert files
      description: |
        Convert multiple files at once. Each file is converted separately and all results
        are packaged in a zip. Costs 1 Make per file.

        Requires uploading files first via /api/upload, then calling this endpoint with session_id.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [session_id, output]
              properties:
                session_id:
                  type: string
                  description: Session ID from file upload
                output:
                  type: string
                  enum: [pdf, docx, xlsx, pptx, csv, txt, png, jpg, epub]
      responses:
        '200':
          description: Zip file with converted files

  /api/batch/combine:
    post:
      tags: [Batch]
      summary: Combine files
      description: |
        Combine multiple files into one. Costs 1 Make per input file.

        Requires uploading files first via /api/upload, then calling this endpoint with session_id.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [session_id, output]
              properties:
                session_id:
                  type: string
                output:
                  type: string
                  enum: [pdf, docx, xlsx, pptx, epub]
      responses:
        '200':
          description: Combined file

  /api/makes/limits:
    get:
      tags: [Usage]
      summary: Get Makes limits
      description: Get your current Makes balance, daily limit, and usage stats.
      responses:
        '200':
          description: Makes info
          content:
            application/json:
              schema:
                type: object
                properties:
                  tier:
                    type: string
                  dailyLimit:
                    type: integer
                  usedToday:
                    type: integer
                  remaining:
                    type: integer

  /api/makes/costs:
    get:
      tags: [Usage]
      summary: Get Makes cost table
      description: Get the Makes cost for each operation.
      responses:
        '200':
          description: Cost table
          content:
            application/json:
              schema:
                type: object
                properties:
                  costs:
                    type: object
                    description: Operation name → Makes cost

  /api/keys:
    get:
      tags: [Auth]
      summary: List API keys
      description: List all your API keys (Pro tier only).
      security:
        - apiKeyAuth: []
      responses:
        '200':
          description: API keys list
          content:
            application/json:
              schema:
                type: object
                properties:
                  keys:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        prefix:
                          type: string
                        expires:
                          type: string
                        created:
                          type: string
                        last_used:
                          type: string

  /api/keys/generate:
    post:
      tags: [Auth]
      summary: Generate API key
      description: Generate a new API key. Pro tier only. Key is shown once.
      security:
        - apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Optional label for this key
                expiry:
                  type: string
                  enum: [1d, 7d, 30d, 90d, 1y, never]
                  default: never
      responses:
        '200':
          description: API key (shown once)
          content:
            application/json:
              schema:
                type: object
                properties:
                  key:
                    type: string
                    description: Full API key (shown once only)
                  prefix:
                    type: string
                  expires:
                    type: string

  /api/tools/{action}:
    post:
      tags: [Convert]
      summary: Process file (browser parity)
      description: |
        Same as browser tools but for API callers. Accepts file upload with action-specific options.
        Actions: convert, split, compress, rotate, protect, unlock, watermark, lossless, epub
      parameters:
        - name: action
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
                  format: binary
                output:
                  type: string
                password:
                  type: string
                pages:
                  type: string
                text:
                  type: string
      responses:
        '200':
          description: Processed file

  /health:
    get:
      summary: Health check
      responses:
        '200':
          description: Service status

components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: "API key for Pro tier (500 calls/day). Get one at https://docmake.online after signing in. Free tier (10 calls/day) needs no key."

  schemas:
    Error:
      type: object
      properties:
        detail:
          type: string
        error:
          type: string