Cadencz Agents API

openapi: 3.2.0
info:
  title: Cadencz Agents 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: Agents
  description: Multi-agent graph runs and their per-agent trace.
paths:
  /api/v1/agents/run:
    post:
      tags:
      - Agents
      summary: Run the agent graph
      description: Executes the Cadencz agent graph for one request and returns the run with its full per-agent trace. Phase A route is 'answer' (a strict one-line assistant).
      operationId: run_agents_api_v1_agents_run_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentRunRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentRunRead'
        '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/agents/runs:
    get:
      tags:
      - Agents
      summary: List recent agent runs + traces
      operationId: list_agent_runs_api_v1_agents_runs_get
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 20
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AgentRunRead'
                title: Response List Agent Runs Api V1 Agents Runs Get
        '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/agents/runs/{run_id}:
    get:
      tags:
      - Agents
      summary: Get an agent run + trace
      operationId: get_agent_run_api_v1_agents_runs__run_id__get
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          title: Run Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentRunRead'
        '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: []
components:
  schemas:
    AgentRunRequest:
      properties:
        input:
          type: string
          maxLength: 8000
          minLength: 1
          title: Input
          description: What the user is asking the agent graph to do.
          examples:
          - Write a launch post about our new Google sign-in.
        tags:
          items:
            type: string
          type: array
          maxItems: 12
          title: Tags
          description: 'Strict allow-list tags that steer the graph (e.g. #reddit, #hook, #shorten).'
          examples:
          - - '#hook'
        platform:
          anyOf:
          - type: string
            maxLength: 40
          - type: 'null'
          title: Platform
          description: Optional target platform for this run.
          examples:
          - twitter
        brain_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Brain Id
          description: Optional Brain id/slug to ground the run in saved product knowledge.
        route:
          type: string
          maxLength: 40
          title: Route
          description: 'Graph route: ''answer'' (strict one-line) or ''generate_post''.'
          default: answer
        read_source:
          type: string
          maxLength: 20
          title: Read Source
          description: 'Reader source: ''paste'' | ''rss'' | ''x'' (x is flagged off in v1).'
          default: paste
        read_input:
          anyOf:
          - type: string
            maxLength: 20000
          - type: 'null'
          title: Read Input
          description: Optional material for the Reader agent — pasted text or an RSS URL.
      type: object
      required:
      - input
      title: AgentRunRequest
    AgentRunRead:
      properties:
        id:
          type: string
          title: Id
        workspace_id:
          type: string
          title: Workspace Id
        route:
          type: string
          title: Route
          description: The graph route (stored as the run 'stage').
        status:
          type: string
          title: Status
        tags:
          items:
            type: string
          type: array
          title: Tags
        input_text:
          anyOf:
          - type: string
          - type: 'null'
          title: Input Text
        output_json:
          additionalProperties: true
          type: object
          title: Output Json
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
        tokens_used:
          type: integer
          title: Tokens Used
        model_provider:
          anyOf:
          - type: string
          - type: 'null'
          title: Model Provider
        model_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Model Name
        steps:
          items:
            $ref: '#/components/schemas/AgentStepRead'
          type: array
          title: Steps
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
      - id
      - workspace_id
      - route
      - status
      - tags
      - input_text
      - output_json
      - error
      - tokens_used
      - model_provider
      - model_name
      - steps
      - created_at
      - updated_at
      title: AgentRunRead
      example:
        created_at: '2026-07-13T10:00:00Z'
        id: run_123
        input_text: Write a launch post about Google sign-in.
        model_name: deepseek-chat
        model_provider: deepseek
        output_json:
          text: Google sign-in is live — one tap in, zero password resets.
        route: answer
        status: succeeded
        steps: []
        tags:
        - '#hook'
        tokens_used: 56
        updated_at: '2026-07-13T10:00:01Z'
        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
    AgentStepRead:
      properties:
        id:
          type: string
          title: Id
        sequence:
          type: integer
          title: Sequence
        agent_name:
          type: string
          title: Agent Name
        tier:
          type: string
          title: Tier
        provider:
          anyOf:
          - type: string
          - type: 'null'
          title: Provider
        model:
          anyOf:
          - type: string
          - type: 'null'
          title: Model
        status:
          type: string
          title: Status
        attempt:
          type: integer
          title: Attempt
        output_json:
          additionalProperties: true
          type: object
          title: Output Json
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
        input_tokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Input Tokens
        output_tokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Output Tokens
        total_tokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Total Tokens
        cached_input_tokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Cached Input Tokens
        latency_ms:
          anyOf:
          - type: integer
          - type: 'null'
          title: Latency Ms
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - sequence
      - agent_name
      - tier
      - provider
      - model
      - status
      - attempt
      - output_json
      - error
      - input_tokens
      - output_tokens
      - total_tokens
      - cached_input_tokens
      - latency_ms
      - created_at
      title: AgentStepRead
    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.