Cadencz Jobs API

openapi: 3.2.0
info:
  title: Cadencz Jobs 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: Jobs
  description: Worker callbacks for scheduled publishing.
paths:
  /api/v1/jobs/publish-due:
    post:
      tags:
      - Jobs
      summary: Publish due scheduled variants
      description: Cloudflare Cron callback endpoint. Authenticates with `WORKER_SECRET`, claims due scheduled variants from the database, and publishes them. This is the preferred scheduler path for posts scheduled more than a few days ahead.
      operationId: publish_due_job_api_v1_jobs_publish_due_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublishDueJobResponse'
        '401':
          description: Missing or invalid worker secret.
          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'
  /api/v1/jobs/plan-week:
    post:
      tags:
      - Jobs
      summary: Auto-generate this week's plan for workspaces due right now
      description: 'Cloudflare Cron callback. **Must be scheduled hourly (`0 * * * *`)**, not weekly.


        Each workspace picks its own planning weekday, hour, and timezone in its automation settings; this endpoint plans only the workspaces whose configured hour is the current one. An hourly tick is what turns a single global cron into per-workspace scheduling without a job queue — run it weekly and almost every workspace is skipped.


        Authenticates with `WORKER_SECRET`. Auto-planning is opt-in per workspace and is idempotent: a workspace that already has a plan for the current week is skipped.'
      operationId: plan_week_job_api_v1_jobs_plan_week_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanWeekJobResponse'
        '401':
          description: Missing or invalid worker secret.
          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'
  /api/v1/jobs/replan-months:
    post:
      tags:
      - Jobs
      summary: Re-plan the month for workspaces whose plan has lapsed
      description: 'Cloudflare Cron callback. Safe to run hourly: the `generated_for` stamp on each stored month plan makes the work once-per-workspace-per-month, so every call after the first is a cheap no-op.


        Each re-plan reads the Brain profile plus last month''s analytics and published posts, and draws one Brain-analysis allowance unit — a workspace with none left (Free after its lifetime unit) is skipped, not failed. Authenticates with `WORKER_SECRET`.'
      operationId: replan_months_job_api_v1_jobs_replan_months_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonthReplanJobResponse'
        '401':
          description: Missing or invalid worker secret.
          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'
  /api/v1/jobs/refresh-analytics:
    post:
      tags:
      - Jobs
      summary: Refresh engagement metrics for recently published posts
      description: 'Cloudflare Cron callback. **Schedule hourly (`15 * * * *`)**, not daily.


        The tick is hourly but each platform decides for itself whether it is due, based on what its API costs: free, generously rate-limited reads (Bluesky, Mastodon, Reddit, Threads, Facebook, dev.to, LinkedIn) refresh every hour, while X — whose tweet lookup requires a paid tier with a monthly read quota — refreshes once a day. Running this hourly is what lets one cron serve both cadences; running it daily would silently downgrade every platform to daily.


        Only posts Cadencz published, and only the last 30 days, are read. A failure on one platform or channel never stops the rest — the response reports each outcome separately.


        Authenticates with `WORKER_SECRET`.'
      operationId: refresh_analytics_job_api_v1_jobs_refresh_analytics_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefreshAnalyticsJobResponse'
        '401':
          description: Missing or invalid worker secret.
          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'
components:
  schemas:
    MonthReplanJobResponse:
      properties:
        status:
          type: string
          title: Status
        checked:
          type: integer
          title: Checked
        replanned:
          type: integer
          title: Replanned
        skipped:
          type: integer
          title: Skipped
        failed:
          type: integer
          title: Failed
      type: object
      required:
      - status
      - checked
      - replanned
      - skipped
      - failed
      title: MonthReplanJobResponse
    PublishDueJobResponse:
      properties:
        status:
          type: string
          const: ok
          title: Status
        checked:
          type: integer
          title: Checked
        claimed:
          type: integer
          title: Claimed
        published:
          type: integer
          title: Published
        failed:
          type: integer
          title: Failed
        retryable:
          type: integer
          title: Retryable
        skipped:
          type: integer
          title: Skipped
      type: object
      required:
      - status
      - checked
      - claimed
      - published
      - failed
      - retryable
      - skipped
      title: PublishDueJobResponse
      example:
        checked: 3
        claimed: 3
        failed: 0
        published: 2
        retryable: 1
        skipped: 0
        status: ok
    RefreshAnalyticsWorkspaceResult:
      properties:
        workspace_id:
          type: string
          title: Workspace Id
        status:
          type: string
          enum:
          - ok
          - partial
          - failed
          - empty
          title: Status
        refreshed:
          type: integer
          title: Refreshed
        platforms:
          items:
            $ref: '#/components/schemas/RefreshAnalyticsPlatformResult'
          type: array
          title: Platforms
          default: []
      type: object
      required:
      - workspace_id
      - status
      - refreshed
      title: RefreshAnalyticsWorkspaceResult
    PlanWeekJobResponse:
      properties:
        status:
          type: string
          const: ok
          title: Status
        workspaces:
          type: integer
          title: Workspaces
        planned:
          type: integer
          title: Planned
        skipped:
          type: integer
          title: Skipped
        failed:
          type: integer
          title: Failed
      type: object
      required:
      - status
      - workspaces
      - planned
      - skipped
      - failed
      title: PlanWeekJobResponse
      example:
        failed: 0
        planned: 4
        skipped: 8
        status: ok
        workspaces: 12
    RefreshAnalyticsPlatformResult:
      properties:
        platform:
          type: string
          title: Platform
        status:
          type: string
          enum:
          - ok
          - partial
          - failed
          - skipped
          - unsupported
          title: Status
        posts:
          type: integer
          title: Posts
        refreshed:
          type: integer
          title: Refreshed
        detail:
          anyOf:
          - type: string
          - type: 'null'
          title: Detail
      type: object
      required:
      - platform
      - status
      - posts
      - refreshed
      title: RefreshAnalyticsPlatformResult
    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.
    RefreshAnalyticsJobResponse:
      properties:
        status:
          type: string
          const: ok
          title: Status
        workspaces:
          type: integer
          title: Workspaces
        refreshed:
          type: integer
          title: Refreshed
        failed_platforms:
          type: integer
          title: Failed Platforms
        workspaces_detail:
          items:
            $ref: '#/components/schemas/RefreshAnalyticsWorkspaceResult'
          type: array
          title: Workspaces Detail
          default: []
      type: object
      required:
      - status
      - workspaces
      - refreshed
      - failed_platforms
      title: RefreshAnalyticsJobResponse
      example:
        failed_platforms: 1
        refreshed: 240
        status: ok
        workspaces: 12
        workspaces_detail: []
  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.