Cadencz Channels API

openapi: 3.2.0
info:
  title: Cadencz Channels 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: Channels
  description: Connected publishing accounts.
paths:
  /api/v1/channels:
    get:
      tags:
      - Channels
      summary: List connected channels
      description: Returns the publishing channels connected to the current user's workspace.
      operationId: list_channels_api_v1_channels_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ChannelRead'
                type: array
                title: Response List Channels Api V1 Channels Get
        '401':
          description: Missing or invalid Supabase bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - SupabaseBearerAuth: []
  /api/v1/channels/connect/bluesky:
    post:
      tags:
      - Channels
      summary: Connect a Bluesky account
      description: Authenticates a Bluesky handle with an app password and stores encrypted publishing credentials for the current workspace.
      operationId: connect_bluesky_api_v1_channels_connect_bluesky_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BlueskyConnectRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChannelRead'
        '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'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - SupabaseBearerAuth: []
  /api/v1/channels/connect/slack:
    post:
      tags:
      - Channels
      summary: Connect a Slack channel
      description: Verifies a Slack Incoming Webhook by posting a confirmation message, then stores the webhook URL encrypted for the workspace.
      operationId: connect_slack_api_v1_channels_connect_slack_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SlackConnectRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChannelRead'
        '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'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - SupabaseBearerAuth: []
  /api/v1/channels/connect/devto:
    post:
      tags:
      - Channels
      summary: Connect a dev.to account
      description: Validates a dev.to API key and stores it encrypted. dev.to rather than Medium because Medium stopped issuing API tokens to new integrations in January 2025 — there is no way to onboard a new user there.
      operationId: connect_devto_api_v1_channels_connect_devto_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DevToConnectRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChannelRead'
        '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'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - SupabaseBearerAuth: []
  /api/v1/channels/connect/wordpress:
    post:
      tags:
      - Channels
      summary: Connect a WordPress site
      description: Validates a site URL plus an application password and stores the credential encrypted. Application passwords are issued by WordPress core under Users → Profile and are revocable on their own, so there is no OAuth app to register and no review to wait on.
      operationId: connect_wordpress_api_v1_channels_connect_wordpress_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WordPressConnectRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChannelRead'
        '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'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - SupabaseBearerAuth: []
  /api/v1/channels/connect/telegram/link:
    post:
      tags:
      - Channels
      summary: Start the shared-bot Telegram connect flow
      description: Returns a t.me deep link that opens a private chat with the shared Cadencz bot, carrying a signed, short-lived token that identifies the workspace. Telegram only ever echoes deep-link payloads back on a private /start — there's no equivalent for adding a bot to a channel — so the user is asked to add the bot to their channel afterward, from Telegram's own Administrators screen. Our webhook links the two events by the Telegram user id common to both.
      operationId: telegram_link_api_v1_channels_connect_telegram_link_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TelegramLinkResponse'
        '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'
      security:
      - SupabaseBearerAuth: []
  /api/v1/channels/connect/telegram:
    post:
      tags:
      - Channels
      summary: Connect a Telegram channel
      description: Validates a Telegram bot token and target chat, then stores the token encrypted. The bot must be an admin of the channel/group.
      operationId: connect_telegram_api_v1_channels_connect_telegram_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TelegramConnectRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChannelRead'
        '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'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - SupabaseBearerAuth: []
  /api/v1/channels/connect/reddit/start:
    post:
      tags:
      - Channels
      summary: Start Reddit OAuth
      description: Creates a signed Reddit OAuth state and returns the Reddit authorization URL. Users approve access on Reddit; they do not enter Reddit credentials in Cadencz.
      operationId: start_reddit_oauth_api_v1_channels_connect_reddit_start_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RedditOAuthStartResponse'
        '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'
      security:
      - SupabaseBearerAuth: []
  /api/v1/channels/connect/mastodon/start:
    post:
      tags:
      - Channels
      summary: Start Mastodon OAuth
      description: Registers a Cadencz app on the given Mastodon instance and returns that instance's OAuth approval URL.
      operationId: start_mastodon_oauth_api_v1_channels_connect_mastodon_start_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MastodonOAuthStartRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthStartResponse'
        '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'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - SupabaseBearerAuth: []
  /api/v1/channels/connect/{provider}/start:
    post:
      tags:
      - Channels
      summary: Start OAuth for a social provider
      description: 'Signs an OAuth state and returns the provider''s authorization URL. Supported: x, linkedin, threads, facebook, discord.'
      operationId: start_oauth_api_v1_channels_connect__provider__start_post
      parameters:
      - name: provider
        in: path
        required: true
        schema:
          type: string
          title: Provider
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/OAuthStartRequest'
              - type: 'null'
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthStartResponse'
        '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'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - SupabaseBearerAuth: []
  /api/v1/channels/{channel_id}:
    delete:
      tags:
      - Channels
      summary: Disconnect a channel
      description: Marks a connected publishing channel as disconnected for the current workspace.
      operationId: disconnect_channel_api_v1_channels__channel_id__delete
      parameters:
      - name: channel_id
        in: path
        required: true
        schema:
          type: string
          title: Channel Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '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/channels/{channel_id}/threads/insights:
    get:
      tags:
      - Channels
      summary: Read account-level Threads insights
      description: 'Calls `GET /{threads-user-id}/threads_insights` for a connected Threads channel and returns the metrics Meta reports for the account as a whole — reach, engagement, and follower count.


        Requires the `threads_manage_insights` permission. A channel connected before that scope was requested answers 409 and needs reconnecting.'
      operationId: read_threads_account_insights_api_v1_channels__channel_id__threads_insights_get
      parameters:
      - name: channel_id
        in: path
        required: true
        schema:
          type: string
          title: Channel Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThreadsAccountInsightsResponse'
        '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'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - SupabaseBearerAuth: []
  /api/v1/channels/{channel_id}/threads/profile-lookup:
    get:
      tags:
      - Channels
      summary: Look up a public Threads profile
      description: 'Calls `GET /profile_lookup` using a connected Threads channel''s token to read another creator''s public profile and their last seven days of public engagement.


        Requires the `threads_profile_discovery` permission. Meta only discloses public profiles with at least 100 followers; anything else returns `found: false` rather than an error.'
      operationId: lookup_threads_profile_api_v1_channels__channel_id__threads_profile_lookup_get
      parameters:
      - name: channel_id
        in: path
        required: true
        schema:
          type: string
          title: Channel Id
      - name: username
        in: query
        required: true
        schema:
          type: string
          minLength: 1
          description: Threads handle to look up, with or without the leading @.
          examples:
          - zuck
          title: Username
        description: Threads handle to look up, with or without the leading @.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThreadsProfileLookupResponse'
        '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'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - SupabaseBearerAuth: []
components:
  schemas:
    ThreadsAccountInsightsResponse:
      properties:
        channel_id:
          type: string
          title: Channel Id
        handle:
          type: string
          title: Handle
        metrics:
          additionalProperties:
            type: integer
          type: object
          title: Metrics
          description: Metric name to value. Absent metrics are omitted rather than zeroed.
          examples:
          - followers_count: 1420
            likes: 96
            replies: 12
            views: 1820
      type: object
      required:
      - channel_id
      - handle
      title: ThreadsAccountInsightsResponse
      description: Account-level Threads insights for one connected channel.
    SlackConnectRequest:
      properties:
        webhook_url:
          type: string
          minLength: 1
          title: Webhook Url
          description: Slack Incoming Webhook URL (https://hooks.slack.com/services/…).
          examples:
          - https://hooks.slack.com/services/REDACTED
        display_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Name
          description: Optional label for the channel.
          examples:
          - '#launches'
      type: object
      required:
      - webhook_url
      title: SlackConnectRequest
    TelegramConnectRequest:
      properties:
        bot_token:
          type: string
          minLength: 1
          title: Bot Token
          description: Bot token from @BotFather.
          examples:
          - 123456:ABC-DEF...
        chat_id:
          type: string
          minLength: 1
          title: Chat Id
          description: Target channel/group — @username or numeric chat id. The bot must be an admin.
          examples:
          - '@mychannel'
        display_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Name
          description: Optional label.
          examples:
          - Build Notes
      type: object
      required:
      - bot_token
      - chat_id
      title: TelegramConnectRequest
    BlueskyConnectRequest:
      properties:
        identifier:
          type: string
          minLength: 1
          title: Identifier
          description: Bluesky handle or email.
          examples:
          - cadencz.bsky.social
        app_password:
          type: string
          minLength: 1
          title: App Password
          description: Bluesky app password. Never send the account password.
          examples:
          - abcd-efgh-ijkl-mnop
      type: object
      required:
      - identifier
      - app_password
      title: BlueskyConnectRequest
      example:
        app_password: abcd-efgh-ijkl-mnop
        identifier: cadencz.bsky.social
    StatusResponse:
      properties:
        status:
          type: string
          title: Status
      type: object
      required:
      - status
      title: StatusResponse
      example:
        status: ok
    ChannelRead:
      properties:
        id:
          type: string
          title: Id
        workspace_id:
          type: string
          title: Workspace Id
        platform:
          type: string
          title: Platform
        handle:
          type: string
          title: Handle
        display_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Name
        avatar_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Avatar Url
        status:
          type: string
          title: Status
        byo_app:
          type: boolean
          title: Byo App
        token_expires_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Token Expires At
        followers:
          type: integer
          title: Followers
        capabilities:
          additionalProperties: true
          type: object
          title: Capabilities
        plan_entitled:
          type: boolean
          title: Plan Entitled
          default: true
        entitlement_status:
          type: string
          enum:
          - available
          - plan_paused
          - disconnected
          title: Entitlement Status
          default: available
        plan_pause_reason:
          anyOf:
          - type: string
            enum:
            - plan_required
            - workspace_limit
            - platform_limit
          - type: 'null'
          title: Plan Pause Reason
      type: object
      required:
      - id
      - workspace_id
      - platform
      - handle
      - display_name
      - avatar_url
      - status
      - byo_app
      - token_expires_at
      - followers
      title: ChannelRead
      example:
        avatar_url: https://example.com/avatar.png
        byo_app: false
        display_name: Cadencz
        followers: 42
        handle: cadencz.bsky.social
        id: chn_123
        platform: bluesky
        status: connected
        workspace_id: wks_123
    TelegramLinkResponse:
      properties:
        bot_username:
          type: string
          title: Bot Username
        deep_link:
          type: string
          title: Deep Link
        token:
          type: string
          title: Token
      type: object
      required:
      - bot_username
      - deep_link
      - token
      title: TelegramLinkResponse
      description: Deep link that adds the shared Cadencz bot to a channel.
    OAuthStartRequest:
      properties:
        learn_voice:
          type: boolean
          title: Learn Voice
          description: After the account connects, read its ten most recent posts once and save them as writing samples on the Writing style page. X only — LinkedIn does not let an app read a member's posts.
          default: false
      type: object
      title: OAuthStartRequest
      description: Options that ride the OAuth round-trip in the signed state.
    OAuthStartResponse:
      properties:
        authorization_url:
          type: string
          title: Authorization Url
          description: Provider OAuth approval URL.
      type: object
      required:
      - authorization_url
      title: OAuthStartResponse
      description: 'Returned by any provider''s OAuth start endpoint; the frontend redirects

        the browser to `authorization_url`.'
    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
    ThreadsProfileLookupResponse:
      properties:
        username:
          type: string
          title: Username
        found:
          type: boolean
          title: Found
        profile:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Profile
          examples:
          - follower_count: 4000000
            is_verified: true
            name: Mark Zuckerberg
            username: zuck
            views_count: 120000
      type: object
      required:
      - username
      - found
      title: ThreadsProfileLookupResponse
      description: 'A public Threads profile, when Meta has one to give.


        `found` is false — not an error — for a handle that does not exist, is

        private, or sits under Meta''s 100-follower disclosure floor.'
    DevToConnectRequest:
      properties:
        api_key:
          type: string
          title: Api Key
          description: dev.to API key.
          examples:
          - abcd1234...
        display_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Name
          description: Optional label for the channel.
      type: object
      required:
      - api_key
      title: DevToConnectRequest
      description: Connect dev.to by pasting the API key from Settings → Extensions.
    MastodonOAuthStartRequest:
      properties:
        instance_url:
          type: string
          minLength: 1
          title: Instance Url
          description: The Mastodon instance to connect (host or URL).
          examples:
          - mastodon.social
      type: object
      required:
      - instance_url
      title: MastodonOAuthStartRequest
    RedditOAuthStartResponse:
      properties:
        authorization_url:
          type: string
          title: Authorization Url
          description: Reddit OAuth approval URL.
      type: object
      required:
      - authorization_url
      title: RedditOAuthStartResponse
    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
    WordPressConnectRequest:
      properties:
        site_url:
          type: string
          title: Site Url
          description: Your site address.
          examples:
          - example.com
        username:
          type: string
          title: Username
          description: Your WordPress username.
          examples:
          - akshay
        app_password:
          type: string
          title: App Password
          description: Application password from Users -> Profile.
        display_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Name
          description: Optional label for the channel.
      type: object
      required:
      - site_url
      - username
      - app_password
      title: WordPressConnectRequest
      description: Connect a self-hosted or WordPress.com site with an application password.
  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.