openapi: 3.1.0
info:
  title: Simplebooklet Public API
  version: 1.0.0
  description: |
    Simplebooklet converts PDFs into hosted, interactive HTML flipbooks that are
    publicly accessible via a unique URL. This API lets an AI agent or any
    external service upload a PDF on behalf of a user and return a URL the user
    can open in a browser to complete account setup and flipbook creation.

    ## Two-step flow

    1. **Upload** — POST a PDF to `/api/api/upload`. The server stores it
       temporarily and returns a `url` the user must open in their browser.
    2. **Convert** — The user opens the returned `url` in a browser, logs in or
       creates a free Simplebooklet account, and the flipbook conversion starts
       automatically. The finished flipbook is then available at a permanent
       public URL on `simplebooklet.com`.

    ## Notes for AI agents

    - Step 1 (upload) requires no authentication and can be called server-side
      or from an MCP tool.
    - Step 2 (convert) is a browser redirect — surface the `url` to the human
      user rather than following it programmatically.
    - Uploaded files are stored temporarily. If the user never visits the convert
      URL the file will eventually be cleaned up.

servers:
  - url: https://simplebooklet.com
    description: Production

paths:
  /api/api/upload:
    post:
      operationId: uploadPdf
      summary: Upload a PDF for flipbook conversion
      description: |
        Accepts a PDF file via multipart form upload. The file is validated by
        MIME type (not filename), stored under a unique key, and a one-time
        convert URL is returned. Surface this URL to the user so they can open
        it in a browser to complete account setup and start the flipbook
        conversion.

        No authentication is required on this endpoint. CORS is open so it can
        be called from any origin including MCP tools and browser-based clients.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: The PDF file to convert. Must have MIME type `application/pdf`.
      responses:
        '200':
          description: File accepted. Open the returned `url` in a browser to proceed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  message:
                    type: string
                    example: File uploaded
                  data:
                    type: object
                    properties:
                      url:
                        type: string
                        format: uri
                        description: |
                          The convert URL. Open this in the user's browser. The
                          user will be prompted to log in or sign up, after which
                          flipbook conversion begins automatically.
                        example: https://simplebooklet.com/api/api/convert/aBcDeFgHiJkLmNoPqRsTuV
        '200-error':
          description: |
            Errors are also returned as HTTP 200 with `status` set to `error`.
            Check `status` in the response body, not the HTTP status code.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/api/convert/{key}:
    get:
      operationId: convertPdf
      summary: Complete flipbook conversion (browser redirect)
      description: |
        Browser-facing endpoint. The user opens this URL in their browser after
        receiving it from the upload response.

        - If the user is not logged in they are redirected to the Simplebooklet
          sign-up page and then back here after authentication.
        - Once authenticated the pending PDF is moved into the user's account,
          a conversion job is queued, and the user is redirected to their
          Simplebooklet dashboard where the conversion preview dialog opens.

        This endpoint is intended for human browser navigation, not programmatic
        HTTP calls. AI agents should surface the URL to the user rather than
        following it themselves.

        An optional `title` query parameter pre-fills the booklet title.
      parameters:
        - name: key
          in: path
          required: true
          description: The unique upload key returned by the upload endpoint.
          schema:
            type: string
            pattern: '^[0-9a-zA-Z]{22}$'
            example: aBcDeFgHiJkLmNoPqRsTuV
        - name: title
          in: query
          required: false
          description: Optional title to pre-fill for the new flipbook.
          schema:
            type: string
            maxLength: 255
            example: Q3 Product Catalogue
      responses:
        '302':
          description: |
            Redirects to `/signup.php` if unauthenticated, or to
            `/dashboard.php` once the conversion job is queued.
        '200':
          description: |
            Error responses (invalid key, file not found, etc.) are returned as
            JSON with `status` set to `error`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        status:
          type: string
          example: error
        message:
          type: string
          example: Uploaded file must be a PDF