Cadencz Posts API

openapi: 3.2.0
info:
  title: Cadencz Posts 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: Posts
  description: Posts, variants, scheduling, and publishing actions.
paths:
  /api/v1/posts:
    get:
      tags:
      - Posts
      summary: List posts
      description: Returns posts and variants for the current user's active workspace.
      operationId: list_posts_api_v1_posts_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/PostRead'
                type: array
                title: Response List Posts Api V1 Posts Get
        '401':
          description: Missing or invalid Supabase bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - SupabaseBearerAuth: []
    post:
      tags:
      - Posts
      summary: Create a post
      description: Creates a post and one or more channel-specific variants. Variants with `scheduled_at` are persisted for the Cloudflare Cron worker.
      operationId: create_post_api_v1_posts_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostCreate'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostRead'
        '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'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - SupabaseBearerAuth: []
  /api/v1/posts/published:
    get:
      tags:
      - Posts
      summary: What has gone out, a page at a time
      description: Published variants newest first, ten by default, with their media resolved. Pass the previous page's `next_cursor` as `before` for the next page.
      operationId: list_published_api_v1_posts_published_get
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 10
          title: Limit
      - name: before
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Before
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublishedPageRead'
        '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/posts/counts:
    get:
      tags:
      - Posts
      summary: Get lightweight post counts for the app shell
      operationId: post_counts_api_v1_posts_counts_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostCounts'
        '401':
          description: Missing or invalid Supabase bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - SupabaseBearerAuth: []
  /api/v1/variants/{variant_id}:
    patch:
      tags:
      - Posts
      summary: Update a post variant
      description: Updates editable copy or media for a draft, scheduled, or failed variant.
      operationId: update_variant_api_v1_variants__variant_id__patch
      parameters:
      - name: variant_id
        in: path
        required: true
        schema:
          type: string
          title: Variant Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateVariantRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VariantRead'
        '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: []
    delete:
      tags:
      - Posts
      summary: Delete a post variant
      description: Permanently deletes a variant (and its schedule). Published variants can't be deleted.
      operationId: delete_variant_api_v1_variants__variant_id__delete
      parameters:
      - name: variant_id
        in: path
        required: true
        schema:
          type: string
          title: Variant 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'
        '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/variants/{variant_id}/schedule:
    post:
      tags:
      - Posts
      summary: Schedule a variant
      description: Schedules or reschedules a variant for the Cloudflare Cron worker.
      operationId: schedule_variant_api_v1_variants__variant_id__schedule_post
      parameters:
      - name: variant_id
        in: path
        required: true
        schema:
          type: string
          title: Variant Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScheduleVariantRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VariantRead'
        '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/variants/{variant_id}/cancel:
    post:
      tags:
      - Posts
      summary: Cancel a variant
      description: Cancels a draft, scheduled, or failed variant before publishing has started.
      operationId: cancel_variant_api_v1_variants__variant_id__cancel_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/VariantRead'
        '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/variants/{variant_id}/publish-now:
    post:
      tags:
      - Posts
      summary: Publish a variant now
      description: 'Publishes a draft, scheduled, or failed variant immediately and synchronously — the response reflects the real publish outcome rather than waiting for the scheduler. Also the retry path for a failed post: it posts instantly instead of waiting for its (past) scheduled time.'
      operationId: publish_now_api_v1_variants__variant_id__publish_now_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/VariantRead'
        '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'
        '400':
          description: The request payload is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: The platform rejected the publish; safe to retry.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - SupabaseBearerAuth: []
  /api/v1/posts/{post_id}:
    delete:
      tags:
      - Posts
      summary: Delete a post and all its variants
      description: Permanently deletes a post and every variant/schedule under it (published excepted).
      operationId: delete_post_api_v1_posts__post_id__delete
      parameters:
      - name: post_id
        in: path
        required: true
        schema:
          type: string
          title: Post 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'
        '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:
    UpdateVariantRequest:
      properties:
        body:
          anyOf:
          - type: string
          - type: 'null'
          title: Body
          examples:
          - Updated post copy for Bluesky.
        media_ids:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Media Ids
        platform_target:
          anyOf:
          - type: string
          - type: 'null'
          title: Platform Target
          examples:
          - r/test
        channel_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Channel Id
          description: Assign a channel to an unscheduled draft.
      type: object
      title: UpdateVariantRequest
      example:
        body: Updated post copy for Bluesky.
        media_ids: []
    PostCreate:
      properties:
        idea:
          type: string
          minLength: 1
          title: Idea
          examples:
          - Turn this product changelog into a Bluesky post.
        source:
          type: string
          enum:
          - manual
          - agent
          title: Source
          default: manual
        brain_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Brain Id
          examples:
          - brain_123
        timezone:
          type: string
          title: Timezone
          description: IANA zone the schedule times were chosen in. `scheduled_at` is already absolute, so this does not move the post — it records what the customer meant, which is what a later reschedule or a best-time read has to honour.
          default: UTC
          examples:
          - Asia/Kolkata
        variants:
          items:
            $ref: '#/components/schemas/VariantCreate'
          type: array
          title: Variants
      type: object
      required:
      - idea
      title: PostCreate
      example:
        brain_id: brain_123
        idea: Turn this product changelog into a Bluesky post.
        source: manual
        variants:
        - body: Cadencz now supports scheduled Bluesky posts.
          channel_id: chn_123
          media_ids: []
          platform: bluesky
          scheduled_at: '2026-07-08T10:30:00Z'
    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
    ScheduleVariantRequest:
      properties:
        scheduled_at:
          type: string
          format: date-time
          title: Scheduled At
          examples:
          - '2026-07-08T10:30:00Z'
        timezone:
          type: string
          minLength: 1
          title: Timezone
          default: UTC
      type: object
      required:
      - scheduled_at
      title: ScheduleVariantRequest
      example:
        scheduled_at: '2026-07-08T10:30:00Z'
        timezone: Asia/Calcutta
    PublishedPageRead:
      properties:
        items:
          items:
            $ref: '#/components/schemas/VariantRead'
          type: array
          title: Items
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
      type: object
      title: PublishedPageRead
      description: A page of what has gone out, newest first, and where the next page starts.
    PostRead:
      properties:
        id:
          type: string
          title: Id
        workspace_id:
          type: string
          title: Workspace Id
        idea:
          type: string
          title: Idea
        source:
          type: string
          title: Source
        brain_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Brain Id
        variants:
          items:
            $ref: '#/components/schemas/VariantRead'
          type: array
          title: Variants
      type: object
      required:
      - id
      - workspace_id
      - idea
      - source
      - brain_id
      title: PostRead
      example:
        brain_id: brain_123
        id: pst_123
        idea: Turn this product changelog into a Bluesky post.
        source: manual
        variants:
        - attempt_count: 0
          body: Cadencz now supports scheduled Bluesky posts.
          channel_id: chn_123
          id: var_123
          media_ids: []
          platform: bluesky
          post_id: pst_123
          scheduled_at: '2026-07-08T10:30:00Z'
          status: scheduled
        workspace_id: wks_123
    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
    PostCounts:
      properties:
        awaiting_review:
          type: integer
          title: Awaiting Review
          default: 0
      type: object
      title: PostCounts
      description: Small shell payload for badges that do not need complete post bodies.
    VariantRead:
      properties:
        id:
          type: string
          title: Id
        post_id:
          type: string
          title: Post Id
        channel_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Channel Id
        platform:
          type: string
          title: Platform
        body:
          type: string
          title: Body
        media_ids:
          items:
            type: string
          type: array
          title: Media Ids
        media:
          items:
            $ref: '#/components/schemas/MediaRead'
          type: array
          title: Media
        platform_target:
          anyOf:
          - type: string
          - type: 'null'
          title: Platform Target
        status:
          type: string
          title: Status
        scheduled_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Scheduled At
        published_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Published At
        provider_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Provider Url
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
        attempt_count:
          type: integer
          title: Attempt Count
        content_metadata:
          additionalProperties: true
          type: object
          title: Content Metadata
        thread_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Thread Id
        thread_position:
          anyOf:
          - type: integer
          - type: 'null'
          title: Thread Position
      type: object
      required:
      - id
      - post_id
      - channel_id
      - platform
      - body
      - media_ids
      - platform_target
      - status
      - scheduled_at
      - published_at
      - provider_url
      - error
      - attempt_count
      title: VariantRead
      example:
        attempt_count: 0
        body: Cadencz now supports scheduled Bluesky posts.
        channel_id: chn_123
        id: var_123
        media_ids: []
        platform: bluesky
        post_id: pst_123
        scheduled_at: '2026-07-08T10:30:00Z'
        status: scheduled
    VariantCreate:
      properties:
        channel_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Channel Id
          examples:
          - chn_123
        platform:
          type: string
          title: Platform
          examples:
          - bluesky
        body:
          type: string
          minLength: 1
          title: Body
          examples:
          - Shipping a compact update from Cadencz today.
        media_ids:
          items:
            type: string
          type: array
          title: Media Ids
        platform_target:
          anyOf:
          - type: string
          - type: 'null'
          title: Platform Target
          description: Optional platform-specific destination, e.g. Reddit subreddit.
          examples:
          - r/test
        scheduled_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Scheduled At
          examples:
          - '2026-07-08T10:30:00Z'
        content_metadata:
          additionalProperties: true
          type: object
          title: Content Metadata
        thread_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Thread Id
        thread_position:
          anyOf:
          - type: integer
            minimum: 0.0
          - type: 'null'
          title: Thread Position
      type: object
      required:
      - platform
      - body
      title: VariantCreate
    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.