slideforge-dev Brands API

openapi: 3.2.0
info:
  title: SlideForge Brands 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: Brands
paths:
  /v1/brands:
    get:
      tags:
      - Brands
      summary: List My Brands
      operationId: list_my_brands_v1_brands_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
    post:
      tags:
      - Brands
      summary: Create Brand From Tokens
      operationId: create_brand_from_tokens_v1_brands_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBrandRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/brands/upload:
    post:
      tags:
      - Brands
      summary: Upload Brand Template
      operationId: upload_brand_template_v1_brands_upload_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_upload_brand_template_v1_brands_upload_post'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/brands/from-url:
    post:
      tags:
      - Brands
      summary: Create Brand From Url
      operationId: create_brand_from_url_v1_brands_from_url_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FromUrlRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/brands/{slug}/tokens.json:
    get:
      tags:
      - Brands
      summary: Export Tokens Json
      description: 'The kit as its DTCG document — the open-play half of §2.3: the same file Figma, Tokens

        Studio and Style Dictionary read. Built-in kits are public product info (W5): fetch one,

        tweak it, send it back as the inline `brand` document on a render.'
      operationId: export_tokens_json_v1_brands__slug__tokens_json_get
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/brands/{slug}/potx:
    get:
      tags:
      - Brands
      summary: Export Brand Potx
      operationId: export_brand_potx_v1_brands__slug__potx_get
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/brands/{slug}/thmx:
    get:
      tags:
      - Brands
      summary: Export Brand Thmx
      operationId: export_brand_thmx_v1_brands__slug__thmx_get
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/brands/{slug}:
    get:
      tags:
      - Brands
      summary: Get Brand
      operationId: get_brand_v1_brands__slug__get
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Brands
      summary: Delete My Brand
      description: Delete a kit you own — the entitlement remedy for the one-kit cap ('delete it first').
      operationId: delete_my_brand_v1_brands__slug__delete
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/brands/{slug}/versions:
    post:
      tags:
      - Brands
      summary: Publish Version
      operationId: publish_version_v1_brands__slug__versions_post
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewVersionRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    Body_upload_brand_template_v1_brands_upload_post:
      properties:
        file:
          type: string
          format: binary
          title: File
        slug:
          type: string
          title: Slug
        name:
          type: string
          title: Name
      type: object
      required:
      - file
      title: Body_upload_brand_template_v1_brands_upload_post
    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
    NewVersionRequest:
      properties:
        document:
          type: object
          title: Document
      type: object
      required:
      - document
      title: NewVersionRequest
    FromUrlRequest:
      properties:
        url:
          type: string
          maxLength: 512
          minLength: 3
          title: Url
          description: The brand's website — a domain or any URL on it.
        slug:
          anyOf:
          - type: string
            pattern: ^[a-z0-9][a-z0-9_-]{1,63}$
          - type: 'null'
          title: Slug
        name:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
          title: Name
      type: object
      required:
      - url
      title: FromUrlRequest
    CreateBrandRequest:
      properties:
        slug:
          type: string
          pattern: ^[a-z0-9][a-z0-9_-]{1,63}$
          title: Slug
          description: The wire theme_id. Lowercase; unique within your account.
        name:
          type: string
          maxLength: 256
          minLength: 1
          title: Name
        document:
          type: object
          title: Document
          description: A W3C Design Tokens (DTCG 2025.10) document; Tokens-Studio dialect accepted.
      type: object
      required:
      - slug
      - name
      - document
      title: CreateBrandRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  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.