slideforge-dev Discovery API

openapi: 3.2.0
info:
  title: SlideForge Discovery 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: Discovery
paths:
  /v1/widgets:
    get:
      tags:
      - Discovery
      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:
      - Discovery
      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:
      - Discovery
      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/agent-onboarding:
    get:
      tags:
      - Discovery
      summary: Agent-first onboarding playbook
      description: Structured playbook for an agent evaluating SlideForge. Free; no auth required, but balance is only shown with auth.
      operationId: agent_onboarding_v1_agent_onboarding_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /v1/capabilities:
    get:
      tags:
      - Discovery
      summary: Capability overview
      description: 'REST bootstrap for agents: render paths, discovery, costs, and constraints.'
      operationId: capabilities_v1_capabilities_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /v1/pricing:
    get:
      tags:
      - Discovery
      summary: Machine-readable rate card
      description: Returns the canonical pricing table as structured JSON.
      operationId: pricing_v1_pricing_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /openapi-agent.json:
    get:
      tags:
      - Discovery
      summary: Agent-facing OpenAPI projection
      description: 'Curated subset of the API for GPT Actions, custom connectors and other OpenAPI-driven agents: the 7-tool MCP surface plus the job lifecycle, with operationIds written to be read as function names. Derived from the live spec, so it cannot drift from what the server actually serves.'
      operationId: openapi_agent_openapi_agent_json_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    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
  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.