openapi: 3.0.3
info:
  title: Deckrun Free API
  version: 1.0.0
  description: |
    Free tier of the Deckrun slide-generation API. No authentication required.

    POST Markdown to /free/generate and receive a public PDF URL.
    Slide separator: \n---\n
    Maximum 10 slides, 50 KB per request.

    To generate a slide deck:
    1. Write Markdown where each slide is separated by a line containing only "---".
    2. POST {"markdown": "..."} to /free/generate.
    3. On success, open the returned "url" to download your PDF.

    The PDF is hosted on Google Cloud Storage and expires after 90 days.
  contact:
    name: Agentic Decks
    url: https://agenticdecks.com/contact
    email: hello@agenticdecks.com
  license:
    name: Deckrun API Terms
    url: https://agenticdecks.com/terms

servers:
  - url: https://free.agenticdecks.com
    description: Free tier (no auth; /free/generate only)

paths:
  /free/generate:
    post:
      operationId: freeGenerate
      summary: Generate a PDF slide deck from Markdown
      description: |
        Accepts Markdown with slides separated by `---` on its own line.
        Renders a 16:9 PDF using the default Deckrun theme.
        No authentication required. Maximum 10 slides, 50 KB input.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FreeGenerateRequest'
            example:
              markdown: |
                # My Presentation

                Introduction slide content.

                ---

                # Slide Two

                - Bullet point one
                - Bullet point two

                ---

                # Conclusion

                Summary and next steps.
      responses:
        '200':
          description: PDF generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FreeGenerateResponse'
              example:
                url: "https://storage.googleapis.com/deckrun-free-artifacts-deckrun-free-tier/abc123/deck.pdf"
                slug: "abc123"
        '413':
          description: Input too large (more than 10 slides or exceeds 50 KB)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: INPUT_TOO_LARGE
                  message: "Input exceeds maximum allowed size (10 slides / 50 KB)"
        '422':
          description: Markdown could not be parsed or rendered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal generation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /health:
    get:
      operationId: healthCheck
      summary: Service health check
      description: Returns 200 if the service is running.
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok

components:
  schemas:
    FreeGenerateRequest:
      type: object
      required:
        - markdown
      properties:
        markdown:
          type: string
          description: |
            Slide deck in Markdown format. Slides are separated by a line containing
            only "---". Maximum 10 slides and 50 KB total.
          maxLength: 51200
          example: "# Title Slide\n\nIntroduction\n\n---\n\n# Slide Two\n\n- Point one\n- Point two"
        schema_version:
          type: string
          description: |
            Optional. Declare which Deckrun format version the Markdown targets.
            Send "deckrun.v1". Echoed back in the response.
          example: "deckrun.v1"

    FreeGenerateResponse:
      type: object
      required:
        - url
        - slug
      properties:
        url:
          type: string
          format: uri
          description: Public URL of the generated PDF. Expires after 90 days.
          example: "https://storage.googleapis.com/deckrun-free-artifacts-deckrun-free-tier/abc123/deck.pdf"
        slug:
          type: string
          description: Unique identifier for this generation job.
          example: "abc123"
        slides:
          type: integer
          minimum: 1
          description: Number of slides in the generated deck.
          example: 6
        warnings:
          type: array
          items:
            type: string
          description: |
            Non-fatal notices about the generation. Agents should inspect and
            self-correct on subsequent requests if possible.
          example:
            - "Title-slide layout tag missing from first slide; rendered with default layout."
        schema_version:
          type: string
          description: Echoed from the request, or "deckrun.v1" if not provided.
          example: "deckrun.v1"

    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code.
              example: INPUT_TOO_LARGE
            message:
              type: string
              description: Human-readable error description.
              example: "Input exceeds maximum allowed size (10 slides / 50 KB)"
