slideforge-dev Deck API

openapi: 3.2.0
info:
  title: SlideForge Deck API
  description: 'Agent-first PowerPoint generation. Send structured slide intents (a `form` plus typed fields) or a brief; get back a real, editable `.pptx`. The draw path is deterministic — no model renders your slide, so supplied numbers and text come out verbatim. Every response carries `status`, `fidelity` and `warnings` so an automated caller can tell whether the output is usable. $0.05 per slide; an unusable slide is not billed. Authenticate with a SlideForge API key (`Authorization: Bearer sf_live_…` or `X-API-Key`) — new accounts include 60 free slides, no credit card: https://slideforge.dev/sign-up'
  version: 5.356.0
servers:
- url: https://api.slideforge.dev
security:
- bearerAuth: []
- apiKeyAuth: []
tags:
- name: deck
paths:
  /v1/deck:
    post:
      tags:
      - deck
      summary: Removed — the legacy convergence deck engine is gone (ADR 2026-06-14)
      description: Gone (410). Render a deck of structured intents via POST /v1/render/intent/deck (or the MCP create_deck tool); assemble existing slides via POST /v1/deck/from-jobs.
      operationId: generate_deck_v1_deck_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '410':
          description: Legacy deck engine removed
  /v1/deck/outline:
    post:
      tags:
      - deck
      summary: Predict the deck plan (engines + cost) without rendering
      description: 'Free preview of a deck render. Returns per-slide engine and cost: every slide goes through the SSG intent engine at a flat $0.05/slide. Thin briefs carry a `brief_hint` coaching nudge. No render, no wallet charge.'
      operationId: deck_outline_v1_deck_outline_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeckRequest'
        required: true
      responses:
        '200':
          description: Outline + cost estimate
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/deck/{deck_id}:
    patch:
      tags:
      - deck
      summary: Replace slides in an existing deck and recompile
      description: Swap one or more slides in a previously compiled deck. Pass position (1-based) and any completed job_id. Returns 202 — poll GET /v1/jobs/{deck_id} for recompile progress.
      operationId: update_deck_v1_deck__deck_id__patch
      parameters:
      - name: deck_id
        in: path
        required: true
        schema:
          type: string
          title: Deck Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeckUpdateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '202':
          description: Recompile started
        '400':
          description: Invalid request
        '404':
          description: Deck not found
        '409':
          description: Deck not in a recompilable state
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/deck/from-jobs:
    post:
      tags:
      - deck
      summary: Assemble a deck from existing slide job_ids
      description: 'Compose an existing set of completed slide jobs into a real deck. Cheaper than POST /v1/deck (no LLM, no generation), more polished than POST /v1/compile (creates a real `job_type=deck` row that PATCH /v1/deck/{id} can later edit).


        Use this when you have a set of slides from prior /v1/generate or /v1/render calls and want to bundle them into an editable deck.'
      operationId: deck_from_jobs_v1_deck_from_jobs_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeckFromJobsRequest'
        required: true
      responses:
        '202':
          description: Deck creation queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeckQueued'
        '400':
          description: No job_ids provided or invalid
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/deck/{deck_id}/fork:
    post:
      tags:
      - deck
      summary: Fork a deck — create a new editable copy with the same children
      description: Create an A/B variant of a deck. The new deck has the same slide content as the source (sharing blob references — no duplication) but its own metadata, so PATCH /v1/deck/{new_id} edits don't affect the source. Free.
      operationId: fork_deck_v1_deck__deck_id__fork_post
      parameters:
      - name: deck_id
        in: path
        required: true
        schema:
          type: string
          title: Deck Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeckForkRequest'
      responses:
        '202':
          description: Fork queued
          content:
            application/json:
              schema: {}
        '404':
          description: Source deck not found
        '400':
          description: Source job is not a deck
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/deck/combine:
    post:
      tags:
      - deck
      summary: Merge uploaded .pptx files into one deck
      description: Merge up to 10 uploaded .pptx files into a single deck, in the order given. Free — merging spends no model tokens, so nothing is charged and no balance is touched. 20 MB per file, 100 MB total. Anonymous callers get the first two files via POST /v1/tools/combine-powerpoint instead.
      operationId: deck_combine_v1_deck_combine_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_deck_combine_v1_deck_combine_post'
        required: true
      responses:
        '200':
          description: Merged — response includes a signed download_url
          content:
            application/json:
              schema: {}
        '400':
          description: Fewer than 2 files, or a file that is not a readable .pptx
        '401':
          description: Not authenticated
        '413':
          description: A file exceeds 20 MB, or the set exceeds 100 MB
        '429':
          description: Rate limit exceeded
        '503':
          description: Merge failed or storage unavailable
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    DeckQueued:
      properties:
        deck_id:
          type: string
          title: Deck Id
        status:
          type: string
          title: Status
          default: queued
        slide_count:
          type: integer
          title: Slide Count
      type: object
      required:
      - deck_id
      - slide_count
      title: DeckQueued
      description: 202 response for deck creation.
    GenerateSpec:
      properties:
        brief:
          type: string
          title: Brief
        chrome:
          anyOf:
          - $ref: '#/components/schemas/Chrome'
          - type: 'null'
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
      type: object
      required:
      - brief
      title: GenerateSpec
      description: Per-slide brief config within a deck (new explicit format).
    Body_deck_combine_v1_deck_combine_post:
      properties:
        files:
          items:
            type: string
            format: binary
          type: array
          title: Files
          description: .pptx files, in merge order
      type: object
      required:
      - files
      title: Body_deck_combine_v1_deck_combine_post
    Chrome:
      properties:
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        subtitle:
          anyOf:
          - type: string
          - type: 'null'
          title: Subtitle
        kicker:
          anyOf:
          - type: string
          - type: 'null'
          title: Kicker
        footer:
          anyOf:
          - type: string
          - type: 'null'
          title: Footer
        source:
          anyOf:
          - type: string
          - type: 'null'
          title: Source
        page_number:
          anyOf:
          - type: integer
          - type: 'null'
          title: Page Number
        classification:
          anyOf:
          - type: string
          - type: 'null'
          title: Classification
      type: object
      title: Chrome
      description: 'Slide chrome — the frame rendered by render_chrome().


        All fields optional. Resolution order:

        1. Explicit chrome on request (highest priority)

        2. LLM-extracted chrome from brief

        3. Deck-level chrome defaults

        4. Theme chrome defaults

        5. Not rendered (if still None)'
    DeckForkRequest:
      properties:
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        author:
          anyOf:
          - type: string
          - type: 'null'
          title: Author
      type: object
      title: DeckForkRequest
      description: POST /v1/deck/{id}/fork request body — all fields optional.
    SlideSpec:
      properties:
        generate:
          anyOf:
          - $ref: '#/components/schemas/GenerateSpec'
          - type: 'null'
        brief:
          type: string
          title: Brief
          default: ''
        chrome:
          anyOf:
          - $ref: '#/components/schemas/Chrome'
          - type: 'null'
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        slide_number:
          anyOf:
          - type: integer
          - type: 'null'
          title: Slide Number
      type: object
      title: SlideSpec
      description: One slide within a deck request.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    DeckFromJobsRequest:
      properties:
        job_ids:
          items:
            type: string
          type: array
          title: Job Ids
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        author:
          anyOf:
          - type: string
          - type: 'null'
          title: Author
        theme_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Theme Id
        slide_numbers:
          type: boolean
          title: Slide Numbers
          default: true
      type: object
      required:
      - job_ids
      title: DeckFromJobsRequest
      description: 'POST /v1/deck/from-jobs request body.


        Like /v1/compile, but produces a real `job_type=deck` row with child slides

        linked via parent_job_id, so PATCH /v1/deck/{id} works on the result.

        No LLM, no generation — just merge + chrome.'
    SlideReplacement:
      properties:
        position:
          type: integer
          title: Position
        job_id:
          type: string
          title: Job Id
      type: object
      required:
      - position
      - job_id
      title: SlideReplacement
      description: One slide to swap in a deck.
    DeckRequest:
      properties:
        slides:
          items:
            $ref: '#/components/schemas/SlideSpec'
          type: array
          title: Slides
          default: []
        prompt:
          anyOf:
          - type: string
          - type: 'null'
          title: Prompt
        slide_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Slide Count
        audience:
          anyOf:
          - type: string
          - type: 'null'
          title: Audience
        focus_area:
          anyOf:
          - type: string
          - type: 'null'
          title: Focus Area
        visual_style:
          anyOf:
          - type: string
          - type: 'null'
          title: Visual Style
        theme_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Theme Id
        mode:
          anyOf:
          - type: string
          - type: 'null'
          title: Mode
        enrich:
          type: boolean
          title: Enrich
          default: false
        chrome:
          anyOf:
          - $ref: '#/components/schemas/Chrome'
          - type: 'null'
        language:
          anyOf:
          - type: string
          - type: 'null'
          title: Language
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        author:
          anyOf:
          - type: string
          - type: 'null'
          title: Author
        model:
          anyOf:
          - type: string
          - type: 'null'
          title: Model
        max_parallel:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Parallel
      type: object
      title: DeckRequest
      description: POST /v1/deck request body.
    DeckUpdateRequest:
      properties:
        replace:
          items:
            $ref: '#/components/schemas/SlideReplacement'
          type: array
          title: Replace
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        author:
          anyOf:
          - type: string
          - type: 'null'
          title: Author
        slide_numbers:
          type: boolean
          title: Slide Numbers
          default: true
      type: object
      required:
      - replace
      title: DeckUpdateRequest
      description: PATCH /v1/deck/{deck_id} request body.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'SlideForge API key: `Authorization: Bearer sf_live_…`. Create one at https://slideforge.dev/console/keys'
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Same key, header form — for clients that cannot set Authorization.