AdvisorPPC Scheduler API

openapi: 3.2.0
info:
  title: AdvisorPPC Scheduler API
  version: 0.1.0
tags:
- name: Scheduler
paths:
  /api/internal/scheduler/reporting-tick:
    post:
      tags:
      - Scheduler
      summary: Reporting Tick
      description: 'External-cron entry point for the 5-minute reporting dispatcher.


        Separate from the daily agent tick on purpose: reporting must run for every

        selected account on a Free, no-agent workspace too, and it must keep its own

        cadence and its own heartbeat. Same fail-closed shared secret.'
      operationId: reporting_tick_api_internal_scheduler_reporting_tick_post
      parameters:
      - name: x-scheduler-token
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Scheduler-Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: integer
                title: Response Reporting Tick Api Internal Scheduler Reporting Tick Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/internal/scheduler/tick/status:
    get:
      tags:
      - Scheduler
      summary: Scheduler Tick Status
      description: 'Today''s daily pass, read back from ``scheduler_daily_passes``.


        Why (2026-10-23): after a 202 the sweep''s counters lived only in one log

        line of the process that ran it, and a deploy in the sweep window lost

        them. The cron polls this after its 202 and prints the counters; the row

        survives the process. Same fail-closed shared secret as POST /tick.

        Returns today''s cron pass (status, counters, stale flag), every attempt

        of today, the latest finished cron pass, and today''s pass runs by status.

        Counts and ids only: no tenant name, no secret.'
      operationId: scheduler_tick_status_api_internal_scheduler_tick_status_get
      parameters:
      - name: x-scheduler-token
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Scheduler-Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Scheduler Tick Status Api Internal Scheduler Tick Status Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/internal/scheduler/tick:
    post:
      tags:
      - Scheduler
      summary: Scheduler Tick
      description: 'External-cron entry point. Idempotent per (instance, UTC day): call it

        as often as you like; each manager ticks at most once per day.


        ``Prefer: respond-async`` answers 202 as soon as the token checks out and

        runs the same sweep in this process (services/tick_worker.py). The sweep

        takes minutes and Cloudflare cuts a request at 100 s, so the Box 1 cron

        logged http=524 every day while the sweep itself completed (estate map

        2026-10-20). Without the header the call stays synchronous.'
      operationId: scheduler_tick_api_internal_scheduler_tick_post
      parameters:
      - name: x-scheduler-token
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Scheduler-Token
      - name: prefer
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Prefer
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: integer
                title: Response Scheduler Tick Api Internal Scheduler Tick Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    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
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer