openapi.yaml

openapi: 3.1.0
info:
  title: OPF Service API Reference
  version: "1.0.0"
  description: |
    Reference REST API shape for downstream services that parse, validate, convert, generate, or render presentations with OPF.
    OPF (Open Presentation Format) is the JSON contract; schema URL: `https://openpresentation.org/schema/opf/v1`.

    OpenPresentation does not host this API. Implementers may use this contract as a starting point for their own hosted services, internal tools, or self-hosted deployments.

    **Authentication:** Send `Authorization: Bearer <token>` on authenticated requests. `POST /v1/preview` is shown as an optional unauthenticated preview endpoint for services that choose to expose one.
  contact:
    name: OpenPresentation
    url: https://openpresentation.org
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://api.example.com
    description: Downstream service endpoint
  - url: http://localhost:3000/api
    description: Example local development endpoint

tags:
  - name: playground
    description: Optional unauthenticated OPF preview helpers
  - name: validate
    description: OPF schema validation
  - name: parse
    description: Upload and inspect .pptx files
  - name: convert
    description: PPTX to OPF
  - name: generate
    description: OPF to PPTX and exports
  - name: render
    description: PPTX to web or raster/vector previews

security:
  - bearerAuth: []

paths:
  /v1/validate:
    post:
      operationId: validateOpf
      tags: [validate]
      summary: Validate OPF JSON
      description: Validates an OPF document against the schema. Returns structured errors and warnings.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OpfDocument"
            examples:
              minimal:
                summary: Minimal OPF
                value:
                  $schema: "https://openpresentation.org/schema/opf/v1"
                  meta:
                    title: Example
                  design:
                    theme: corporate-minimal
                  slides:
                    - id: s1
                      layout: title-slide
                      elements:
                        - id: h1
                          type: text
                          content:
                            text: Hello
      responses:
        "200":
          description: Validation result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidateResponse"
        "400":
          description: Bad request (wrong Content-Type or invalid JSON)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"

  /v1/preview:
    post:
      operationId: previewOpf
      tags: [playground]
      summary: OPF preview summary (anonymous)
      description: |
        Validates OPF JSON (body max 256 KB) for live preview without an API key.
        Per-IP limits: 30 requests/minute and 500/hour (separate fixed windows).
        `format=web` returns `textRuns` per slide (similar to `/v1/render?format=web`).
        `format=svg|png` returns `svg: null` per slide with an `export` stub until the engine ships.
      security: []
      parameters:
        - name: format
          in: query
          required: false
          schema:
            type: string
            enum: [web, svg, png]
            default: svg
          description: Preview representation
        - name: slides
          in: query
          required: false
          schema:
            type: string
          description: Comma-separated 1-based slide numbers (subset of slides to return)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OpfDocument"
      responses:
        "200":
          description: Valid OPF — preview payload (`slides` shape depends on `format`)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PreviewResponse"
        "400":
          description: Bad request (wrong Content-Type, invalid JSON, bad `format`/`slides`)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "413":
          description: Request body larger than 256 KB
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: OPF failed validation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          $ref: "#/components/responses/InternalError"

  /v1/parse:
    post:
      operationId: parsePptx
      tags: [parse]
      summary: Parse a .pptx upload
      description: Upload a `.pptx` file and receive a `parseId` for follow-up GET endpoints.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
                  format: binary
                  description: PowerPoint file (.pptx)
      responses:
        "200":
          description: Parse job created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ParseAcceptedResponse"
        "400":
          description: Missing file or not a .pptx
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"

  /v1/convert:
    post:
      operationId: convertPptxToOpf
      tags: [convert]
      summary: Convert .pptx to OPF JSON
      description: Reverse of `/v1/generate` — imports an existing deck as OPF.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
                  format: binary
      responses:
        "200":
          description: OPF document
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OpfDocument"
        "400":
          description: Missing file or not a .pptx
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"

  /v1/generate:
    post:
      operationId: generateFromOpf
      tags: [generate]
      summary: Generate output from OPF
      description: |
        Validates OPF, then enqueues or returns generation status. Query `format` selects the target
        (`pptx`, `pdf`, `png`, `svg`). The PPTX engine may return `202 Accepted` while work is stubbed or async.
      parameters:
        - name: format
          in: query
          required: false
          schema:
            type: string
            enum: [pptx, pdf, png, svg]
            default: pptx
          description: Output format
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OpfDocument"
      responses:
        "202":
          description: Accepted — generation stub or async pipeline
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenerateAcceptedResponse"
        "400":
          description: Invalid format or wrong Content-Type
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          description: OPF failed validation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          $ref: "#/components/responses/InternalError"

  /v1/render:
    post:
      operationId: renderPptx
      tags: [render]
      summary: Render a .pptx for web or export
      description: |
        Parses upload, stores result, and returns slide data (`format=web`) or an acceptance payload
        for raster/vector engines (`svg`, `png`).
      parameters:
        - name: format
          in: query
          required: false
          schema:
            type: string
            enum: [web, svg, png]
            default: web
        - name: slides
          in: query
          required: false
          schema:
            type: string
          description: Comma-separated 1-based slide numbers (e.g. `1,3,5`)
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
                  format: binary
      responses:
        "200":
          description: Web slide payload
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RenderWebResponse"
        "202":
          description: Export pipeline not ready — stub response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RenderAcceptedResponse"
        "400":
          description: Invalid format, slides, or missing file
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"

  /v1/parse/{parseId}/metadata:
    get:
      operationId: getParseMetadata
      tags: [parse]
      summary: Get document metadata for a parse
      parameters:
        - $ref: "#/components/parameters/ParseId"
      responses:
        "200":
          description: Metadata buckets (core, app, custom)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ParseMetadataResponse"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          description: Parse expired or unknown
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /v1/parse/{parseId}/slides/{index}:
    get:
      operationId: getParseSlide
      tags: [parse]
      summary: Get one slide by index
      parameters:
        - $ref: "#/components/parameters/ParseId"
        - name: index
          in: path
          required: true
          schema:
            type: integer
            minimum: 0
          description: Zero-based slide index
      responses:
        "200":
          description: Slide payload
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ParseSlideResponse"
        "400":
          description: Invalid index
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          description: Parse or slide not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /v1/parse/{parseId}/text:
    get:
      operationId: getParseAllText
      tags: [parse]
      summary: Get flattened text for all slides
      parameters:
        - $ref: "#/components/parameters/ParseId"
      responses:
        "200":
          description: Text per slide
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ParseTextResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          description: Parse expired or unknown
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Service-defined bearer token.

  parameters:
    ParseId:
      name: parseId
      in: path
      required: true
      schema:
        type: string
      description: Identifier returned by `POST /v1/parse` or `/v1/render`

  responses:
    Unauthorized:
      description: Missing or invalid credentials
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    InternalError:
      description: Server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"

  schemas:
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          $ref: "#/components/schemas/ApiError"

    ApiError:
      type: object
      required: [code, message, requestId]
      properties:
        code:
          type: string
          enum:
            - invalid_request
            - unauthorized
            - forbidden
            - not_found
            - rate_limited
            - idempotency_conflict
            - internal_error
        message:
          type: string
        details:
          type: object
          additionalProperties: true
          description: Optional structured details for the error code.
        requestId:
          type: string

    OpfDocument:
      type: object
      description: OPF v1 document. See https://openpresentation.org/schema/opf/v1 for the canonical schema.
      additionalProperties: true
      properties:
        $schema:
          type: string
          const: "https://openpresentation.org/schema/opf/v1"
        meta:
          type: object
          additionalProperties: true
        design:
          type: object
          additionalProperties: true
        slides:
          type: array
          items:
            type: object
            additionalProperties: true

    ValidationIssue:
      type: object
      required: [path, message]
      properties:
        path:
          type: string
        message:
          type: string

    ValidateResponse:
      type: object
      required: [valid, errors, warnings]
      properties:
        valid:
          type: boolean
        errors:
          type: array
          items:
            $ref: "#/components/schemas/ValidationIssue"
        warnings:
          type: array
          items:
            $ref: "#/components/schemas/ValidationIssue"

    PreviewWebSlide:
      type: object
      required: [index, slideNumber, id, layout, hidden, textRuns, speakerNotes]
      properties:
        index:
          type: integer
          minimum: 0
        slideNumber:
          type: integer
          minimum: 1
        id:
          type: string
        layout:
          type: string
        hidden:
          type: boolean
        textRuns:
          type: array
          items:
            type: object
            additionalProperties: true
        speakerNotes:
          type: string

    PreviewRasterSlide:
      type: object
      required: [index, slideNumber, id, layout, svg]
      properties:
        index:
          type: integer
          minimum: 0
        slideNumber:
          type: integer
          minimum: 1
        id:
          type: string
        layout:
          type: string
        svg:
          type: string
          nullable: true

    PreviewExportStub:
      type: object
      required: [status, message]
      properties:
        status:
          type: string
          example: accepted
        message:
          type: string

    PreviewResponse:
      type: object
      required: [status, format, slideCount, dimensions, meta, design, slides, warnings]
      properties:
        status:
          type: string
          example: ok
        format:
          type: string
          enum: [web, svg, png]
        slideCount:
          type: integer
          minimum: 0
        dimensions:
          type: object
          required: [widthPx, heightPx, preset]
          properties:
            widthPx:
              type: integer
            heightPx:
              type: integer
            preset:
              type: string
        meta:
          type: object
          required: [title]
          properties:
            title:
              type: string
            filename:
              type: string
              description: Suggested download filename including extension (resolved from meta.filename or title).
            subtitle:
              type: string
        design:
          type: object
          properties:
            theme:
              type: string
        export:
          $ref: "#/components/schemas/PreviewExportStub"
        slides:
          type: array
          items:
            oneOf:
              - $ref: "#/components/schemas/PreviewWebSlide"
              - $ref: "#/components/schemas/PreviewRasterSlide"
        warnings:
          type: array
          items:
            $ref: "#/components/schemas/ValidationIssue"

    ParseAcceptedResponse:
      type: object
      required: [parseId, slideCount, width, height]
      properties:
        parseId:
          type: string
        slideCount:
          type: integer
        width:
          type: integer
          description: Slide width in EMUs
        height:
          type: integer
          description: Slide height in EMUs

    GenerateAcceptedResponse:
      type: object
      required: [status, message, format, slideCount, validationWarnings]
      properties:
        status:
          type: string
          example: accepted
        message:
          type: string
        format:
          type: string
        filename:
          type: string
          description: Suggested output filename including extension (from meta.filename or title slug).
        slideCount:
          type: integer
        validationWarnings:
          type: array
          items:
            type: string

    TextRun:
      type: object
      additionalProperties: true
      properties:
        text:
          type: string
        bold:
          type: boolean
        italic:
          type: boolean
        underline:
          type: boolean
        fontSize:
          type: number
        fontFamily:
          type: string
        color:
          type: string
        alignment:
          type: string

    RenderWebResponse:
      type: object
      required: [parseId, format, dimensions, slideCount, slides, metadata, viewerUrl]
      properties:
        parseId:
          type: string
        format:
          type: string
          enum: [web]
        dimensions:
          type: object
          additionalProperties: true
        slideCount:
          type: integer
        slides:
          type: array
          items:
            type: object
            additionalProperties: true
        metadata:
          type: object
          additionalProperties: true
        viewerUrl:
          type: string
          description: Relative URL to the web viewer

    RenderAcceptedResponse:
      type: object
      required: [status, message, parseId, format, slideCount, viewerUrl]
      properties:
        status:
          type: string
          example: accepted
        message:
          type: string
        parseId:
          type: string
        format:
          type: string
        slideCount:
          type: integer
        viewerUrl:
          type: string

    ParseMetadataResponse:
      type: object
      required: [parseId, core, app, custom]
      properties:
        parseId:
          type: string
        core:
          type: object
          additionalProperties: true
        app:
          type: object
          additionalProperties: true
        custom:
          type: object
          additionalProperties: true

    ParseSlideResponse:
      type: object
      required: [index, slideNumber, hidden, width, height, textRuns]
      properties:
        index:
          type: integer
        slideNumber:
          type: integer
        hidden:
          type: boolean
        width:
          type: integer
        height:
          type: integer
        textRuns:
          type: array
          items:
            $ref: "#/components/schemas/TextRun"
        speakerNotes:
          type: string

    ParseTextResponse:
      type: object
      required: [parseId, slides]
      properties:
        parseId:
          type: string
        slides:
          type: array
          items:
            type: object
            additionalProperties: true