AI Demos Aggregates API

openapi: 3.2.0
info:
  title: Aidemos Com Aggregates API
  version: 0.1.0
  description: 'Operations tagged aggregates across 2 of this provider''s published API definitions: aidemos-com-openapi.json, mcp-openapi.json. Each path carries the servers of the definition it was published in.'
tags:
- name: aggregates
paths:
  /v1/cost/rollup:
    get:
      tags:
      - aggregates
      summary: Cost Rollup
      description: 'Per-job-type rollup: runs, tokens, usd, p50/p95 latency — over the most recent jobs.'
      operationId: cost_rollup_v1_cost_rollup_get
      parameters:
      - name: limit_jobs
        in: query
        required: false
        schema:
          type: integer
          maximum: 20000
          default: 2000
          title: Limit Jobs
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Cost Rollup V1 Cost Rollup Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/work-queue:
    get:
      tags:
      - aggregates
      summary: Work Queue
      description: 'Dashboard aggregate: status counts (24h + all) + recent attention/runs/reviews.'
      operationId: work_queue_v1_work_queue_get
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Work Queue V1 Work Queue Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/coverage:
    get:
      tags:
      - aggregates
      summary: Coverage
      description: 'Research-task ↔ tool coverage: what the CURRENT evidence run tested, next to what shipped.


        `tools` is the roster of the newest run that actually produced observations for the task — NOT

        the union across every historical re-run. The union was wrong twice over: it re-counted renamed

        identities (#121 — `nutrient` and `nutrient-io` are one product, `adobe-api` and

        `adobe-pdf-extract-api` are one product) and it kept superseded rosters alive forever. `/v1/tools`

        below already carries the same `DISTINCT ON` current-run filter for exactly this reason; coverage

        never got it, so `86b9h7t37` advertised 13 tools for a task whose every run tested 10 and whose

        published page ranks 8.


        `published` is the tool count on the published ranking page(s) bound to this task''s runs via

        `page_content.source_run_id` — the honest denominator for "did the research reach the site".

        Counts only: 75 of 139 published ranking entries still carry `tool.slug = null` (name-only refs

        from the payload migration + draft-publish), so per-tool tested-vs-published attribution would

        need the same-tool LLM judge, not a name match (directive #5). Tracked on #121/#122.'
      operationId: coverage_v1_coverage_get
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Coverage V1 Coverage Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/tools:
    get:
      tags:
      - aggregates
      summary: List Tools
      description: 'Tool catalog: every tool with observation + research-task counts.


        Counts only CURRENT observations — per (tool, research task), the newest run that has

        observations for that tool. Superseded re-runs of the same task used to inflate the count

        (the console advertised "48 obs" for a bundle whose current evidence was 27, 86bazw0dz).'
      operationId: list_tools_v1_tools_get
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response List Tools V1 Tools Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/rankings:
    get:
      tags:
      - aggregates
      summary: List Rankings
      description: 'Ranking syntheses: research task + final take + best-for + tool count (latest per task).'
      operationId: list_rankings_v1_rankings_get
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response List Rankings V1 Rankings Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/reviews:
    get:
      tags:
      - aggregates
      summary: List Reviews
      description: 'Persisted AI reviews from `sip.ai_reviews` — the durable scorecard log (better than parsing

        job results). Powers AI-review history, the publishing board, and the leaderboard.


        `days` scopes the history to a trailing period window (24h=1, 7d, 30d) so the console can filter

        at the source instead of over-fetching then hiding rows — authoritative as the log grows.'
      operationId: list_reviews_v1_reviews_get
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          default: 100
          title: Limit
      - name: subject
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Subject
      - name: days
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            maximum: 3650
            minimum: 1
          - type: 'null'
          description: only reviews created within the last N days (period window)
          title: Days
        description: only reviews created within the last N days (period window)
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response List Reviews V1 Reviews Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/researcher-leaderboard:
    get:
      tags:
      - aggregates
      summary: Researcher Leaderboard
      description: 'Rank RESEARCHERS by the CURRENT score of each thing they produced.


        Item = one research task''s overall verdict (the research/ranking score) or one tool report

        (the tool-page score). Score of record = the LATEST review of the item; earlier iterations

        only surface as `runs` (rework signal). Pass rate = share of items whose CURRENT verdict is

        publishable. Attribution is persisted (`sip.researcher_subjects`/`researcher_pages`).


        Windows (7d/30d/all) include an item when its latest review falls in the window; the trend

        compares against items whose as-of score dated in the previous equal window (computed from a

        time-bounded latest-per-item pass, so a re-reviewed item is compared at its then-current

        score). Response also carries the flat `items` list for the console''s sortable/filterable

        "Page scores" view, and per-researcher item lists for drilldowns.'
      operationId: researcher_leaderboard_v1_researcher_leaderboard_get
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Researcher Leaderboard V1 Researcher Leaderboard Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/researcher-leaderboard/refresh:
    post:
      tags:
      - aggregates
      summary: Refresh Researcher Attribution
      description: 'Incremental attribution: resolve ClickUp assignees (task, else parent task) for review

        subjects that have no researcher link yet and attribute them (new name variants judged by

        the LLM canonicalizer). The review job runs the same routine per subject on completion, so

        this endpoint is now a manual catch-up, not a required maintenance step. Full rebuilds

        (incl. Payload page authors) stay in scripts/backfill_researcher_attribution.py.'
      operationId: refresh_researcher_attribution_v1_researcher_leaderboard_refresh_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Refresh Researcher Attribution V1 Researcher Leaderboard Refresh 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
x-refined-from:
- aidemos-com-openapi.json
- mcp-openapi.json