Cadencz Plans API

openapi: 3.2.0
info:
  title: Cadencz Plans 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: Plans
  description: Weekly content planning and approvals.
paths:
  /api/v1/plans/generate:
    post:
      tags:
      - Plans
      summary: Generate the week's content plan
      description: Runs the smart-tier planner over the workspace strategy, learned voice, and a summary of recent analytics (the results→plan loop), and returns a themed week — each item with a why.
      operationId: generate_plan_api_v1_plans_generate_post
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/PlanGenerateRequest'
              - type: 'null'
              title: ' Body'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanRead'
        '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/plans/current:
    get:
      tags:
      - Plans
      summary: Get the current content plan
      operationId: current_plan_api_v1_plans_current_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanRead'
        '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/plans/stack:
    get:
      tags:
      - Plans
      summary: Every planned post still waiting on a verdict, across weeks
      operationId: plan_stack_api_v1_plans_stack_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanStackRead'
        '401':
          description: Missing or invalid Supabase bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - SupabaseBearerAuth: []
  /api/v1/plans/items/{item_id}:
    patch:
      tags:
      - Plans
      summary: Edit a plan item (theme, prompt, platforms, time)
      operationId: update_plan_item_route_api_v1_plans_items__item_id__patch
      parameters:
      - name: item_id
        in: path
        required: true
        schema:
          type: string
          title: Item Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlanItemUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanItemRead'
        '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'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - SupabaseBearerAuth: []
    delete:
      tags:
      - Plans
      summary: Dismiss (remove) a plan item
      operationId: dismiss_plan_item_route_api_v1_plans_items__item_id__delete
      parameters:
      - name: item_id
        in: path
        required: true
        schema:
          type: string
          title: Item Id
      responses:
        '204':
          description: Successful Response
        '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'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - SupabaseBearerAuth: []
  /api/v1/plans/items/{item_id}/refine:
    post:
      tags:
      - Plans
      summary: Refine a planned post from user feedback
      operationId: refine_plan_item_route_api_v1_plans_items__item_id__refine_post
      parameters:
      - name: item_id
        in: path
        required: true
        schema:
          type: string
          title: Item Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlanItemRefineRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanItemRefineResponse'
        '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'
        '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/plans/items/{item_id}/render:
    post:
      tags:
      - Plans
      summary: Retry writing a failed draft
      description: Puts a failed plan item back into `rendering` and re-runs the writer in the background — along with any sibling drafts that failed in the same run. The client polls GET /plans/current and watches items leave `rendering`.
      operationId: retry_render_item_route_api_v1_plans_items__item_id__render_post
      parameters:
      - name: item_id
        in: path
        required: true
        schema:
          type: string
          title: Item Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanItemRead'
        '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'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - SupabaseBearerAuth: []
  /api/v1/plans/items/{item_id}/approve:
    post:
      tags:
      - Plans
      summary: Approve a plan item into a post
      operationId: approve_plan_item_api_v1_plans_items__item_id__approve_post
      parameters:
      - name: item_id
        in: path
        required: true
        schema:
          type: string
          title: Item Id
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/PlanItemApproveRequest'
              - type: 'null'
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApproveItemResponse'
        '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'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - SupabaseBearerAuth: []
components:
  schemas:
    PlanItemRefineRequest:
      properties:
        feedback:
          type: string
          maxLength: 1000
          minLength: 3
          title: Feedback
      type: object
      required:
      - feedback
      title: PlanItemRefineRequest
    PlanItemRead:
      properties:
        id:
          type: string
          title: Id
        theme:
          anyOf:
          - type: string
          - type: 'null'
          title: Theme
        angle:
          anyOf:
          - type: string
          - type: 'null'
          title: Angle
        platforms:
          items:
            type: string
          type: array
          title: Platforms
        why:
          anyOf:
          - type: string
          - type: 'null'
          title: Why
        prompt:
          type: string
          title: Prompt
        scheduled_for:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Scheduled For
        status:
          type: string
          title: Status
        format:
          anyOf:
          - type: string
          - type: 'null'
          title: Format
        publish_mode:
          type: string
          title: Publish Mode
          default: single
        content_metadata:
          additionalProperties: true
          type: object
          title: Content Metadata
        body_parts:
          items:
            type: string
          type: array
          title: Body Parts
        media_ids:
          items:
            type: string
          type: array
          title: Media Ids
        media:
          items:
            $ref: '#/components/schemas/MediaRead'
          type: array
          title: Media
        created_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Created At
      type: object
      required:
      - id
      - theme
      - angle
      - platforms
      - why
      - prompt
      - scheduled_for
      - status
      title: PlanItemRead
    PlanItemUpdate:
      properties:
        theme:
          anyOf:
          - type: string
          - type: 'null'
          title: Theme
        angle:
          anyOf:
          - type: string
          - type: 'null'
          title: Angle
        prompt:
          anyOf:
          - type: string
          - type: 'null'
          title: Prompt
        platforms:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Platforms
        scheduled_for:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Scheduled For
        publish_mode:
          anyOf:
          - type: string
            enum:
            - single
            - long_form
            - thread
          - type: 'null'
          title: Publish Mode
        body_parts:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Body Parts
        media_ids:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Media Ids
        decision:
          anyOf:
          - type: string
            enum:
            - accepted
            - rejected
            - ''
          - type: 'null'
          title: Decision
      type: object
      title: PlanItemUpdate
    MediaRead:
      properties:
        id:
          type: string
          title: Id
        kind:
          type: string
          title: Kind
        url:
          type: string
          title: Url
        alt_text:
          anyOf:
          - type: string
          - type: 'null'
          title: Alt Text
        width:
          anyOf:
          - type: integer
          - type: 'null'
          title: Width
        height:
          anyOf:
          - type: integer
          - type: 'null'
          title: Height
        bytes:
          anyOf:
          - type: integer
          - type: 'null'
          title: Bytes
      type: object
      required:
      - id
      - kind
      - url
      title: MediaRead
    ApproveItemResponse:
      properties:
        status:
          type: string
          title: Status
        item_id:
          type: string
          title: Item Id
        post_id:
          type: string
          title: Post Id
        variant_ids:
          items:
            type: string
          type: array
          title: Variant Ids
          default: []
        scheduled:
          type: integer
          title: Scheduled
          default: 0
      type: object
      required:
      - status
      - item_id
      - post_id
      title: ApproveItemResponse
    PlanRead:
      properties:
        id:
          type: string
          title: Id
        workspace_id:
          type: string
          title: Workspace Id
        week_of:
          type: string
          format: date-time
          title: Week Of
        goal:
          type: string
          title: Goal
        niche:
          type: string
          title: Niche
        status:
          type: string
          title: Status
        items:
          items:
            $ref: '#/components/schemas/PlanItemRead'
          type: array
          title: Items
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - workspace_id
      - week_of
      - goal
      - niche
      - status
      - items
      - created_at
      title: PlanRead
      example:
        created_at: '2026-07-13T10:00:00Z'
        goal: grow
        id: plan_123
        items:
        - angle: reframe reliability as a principle
          id: item_1
          platforms:
          - x
          prompt: Write about the single rule that governs our tradeoffs.
          scheduled_for: '2026-07-14T09:00:00Z'
          status: draft
          theme: The one-rule philosophy
          why: Tue mornings get 2x engagement for you.
        niche: indie SaaS
        status: draft
        week_of: '2026-07-13T00:00:00Z'
        workspace_id: wks_123
    PlanItemApproveRequest:
      properties:
        scheduled_for:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Scheduled For
        asap:
          type: boolean
          title: Asap
          default: false
        as_draft:
          type: boolean
          title: As Draft
          default: false
      type: object
      title: PlanItemApproveRequest
      description: 'When the post goes out. Nothing set = the planner''s slot (rolled

        forward if it has passed); `asap` = a few minutes from now; a

        `scheduled_for` = exactly then.'
    PlanItemRefineResponse:
      properties:
        item:
          $ref: '#/components/schemas/PlanItemRead'
        message:
          type: string
          title: Message
      type: object
      required:
      - item
      - message
      title: PlanItemRefineResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PlanStackRead:
      properties:
        items:
          items:
            $ref: '#/components/schemas/PlanItemRead'
          type: array
          title: Items
      type: object
      required:
      - items
      title: PlanStackRead
      description: Every post still waiting on a verdict, across weeks — the stack.
    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.
    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
    PlanGenerateRequest:
      properties:
        fresh:
          type: boolean
          title: Fresh
          default: false
      type: object
      title: PlanGenerateRequest
  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.