Cadencz Generation API

openapi: 3.2.0
info:
  title: Cadencz Generation API
  description: Cadencz Phase 0 API. Frontend developers can use this Swagger page as the live request/response contract. Click `Authorize` and paste a Supabase access token for user-scoped endpoints.
  version: 0.1.0
tags:
- name: generation
  description: AI-assisted social copy generation.
paths:
  /api/v1/generation/text:
    post:
      tags:
      - generation
      summary: Generate platform-specific post copy
      description: Runs the Cadencz agent graph (per platform) to turn one idea into publish-ready copy — in the workspace's learned voice, shaped to each platform's rules, and checked by the critic. Uses the tiered model router (no direct provider key needed).
      operationId: generate_text_api_v1_generation_text_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TextGenerationRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TextGenerationResponse'
        '401':
          description: Missing or invalid Supabase bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: The request payload is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: The upstream provider rejected the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Required infrastructure or provider config is unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - SupabaseBearerAuth: []
  /api/v1/generation/ideas:
    post:
      tags:
      - generation
      summary: Brainstorm a batch of post ideas
      description: Turns the workspace strategy (and an optional seed topic) into a batch of concrete, on-strategy post ideas to draft next — ending the blank-page problem. Never asks the user anything; infers from stored strategy.
      operationId: generate_ideas_api_v1_generation_ideas_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdeasRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdeasResponse'
        '401':
          description: Missing or invalid Supabase bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: The upstream provider rejected the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Required infrastructure or provider config is unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - SupabaseBearerAuth: []
  /api/v1/generation/variants/{variant_id}/review:
    post:
      tags:
      - generation
      summary: AI review of a single post
      description: Reviews one post variant and returns a few applyable improvement suggestions (each with the post already rewritten to apply it) plus a brand-voice verdict. One smart-tier call; grounded in the workspace's strategy, voice, and writing skills.
      operationId: review_variant_api_v1_generation_variants__variant_id__review_post
      parameters:
      - name: variant_id
        in: path
        required: true
        schema:
          type: string
          title: Variant Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostReviewResponse'
        '401':
          description: Missing or invalid Supabase bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: The upstream provider rejected the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Required infrastructure or provider config is unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - SupabaseBearerAuth: []
    get:
      tags:
      - generation
      summary: Latest saved AI review of a post
      description: Returns the most recent completed AI review for this variant, free of charge. Reviews spend allowance to run, so surfaces hydrate from here instead of discarding a paid result on every tab switch. 404 when none has run yet.
      operationId: read_variant_review_api_v1_generation_variants__variant_id__review_get
      parameters:
      - name: variant_id
        in: path
        required: true
        schema:
          type: string
          title: Variant Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostReviewResponse'
        '401':
          description: Missing or invalid Supabase bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - SupabaseBearerAuth: []
components:
  schemas:
    GeneratedPlatformText:
      properties:
        platform:
          type: string
          title: Platform
        text:
          type: string
          title: Text
        provider:
          type: string
          title: Provider
        model:
          type: string
          title: Model
        agent_run_id:
          type: string
          title: Agent Run Id
        draft_index:
          type: integer
          minimum: 1.0
          title: Draft Index
          default: 1
      type: object
      required:
      - platform
      - text
      - provider
      - model
      - agent_run_id
      title: GeneratedPlatformText
      example:
        agent_run_id: run_123
        model: gpt-5.4-mini
        platform: twitter
        provider: openai
        text: Google sign-in is now live, with backend token checks doing the heavy lifting.
    PostIdeaRead:
      properties:
        theme:
          type: string
          title: Theme
        angle:
          type: string
          title: Angle
          default: ''
        hook:
          type: string
          title: Hook
          default: ''
        platform:
          type: string
          title: Platform
          default: ''
        pillar:
          type: string
          title: Pillar
          default: ''
        why:
          type: string
          title: Why
          default: ''
      type: object
      required:
      - theme
      title: PostIdeaRead
    TextGenerationRequest:
      properties:
        input:
          type: string
          maxLength: 8000
          minLength: 1
          title: Input
          description: Source material or instructions the model should turn into social copy.
          examples:
          - We added Google sign-in and a safer backend auth flow for Cadencz.
        platforms:
          items:
            type: string
          type: array
          maxItems: 5
          minItems: 1
          title: Platforms
          description: One or more platform prompt templates to apply.
          examples:
          - - twitter
            - linkedin
        provider:
          anyOf:
          - type: string
          - type: 'null'
          title: Provider
          description: Text model provider. Defaults to TEXT_MODEL_PROVIDER.
          examples:
          - openai
        model:
          anyOf:
          - type: string
          - type: 'null'
          title: Model
          description: Provider model id. Defaults to OPENAI_MODEL for the OpenAI provider.
          examples:
          - gpt-5.4-mini
        brain_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Brain Id
          description: Optional Brain id/slug used to ground the generation in saved product knowledge.
          examples:
          - brain_123
        conversation_id:
          anyOf:
          - type: string
            maxLength: 36
          - type: 'null'
          title: Conversation Id
          description: Optional durable Brain conversation to continue. Requires brain_id; when omitted, a new conversation is created for Brain-backed generation.
          examples:
          - cnv_123
        conversation_message:
          anyOf:
          - type: string
            maxLength: 8000
            minLength: 1
          - type: 'null'
          title: Conversation Message
          description: User-visible conversation turn to persist. Defaults to input when omitted, allowing clients to keep generation-only prompt instructions out of conversation history.
          examples:
          - Turn our onboarding lesson into posts for this week.
        brain_context:
          anyOf:
          - type: string
            maxLength: 12000
          - type: 'null'
          title: Brain Context
          description: Optional client-provided Brain context fallback when the Brain is not yet saved server-side.
        temperature:
          type: number
          maximum: 2.0
          minimum: 0.0
          title: Temperature
          default: 0.7
        max_tokens:
          anyOf:
          - type: integer
            maximum: 2000.0
            minimum: 64.0
          - type: 'null'
          title: Max Tokens
        count:
          anyOf:
          - type: integer
            maximum: 5.0
            minimum: 1.0
          - type: 'null'
          title: Count
          description: How many distinct post concepts to create. When omitted, Compose infers an explicit count from requests such as 'write two posts'.
        content_guidance:
          anyOf:
          - type: string
            maxLength: 500
          - type: 'null'
          title: Content Guidance
          description: Selected content mode, kept separate from the user's requested subject.
      type: object
      required:
      - input
      title: TextGenerationRequest
      example:
        brain_id: brain_123
        conversation_id: cnv_123
        conversation_message: Turn our onboarding lesson into posts for this week.
        input: We added Google sign-in and safer backend token validation.
        max_tokens: 500
        model: gpt-5.4-mini
        platforms:
        - twitter
        - linkedin
        provider: openai
        temperature: 0.7
    PostReviewResponse:
      properties:
        suggestions:
          items:
            $ref: '#/components/schemas/PostSuggestionRead'
          type: array
          title: Suggestions
          default: []
        brand_voice:
          $ref: '#/components/schemas/BrandVoiceRead'
          default:
            on_brand: true
            confidence: 0
            tone: ''
            note: ''
        voice_source:
          type: string
          title: Voice Source
          default: neutral_product
        reviewed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Reviewed At
      type: object
      title: PostReviewResponse
      example:
        brand_voice:
          confidence: 94
          note: Matches your direct, build-in-public voice.
          on_brand: true
          tone: Confident, plain
        suggestions:
        - detail: Open with the surprising result, not the setup.
          revised_body: We cut onboarding to 2 steps and activation rose 18%…
          title: Stronger hook
    IdeasRequest:
      properties:
        seed:
          anyOf:
          - type: string
            maxLength: 2000
          - type: 'null'
          title: Seed
          description: Optional focus/topic for this batch. Omit to ideate from the workspace strategy.
          examples:
          - onboarding and activation
        count:
          type: integer
          maximum: 20.0
          minimum: 1.0
          title: Count
          description: How many ideas to generate.
          default: 8
      type: object
      title: IdeasRequest
      example:
        count: 8
        seed: pricing lessons
    BrandVoiceRead:
      properties:
        on_brand:
          type: boolean
          title: On Brand
          default: true
        confidence:
          type: integer
          title: Confidence
          default: 0
        tone:
          type: string
          title: Tone
          default: ''
        note:
          type: string
          title: Note
          default: ''
      type: object
      title: BrandVoiceRead
    PostSuggestionRead:
      properties:
        title:
          type: string
          title: Title
        detail:
          type: string
          title: Detail
          default: ''
        revised_body:
          type: string
          title: Revised Body
          default: ''
      type: object
      required:
      - title
      title: PostSuggestionRead
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    IdeasResponse:
      properties:
        ideas:
          items:
            $ref: '#/components/schemas/PostIdeaRead'
          type: array
          title: Ideas
      type: object
      required:
      - ideas
      title: IdeasResponse
      example:
        ideas:
        - angle: contrarian
          hook: We cut onboarding from 6 steps to 2. Activation went up, not down.
          pillar: build-in-public
          platform: x
          theme: The onboarding step we deleted
          why: Concrete result tied to the activation pillar.
    ErrorResponse:
      properties:
        detail:
          anyOf:
          - type: string
          - additionalProperties: true
            type: object
          - items: {}
            type: array
          title: Detail
      type: object
      required:
      - detail
      title: ErrorResponse
      example:
        detail: Authorization header is required.
    TextGenerationResponse:
      properties:
        outputs:
          items:
            $ref: '#/components/schemas/GeneratedPlatformText'
          type: array
          title: Outputs
        conversation_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Conversation Id
      type: object
      required:
      - outputs
      title: TextGenerationResponse
      example:
        conversation_id: cnv_123
        outputs:
        - agent_run_id: run_123
          model: gpt-5.4-mini
          platform: twitter
          provider: openai
          text: Google sign-in is now live, with backend token checks doing the heavy lifting.
        - agent_run_id: run_124
          model: gpt-5.4-mini
          platform: linkedin
          provider: openai
          text: 'We shipped Google sign-in with backend token validation. The important part is less visible: the frontend handles identity, while the API owns authorization and database writes.'
  securitySchemes:
    SupabaseBearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Supabase access token
      description: 'Send the Supabase access token as `Authorization: Bearer <token>`.'
    DodoWebhookSignature:
      type: apiKey
      in: header
      name: webhook-signature
      description: Dodo Payments webhook signature header.