slideforge-dev Catalog API

openapi: 3.2.0
info:
  title: SlideForge Catalog 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: Catalog
paths:
  /v1/catalog:
    get:
      tags:
      - Catalog
      summary: Browse the slide-template catalog (patterns + segment showcase)
      description: The public gallery + agent catalog. Returns slide templates with segment/use-case/family facets. Filter with `?segment=`, `?use_case=`, `?family=`, `?layer=pattern|showcase`, and free-text `?q=`. No auth. Layer `pattern` = structural variants; `showcase` = authored segment-specific example slides.
      operationId: list_catalog_v1_catalog_get
      parameters:
      - name: segment
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Segment
      - name: use_case
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Use Case
      - name: family
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Family
      - name: layer
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: pattern | showcase
          title: Layer
        description: pattern | showcase
      - name: q
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: free-text over title + blurb
          title: Q
        description: free-text over title + blurb
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/catalog/forms:
    get:
      tags:
      - Catalog
      summary: The SSG form menu — families, when-to-use, bound fields, variants
      description: 'The structured-intent contract for agents. No `?family=` -> the form overview (each form: when-to-use, bound fields, variant count). `?family=` -> that form''s variants (paginate with `?limit=` / `?offset=`). REST mirror of MCP `browse_catalog`. Free, no auth. Per-form JSON Schema: GET /v1/catalog/forms/{form}.'
      operationId: list_forms_v1_catalog_forms_get
      parameters:
      - name: family
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Scope to one form/family
          title: Family
        description: Scope to one form/family
      - name: limit
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Max variants (with family=)
          title: Limit
        description: Max variants (with family=)
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          description: Pagination offset (with family=)
          default: 0
          title: Offset
        description: Pagination offset (with family=)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/catalog/forms/{form}:
    get:
      tags:
      - Catalog
      summary: One form's machine-readable contract (JSON Schema + capacity + examples)
      description: 'The generated contract for a single form: JSON Schema for the `data` payload, capacity limits, intent-field mapping, variants, and worked examples. REST mirror of MCP `browse_catalog(type=schema, family=)`. `variant=`/`prior_id=` pins a variant so the contract matches the slotmap the binder uses for it. 404 if the form is unknown.'
      operationId: get_form_schema_v1_catalog_forms__form__get
      parameters:
      - name: form
        in: path
        required: true
        schema:
          type: string
          title: Form
      - name: variant
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Variant
      - name: prior_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Prior Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/widgets:
    get:
      tags:
      - Catalog
      summary: Code-mode widget + chart-primitive catalog
      description: The board-grade widgets and chart primitives drawable via `add_widget()` in `mode=code` (`/v1/render/code`). Grid by default (every name + a one-liner); `?name=` returns the full contract — docstring, param/content schema, and a worked example. REST mirror of MCP `browse_catalog(type=widgets)`. Free, no auth.
      operationId: list_widgets_v1_widgets_get
      parameters:
      - name: name
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: A widget/primitive name for its full contract
          title: Name
        description: A widget/primitive name for its full contract
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/widgets/{name}/preview:
    get:
      tags:
      - Catalog
      summary: Widget thumbnail (PNG) from blob storage
      description: 'Pre-rendered thumbnail of the widget/primitive drawn from its worked example on a neutral 16:9 slide (generated by scripts/ssg/publish_widget_thumbnails.py). Sizes: full (~1920px), sm (~480px). No auth.'
      operationId: get_widget_preview_v1_widgets__name__preview_get
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
          title: Name
      - name: size
        in: query
        required: false
        schema:
          type: string
          description: full | sm
          default: full
          title: Size
        description: full | sm
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
            image/png: {}
        '404':
          description: Preview not available
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/helpers:
    get:
      tags:
      - Catalog
      summary: python-pptx helpers available in mode=code
      description: Signatures + categories of the python-pptx helpers injected into the `mode=code` sandbox (`add_text_box`, `add_box`, `add_icon`, `add_widget`, …) plus the canvas notes. REST mirror of MCP `browse_catalog(type=helpers)`. Free, no auth.
      operationId: list_helpers_v1_helpers_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /v1/catalog/{slug}:
    get:
      tags:
      - Catalog
      summary: Get one catalog entry (with its editable structured intent)
      description: Full record for a pattern or showcase slug, including the brief and the structured intent (`content`) that deterministically renders it.
      operationId: get_catalog_item_v1_catalog__slug__get
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogDetail'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/catalog/{slug}/preview:
    get:
      tags:
      - Catalog
      summary: Slide thumbnail (PNG) from blob storage
      description: 'Serves the pre-rendered thumbnail. Sizes: full (~1600px), sm (~480px). No auth.'
      operationId: get_catalog_preview_v1_catalog__slug__preview_get
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      - name: size
        in: query
        required: false
        schema:
          type: string
          description: full | sm
          default: full
          title: Size
        description: full | sm
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
            image/png: {}
        '404':
          description: Preview not available
        '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
    CatalogItem:
      properties:
        slug:
          type: string
          title: Slug
        layer:
          type: string
          title: Layer
        title:
          type: string
          title: Title
        family:
          type: string
          title: Family
        family_label:
          type: string
          title: Family Label
        variant:
          anyOf:
          - type: string
          - type: 'null'
          title: Variant
        variant_label:
          anyOf:
          - type: string
          - type: 'null'
          title: Variant Label
        segments:
          items:
            type: string
          type: array
          title: Segments
        use_cases:
          items:
            type: string
          type: array
          title: Use Cases
        blurb:
          type: string
          title: Blurb
        preview_url:
          type: string
          title: Preview Url
        render_ready:
          type: boolean
          title: Render Ready
          default: true
      type: object
      required:
      - slug
      - layer
      - title
      - family
      - family_label
      - segments
      - use_cases
      - blurb
      - preview_url
      title: CatalogItem
    CatalogDetail:
      properties:
        slug:
          type: string
          title: Slug
        layer:
          type: string
          title: Layer
        title:
          type: string
          title: Title
        family:
          type: string
          title: Family
        family_label:
          type: string
          title: Family Label
        variant:
          anyOf:
          - type: string
          - type: 'null'
          title: Variant
        variant_label:
          anyOf:
          - type: string
          - type: 'null'
          title: Variant Label
        segments:
          items:
            type: string
          type: array
          title: Segments
        use_cases:
          items:
            type: string
          type: array
          title: Use Cases
        blurb:
          type: string
          title: Blurb
        preview_url:
          type: string
          title: Preview Url
        render_ready:
          type: boolean
          title: Render Ready
          default: true
        brief:
          anyOf:
          - type: string
          - type: 'null'
          title: Brief
        intent:
          anyOf:
          - type: object
          - type: 'null'
          title: Intent
        content:
          anyOf:
          - type: object
          - type: 'null'
          title: Content
      type: object
      required:
      - slug
      - layer
      - title
      - family
      - family_label
      - segments
      - use_cases
      - blurb
      - preview_url
      title: CatalogDetail
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CatalogResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/CatalogItem'
          type: array
          title: Items
        count:
          type: integer
          title: Count
        segments:
          items:
            $ref: '#/components/schemas/Facet'
          type: array
          title: Segments
        use_cases:
          items:
            $ref: '#/components/schemas/Facet'
          type: array
          title: Use Cases
        families:
          items:
            $ref: '#/components/schemas/Facet'
          type: array
          title: Families
      type: object
      required:
      - items
      - count
      - segments
      - use_cases
      - families
      title: CatalogResponse
    Facet:
      properties:
        id:
          type: string
          title: Id
        label:
          type: string
          title: Label
        count:
          type: integer
          title: Count
      type: object
      required:
      - id
      - label
      - count
      title: Facet
  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.