AI Demos Site Read API

openapi: 3.2.0
info:
  title: Aidemos Com Site Read API
  version: 0.1.0
  description: 'Operations tagged site-read 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: site-read
paths:
  /v1/redirects:
    get:
      tags:
      - site-read
      summary: List Redirects
      description: 'Catalog redirects (#55 apply actions: folds/merges). The website middleware consumes this so

        a folded page 301s to its canonical target instead of 404ing; sitemap/MCP honor it too. Public

        read-only, same posture as the page reads.'
      operationId: list_redirects_v1_redirects_get
      parameters:
      - name: page_type
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Page Type
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response List Redirects V1 Redirects Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/pages/{page_type}/{slug}:
    get:
      tags:
      - site-read
      summary: Get Page Content
      description: 'Effective neutral content for a page = deep_merge(canonical, human override). The Next.js

        renderer (and the .md/LLM surface) template this — presentation-agnostic, no layout. Serves only

        PUBLISHED rows: a draft/unpublished page 404s here (the renderer then falls back to Payload on a

        miss, exactly like a legacy record).'
      operationId: get_page_content_v1_pages__page_type___slug__get
      parameters:
      - name: page_type
        in: path
        required: true
        schema:
          type: string
          title: Page Type
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Page Content V1 Pages  Page Type   Slug  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/pages/{page_type}/{slug}/preview:
    get:
      tags:
      - site-read
      summary: Get Page Preview
      description: 'DRAFT-capable effective content for the website''s preview mode (ClickUp 86baqvuvz/86bapky0f:

        drafted pages 404 on the live site by design — this is the sanctioned way to view them). Guarded

        by a DEDICATED low-power secret (env PREVIEW_SECRET) — deliberately NOT the service token, so the

        frontend never needs the broad-power token and the worst a leaked key exposes is read-only draft

        content. Unset secret = endpoint disabled (403).'
      operationId: get_page_preview_v1_pages__page_type___slug__preview_get
      parameters:
      - name: page_type
        in: path
        required: true
        schema:
          type: string
          title: Page Type
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      - name: key
        in: query
        required: false
        schema:
          type: string
          default: ''
          title: Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Page Preview V1 Pages  Page Type   Slug  Preview Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/pages/{page_type}:
    get:
      tags:
      - site-read
      summary: List Page Content
      description: 'Enumerate PUBLISHED slugs that have content for a page_type (sitemap / shadow-diff / coverage).

        Drafts are excluded so they never leak into the sitemap.'
      operationId: list_page_content_v1_pages__page_type__get
      parameters:
      - name: page_type
        in: path
        required: true
        schema:
          type: string
          title: Page Type
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 2000
          default: 500
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response List Page Content V1 Pages  Page Type  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/observations/{observation_id}:
    get:
      tags:
      - site-read
      summary: Get Observation
      description: 'PUBLIC evidence permalink read (S5): one observation cell by UUID, complete enough to stand

        on its own and be shared — the claim, the QUESTION it answers (`criteria.definition` + rank

        role + judge reasoning), the INPUT the tool was actually given (verbatim prompt and/or durable

        input files, resolved), what it produced, full provenance, its TRUE peers (same input AND same

        criterion), the other checks run on the same input, and the published pages this evidence

        supports (#359).


        Composed by `services/evidence_cell.observation_detail`, which the MCP `get_evidence` envelope

        also uses for the input/question facts — so the agent surface and the human surface cannot

        disagree about what was fed in.


        Unauthenticated (the frontend carries no service token). PUBLISH-GATED the same way the

        `get_evidence` MCP verb is: a cell leaves when its TOOL has a published page (resolved through

        the #336 id binding — never a cross-namespace string compare, #310) OR its RUN is bound to a

        published ranking (the deliberate relaxation the ranking bundle already has — a ranked tool

        without its own detail page still shows its findings on the ranking that tested it, and the MCP

        emits those permalinks, so this read must honour them or hand agents dead links). 404 on

        malformed / missing / genuinely-unpublished id.'
      operationId: get_observation_v1_observations__observation_id__get
      parameters:
      - name: observation_id
        in: path
        required: true
        schema:
          type: string
          title: Observation Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Observation V1 Observations  Observation Id  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/pages/ranking/{slug}/evidence:
    get:
      tags:
      - site-read
      summary: Get Ranking Evidence
      description: 'PUBLIC evidence bundle for one published ranking page (S6) — everything the evidence-first

        ranking render needs, in one call, scoped to the page''s OWN research run.


        Why a dedicated bundle instead of the per-tool `get_evidence` join: tool slugs are reused across

        research studies (prod 2026-07-11: `elevenlabs` carries 168/200 findings from the voice-cloning

        study on the dubbing page), so a global-by-slug join renders another topic''s evidence. The page''s

        research run is the STORED binding `page_content.source_run_id` via the shared resolver (#146,

        `services/run_binding.py`) — the same fact script-gen and MCP resolve, so surfaces cannot

        disagree. Every score/finding returned belongs to that single run; joins are slug equality only.


        Publish line: gated on the RANKING PAGE being published (this bundle is that page''s own render

        data). Deliberately NOT per-tool-page gated — a ranked tool without its own detail page (e.g.

        claude-artifacts, #122) must still show its findings on the ranking that tested it.


        Coverage is returned so the renderer can gate the new UI and fall back to the legacy render

        below threshold — an empty/near-empty grid must never ship.


        Draft preview (86bazxexw): with a valid PREVIEW_SECRET `key`, the bundle serves DRAFT pages

        too — same low-power secret and same draft-preference rules as /preview, and the run is the

        DRAFT''s own binding. Without it, a never-published ranking previewed via Draft Mode fell back

        to the legacy render, which reporters read as "Preview shows the outdated page design".'
      operationId: get_ranking_evidence_v1_pages_ranking__slug__evidence_get
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      - name: key
        in: query
        required: false
        schema:
          type: string
          default: ''
          title: Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Ranking Evidence V1 Pages Ranking  Slug  Evidence Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/pages/tool/{slug}/criteria:
    get:
      tags:
      - site-read
      summary: Get Tool Criteria
      description: 'PUBLIC per-criterion verdicts for ONE tool page (#446, Ajay 86bbh1faj).


        The generator deliberately reclassifies a report''s evaluation criteria into fewer, broader

        feature cards (`FEATURE_DEFINITION`: *"an evaluation CRITERION … is NOT a feature"*), so the

        researcher''s own dimensions — which the RANKING page ranks on — had NO surface on the tool

        page at all: /tools/doctr showed 2 invented feature names over a 9-criterion report. This

        endpoint serves the report''s dimensions verbatim so the tool page can render its

        "How it scored on the research''s own criteria" section.


        Everything here is the study''s recorded substrate re-served, never re-derived: criteria come

        from the run''s own catalog, the score/summary from `sip.tool_scores` (dimension=''criterion''),

        the per-input dots are the observations'' verdict strings verbatim, and a criterion with no

        recorded run ships `exercised: false` — the section cannot invent a score. The same three

        scope predicates as the ranking evidence bundle apply (#451 finding scope, 86bbbc6jq

        scenario scope), so the two surfaces cannot disagree about what this round asked.


        Draft preview: with a valid PREVIEW_SECRET `key` the newest pending draft''s run serves —

        same rules as the ranking evidence bundle — so a not-yet-published page (DocTR) shows the

        section in preview.'
      operationId: get_tool_criteria_v1_pages_tool__slug__criteria_get
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      - name: key
        in: query
        required: false
        schema:
          type: string
          default: ''
          title: Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Tool Criteria V1 Pages Tool  Slug  Criteria Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/tools/{slug}/rankings:
    get:
      tags:
      - site-read
      summary: Get Tool Rankings
      description: 'PUBLIC reverse lookup (86bb90n80 / #92): the published rankings that feature this tool, with

        its DERIVED rank and badge — the "Featured in rankings" section the tool page lost in the

        Payload read-cutover (the old reverse query hit Payload; the frontend stub has returned [] since).


        Two correctness rules, both paid for before:

        - rank/badge come from `rendered_entries` (the decide_for_slug order a reader actually sees on

        the ranking page), never the stored copy — a stored rank here could disagree with the live

        ranking page (#337''s exact failure class).

        - the tool is matched by EXACT identity only: its page slug, or the sip evidence identity bound

        to its page through page_content.tool_id (86bb9m0tp; written at publish, backfilled for

        migrated pages). Never a slugified/lowercased name guess — that guessing is what silently

        dropped 4 of 10 tools from Similar Tools (#336).

        Unauthenticated + published-only on both sides (mirrors get_tool_scorecard).'
      operationId: get_tool_rankings_v1_tools__slug__rankings_get
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Tool Rankings V1 Tools  Slug  Rankings Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/tools/{slug}/scorecard:
    get:
      tags:
      - site-read
      summary: Get Tool Scorecard
      description: 'PUBLIC per-criterion / per-scenario / overall scorecard for a tool''s most recent run — the /5

        bars the new ranking page (S6) renders. Unauthenticated + published-tool-gated (mirrors the

        get_evidence publish line; the frontend carries no service token). The token-guarded

        `/v1/tools/{slug}` stays for the internal/admin read. 404 if the tool has no published page/run.'
      operationId: get_tool_scorecard_v1_tools__slug__scorecard_get
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Tool Scorecard V1 Tools  Slug  Scorecard Get
        '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