Cadencz Strategy API

openapi: 3.2.0
info:
  title: Cadencz Strategy 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: strategy
  description: Workspace agent strategy and voice learning.
paths:
  /api/v1/strategy:
    get:
      tags:
      - strategy
      summary: Get the workspace agent strategy
      operationId: get_strategy_api_v1_strategy_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StrategyRead'
        '401':
          description: Missing or invalid Supabase bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - SupabaseBearerAuth: []
    put:
      tags:
      - strategy
      summary: Update the workspace agent strategy
      operationId: put_strategy_api_v1_strategy_put
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StrategyUpdate'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StrategyRead'
        '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: []
  /api/v1/strategy/learn:
    post:
      tags:
      - strategy
      summary: Learn the workspace voice from past posts
      description: Runs the smart-tier voice agent over 5-10 past posts, extracts a tone profile, and stores it on the strategy so every future draft is written in the user's voice.
      operationId: learn_voice_api_v1_strategy_learn_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LearnVoiceRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LearnVoiceResponse'
        '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: []
components:
  schemas:
    StrategyRead:
      properties:
        workspace_id:
          type: string
          title: Workspace Id
        niche:
          anyOf:
          - type: string
          - type: 'null'
          title: Niche
        goals:
          items:
            type: string
          type: array
          title: Goals
        whats_new:
          anyOf:
          - type: string
          - type: 'null'
          title: Whats New
        tags:
          items:
            type: string
          type: array
          title: Tags
        tone_profile:
          additionalProperties: true
          type: object
          title: Tone Profile
        voice_profile:
          $ref: '#/components/schemas/VoiceProfile'
        voice_samples:
          items:
            type: string
          type: array
          title: Voice Samples
        voice_sample_platforms:
          additionalProperties:
            type: string
          type: object
          title: Voice Sample Platforms
        voice_platforms_learned:
          items:
            type: string
          type: array
          title: Voice Platforms Learned
        cadence_per_week:
          type: integer
          title: Cadence Per Week
        platforms:
          items:
            type: string
          type: array
          title: Platforms
        automation:
          $ref: '#/components/schemas/AutomationSettings'
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
      - workspace_id
      - niche
      - goals
      - tags
      - tone_profile
      - voice_profile
      - voice_samples
      - cadence_per_week
      - platforms
      - automation
      - updated_at
      title: StrategyRead
      example:
        cadence_per_week: 5
        goals:
        - grow
        - nurture
        niche: Indie SaaS / building in public
        platforms:
        - x
        - linkedin
        tone_profile:
          emoji: sparse
          tone_words:
          - wry
          - concise
        updated_at: '2026-07-14T10:00:00Z'
        workspace_id: wks_123
    ToneAxis:
      properties:
        id:
          type: string
          maxLength: 40
          title: Id
        low:
          type: string
          maxLength: 40
          title: Low
        high:
          type: string
          maxLength: 40
          title: High
        value:
          type: integer
          maximum: 100.0
          minimum: 0.0
          title: Value
          default: 50
      type: object
      required:
      - id
      - low
      - high
      title: ToneAxis
      description: 'One bipolar slider: `value` 0 sits at `low`, 100 at `high`.'
    VoiceVersion:
      properties:
        id:
          type: string
          maxLength: 64
          title: Id
        persona_id:
          type: string
          maxLength: 64
          title: Persona Id
        label:
          type: string
          maxLength: 160
          title: Label
          default: ''
        saved_at:
          type: string
          format: date-time
          title: Saved At
        snapshot:
          $ref: '#/components/schemas/VoicePersona'
      type: object
      required:
      - id
      - persona_id
      - saved_at
      - snapshot
      title: VoiceVersion
      description: A snapshot taken on save, so a regretted edit is one click from undone.
    VoicePersona:
      properties:
        id:
          type: string
          maxLength: 64
          title: Id
        name:
          type: string
          maxLength: 80
          title: Name
          default: ''
        audience:
          type: string
          maxLength: 2000
          title: Audience
          default: ''
        context:
          type: string
          maxLength: 500
          title: Context
          default: ''
        mission:
          type: string
          maxLength: 2000
          title: Mission
          default: ''
        traits:
          items:
            type: string
          type: array
          title: Traits
        goals:
          items:
            type: string
          type: array
          title: Goals
        tone:
          items:
            $ref: '#/components/schemas/ToneAxis'
          type: array
          maxItems: 12
          title: Tone
        vocabulary:
          items:
            type: string
          type: array
          title: Vocabulary
        banned_words:
          items:
            type: string
          type: array
          title: Banned Words
        ctas:
          items:
            type: string
          type: array
          title: Ctas
        formatting:
          items:
            type: string
          type: array
          title: Formatting
        active:
          type: boolean
          title: Active
          default: false
        created_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Created At
        updated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Updated At
      type: object
      required:
      - id
      title: VoicePersona
      description: A named way of speaking. Exactly one persona is active at a time.
    VoiceProfile:
      properties:
        personas:
          items:
            $ref: '#/components/schemas/VoicePersona'
          type: array
          maxItems: 10
          title: Personas
        versions:
          items:
            $ref: '#/components/schemas/VoiceVersion'
          type: array
          maxItems: 20
          title: Versions
      type: object
      title: VoiceProfile
      description: The whole authored document. Empty is valid — it just means untouched.
    LearnVoiceRequest:
      properties:
        posts:
          items:
            type: string
          type: array
          maxItems: 20
          minItems: 1
          title: Posts
          description: 5-10 of the user's past posts. The voice agent learns their tone from these.
        niche:
          anyOf:
          - type: string
            maxLength: 2000
          - type: 'null'
          title: Niche
        writing_notes:
          anyOf:
          - type: string
            maxLength: 2000
          - type: 'null'
          title: Writing Notes
        avoid_style:
          anyOf:
          - type: string
            maxLength: 2000
          - type: 'null'
          title: Avoid Style
        platform:
          anyOf:
          - type: string
            maxLength: 40
          - type: 'null'
          title: Platform
          description: The platform these posts were written for (x, linkedin, threads, …). The tone learned from them is then used for that platform's drafts only. Omit for posts that stand for every platform.
      type: object
      required:
      - posts
      title: LearnVoiceRequest
    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
    StrategyUpdate:
      properties:
        niche:
          anyOf:
          - type: string
            maxLength: 2000
          - type: 'null'
          title: Niche
        goals:
          anyOf:
          - items:
              type: string
            type: array
            maxItems: 12
          - type: 'null'
          title: Goals
        whats_new:
          anyOf:
          - type: string
            maxLength: 2000
          - type: 'null'
          title: Whats New
        tags:
          anyOf:
          - items:
              type: string
            type: array
            maxItems: 40
          - type: 'null'
          title: Tags
        voice_profile:
          anyOf:
          - $ref: '#/components/schemas/VoiceProfile'
          - type: 'null'
        voice_samples:
          anyOf:
          - items:
              type: string
            type: array
            maxItems: 50
          - type: 'null'
          title: Voice Samples
        voice_sample_platforms:
          anyOf:
          - additionalProperties:
              type: string
            type: object
            maxProperties: 50
          - type: 'null'
          title: Voice Sample Platforms
        cadence_per_week:
          anyOf:
          - type: integer
            maximum: 50.0
            minimum: 1.0
          - type: 'null'
          title: Cadence Per Week
        platforms:
          anyOf:
          - items:
              type: string
            type: array
            maxItems: 20
          - type: 'null'
          title: Platforms
        automation:
          anyOf:
          - $ref: '#/components/schemas/AutomationSettings'
          - type: 'null'
      type: object
      title: StrategyUpdate
    AutomationSettings:
      properties:
        enabled:
          type: boolean
          title: Enabled
          description: Off by default. Auto-planning spends credits, so it's opt-in.
          default: false
        suspended_by_plan:
          type: boolean
          title: Suspended By Plan
          description: Cadencz turned automation off after plan access was lost. The saved schedule remains, but the customer must explicitly enable it again.
          default: false
        auto_write_week:
          type: boolean
          title: Auto Write Week
          description: Write the week's posts on their own at the planning hour, so the stack always has a fresh week on it. Every plan; bounded by the tier's weekly number and the monthly pool. Distinct from `enabled`, which is the paid Automation feature (rules, auto-approve).
          default: true
        plan_weekday:
          type: integer
          maximum: 6.0
          minimum: 0.0
          title: Plan Weekday
          description: 0 = Monday.
          default: 0
        plan_hour:
          type: integer
          maximum: 23.0
          minimum: 0.0
          title: Plan Hour
          description: Local hour, 24h.
          default: 6
        timezone:
          type: string
          maxLength: 64
          title: Timezone
          description: IANA zone.
          default: UTC
        posting_weekdays:
          items:
            type: integer
          type: array
          title: Posting Weekdays
          description: Days posts may be scheduled on. 0 = Monday.
        posting_times:
          items:
            type: string
          type: array
          title: Posting Times
          description: HH:MM slots, cycled through in order.
        day_platforms:
          additionalProperties:
            type: string
          type: object
          title: Day Platforms
          description: Which channel each weekday posts to, keyed by weekday index as a string ('0' = Monday). A day with no entry falls back to the workspace's platform rotation.
        platform_quota:
          additionalProperties:
            type: integer
          type: object
          title: Platform Quota
          description: How many posts each channel gets per batch, keyed by platform id. The batch is their sum. Zero (or absent) means the channel gets none; empty means the planner decides per post from cadence.
        brain_id:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Brain Id
          description: Ground posts in this Brain. None = the most recently updated.
        auto_approve:
          type: boolean
          title: Auto Approve
          description: Schedule straight to the calendar instead of holding for review.
          default: false
      type: object
      title: AutomationSettings
      description: When the agents plan, and when the posts they produce go out.
    LearnVoiceResponse:
      properties:
        run_id:
          type: string
          title: Run Id
        voice:
          additionalProperties: true
          type: object
          title: Voice
        strategy:
          $ref: '#/components/schemas/StrategyRead'
      type: object
      required:
      - run_id
      - voice
      - strategy
      title: LearnVoiceResponse
    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.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  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.