Cadencz Onboarding API

openapi: 3.2.0
info:
  title: Cadencz Onboarding 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: Onboarding
paths:
  /api/v1/onboarding/start:
    post:
      tags:
      - Onboarding
      summary: Start onboarding from a website or a written brief
      operationId: start_onboarding_api_v1_onboarding_start_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnboardingStartRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardingRunRead'
        '401':
          description: Missing or invalid Supabase bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: The requested state transition is not allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - SupabaseBearerAuth: []
  /api/v1/onboarding/current:
    get:
      tags:
      - Onboarding
      summary: Poll the latest onboarding run
      operationId: current_onboarding_api_v1_onboarding_current_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardingRunRead'
        '401':
          description: Missing or invalid Supabase bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - SupabaseBearerAuth: []
  /api/v1/onboarding/cancel:
    post:
      tags:
      - Onboarding
      summary: Stop the running onboarding run
      description: 'Stop setup and hand the workspace back.


        Deliberately not a 409 when the run has already finished: the button exists

        because a run looked stuck, and telling someone their stop failed because

        the thing stopped on its own is a worse answer than the run itself.'
      operationId: cancel_onboarding_api_v1_onboarding_cancel_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardingRunRead'
        '401':
          description: Missing or invalid Supabase bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - SupabaseBearerAuth: []
  /api/v1/onboarding/retry:
    post:
      tags:
      - Onboarding
      summary: Retry a failed onboarding run
      operationId: retry_onboarding_api_v1_onboarding_retry_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardingRunRead'
        '401':
          description: Missing or invalid Supabase bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: The requested state transition is not allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - SupabaseBearerAuth: []
components:
  schemas:
    OnboardingStartRequest:
      properties:
        url:
          anyOf:
          - type: string
            maxLength: 2000
            minLength: 4
          - type: 'null'
          title: Url
          description: The website to analyze.
        brief:
          anyOf:
          - type: string
            maxLength: 50000
          - type: 'null'
          title: Brief
          description: 'A written description of the product, used instead of a website: what it is, who it is for, the problem, the benefits, the tone.'
        company_name:
          anyOf:
          - type: string
            maxLength: 160
          - type: 'null'
          title: Company Name
          description: The brand or product name. Required with a brief.
        platforms:
          anyOf:
          - items:
              type: string
            type: array
            maxItems: 20
          - type: 'null'
          title: Platforms
          description: Where the first week should be written for. Saved to the strategy before the run starts.
        goals:
          anyOf:
          - items:
              type: string
            type: array
            maxItems: 12
          - type: 'null'
          title: Goals
          description: What the posts are for — ids from the goal catalogue (promote, learnings, engage, build_in_public, grow, authority). Saved to the strategy before the run.
        brain_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Brain Id
          description: Target an existing brain.
        new_brain:
          type: boolean
          title: New Brain
          description: Force a fresh brain (plan-capped).
          default: false
        refresh:
          type: boolean
          title: Refresh
          description: Re-read the brain's data only — its plan is left untouched.
          default: false
      type: object
      title: OnboardingStartRequest
    OnboardingStepRead:
      properties:
        key:
          type: string
          title: Key
        label:
          type: string
          title: Label
        status:
          type: string
          title: Status
        detail:
          type: string
          title: Detail
          default: ''
        started_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Started At
        finished_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Finished At
      type: object
      required:
      - key
      - label
      - status
      title: OnboardingStepRead
    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
    OnboardingRunRead:
      properties:
        id:
          type: string
          title: Id
        source_kind:
          type: string
          title: Source Kind
          default: url
        url:
          anyOf:
          - type: string
          - type: 'null'
          title: Url
        company_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Company Name
        status:
          type: string
          title: Status
        current_step:
          anyOf:
          - type: string
          - type: 'null'
          title: Current Step
        steps:
          items:
            $ref: '#/components/schemas/OnboardingStepRead'
          type: array
          title: Steps
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
        brain_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Brain Id
        content_plan_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Content Plan Id
        created_at:
          type: string
          format: date-time
          title: Created At
        finished_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Finished At
      type: object
      required:
      - id
      - status
      - created_at
      title: OnboardingRunRead
    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.