AIHOT Selected API

openapi: 3.2.0
info:
  title: '{{siteName}} Public Selected API'
  version: '{{version}}'
  description: 'Anonymous, read-only API for clients and Agents. No API key is required.


    Picking an endpoint: answer a person''s question inside an AI agent -> read /api/v1/agent, which lists Markdown addresses made for agents. Show recent or today''s items -> /api/v1/items. Show what is trending right now -> /api/v1/hot-topics. Show the daily digest -> /api/v1/dailies/latest; the weekly and monthly reports -> /api/v1/weeklies/latest and /api/v1/monthlies/latest. Keep a complete local copy of the selected set -> /api/v1/selected/snapshot once, then /api/v1/selected/changes forever.


    How often to poll: use each response''s Cache-Control s-maxage as the minimum interval, and always send If-None-Match: an unchanged resource answers 304 with an empty body. On 429 or 503, honour Retry-After. There is no push channel (no SSE, webhooks or streaming): poll on an interval.


    Keep responses small: send Accept-Encoding: gzip or br (curl --compressed). To follow new items, page back only until you reach an id you already have instead of re-reading the whole 7-day window on every poll; to keep every selected item, read /api/v1/selected/snapshot once and then only /api/v1/selected/changes.


    Report dates, weeks and months identify fixed editions, but corrections and withdrawn citations can change their public content. Revalidate retained copies with If-None-Match after Cache-Control expires; do not treat a dated report as immutable.


    Titles and summaries are generated from third-party sources; the original is always linked in links.original.'
  termsOfService: '{{siteUrl}}/terms'
servers:
- url: '{{siteUrl}}'
tags:
- name: Selected
paths:
  /api/v1/selected/snapshot:
    get:
      operationId: selectedSnapshot
      summary: Fetch the current selected-item snapshot, one page at a time
      description: 'One-time bootstrap for clients that keep a complete local copy of the selected set. Not a browsing endpoint and not something to poll: page through it once with limit (default 500, max 1000) until hasMore is false, keep the cursor from the FIRST page, then stay current with /api/v1/selected/changes. The full set runs to several thousand items and only grows; fields=minimal keeps the bootstrap small. A widget that just shows today''s picks does not need this at all — use /api/v1/items.'
      parameters:
      - $ref: '#/components/parameters/ActorUserAgent'
      - $ref: '#/components/parameters/IfNoneMatch'
      - name: fields
        in: query
        schema:
          type: string
          enum:
          - default
          - minimal
          default: default
        description: '''minimal'' drops summary and the original-article link, cutting the payload roughly 4x. Prefer it when you only need to know which items are currently selected. On continuation pages the value is locked by the page cursor, so a mirror can never end up half default and half minimal.'
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 500
      - name: page
        in: query
        schema:
          type: string
        description: Opaque continuation cursor from the previous response's nextPage. Keep requesting pages while hasMore is true; only after the last page should you use cursor against /api/v1/selected/changes. The sync cursor is identical on every page and always refers to the watermark taken on the first page, so items changed mid-pagination are reconciled by the first changes call.
      responses:
        '200':
          description: OK
          headers:
            ETag:
              schema:
                type: string
            Cache-Control:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SelectedSnapshot'
        '304':
          description: Not Modified
          headers:
            ETag:
              schema:
                type: string
            Cache-Control:
              schema:
                type: string
        '400':
          description: Machine-readable problem response.
          headers:
            X-Request-Id:
              description: Support correlation identifier for this failed request.
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Machine-readable problem response.
          headers:
            X-Request-Id:
              description: Support correlation identifier for this failed request.
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '405':
          description: Machine-readable problem response.
          headers:
            X-Request-Id:
              description: Support correlation identifier for this failed request.
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '409':
          description: Machine-readable problem response.
          headers:
            X-Request-Id:
              description: Support correlation identifier for this failed request.
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Machine-readable problem response.
          headers:
            X-Request-Id:
              description: Support correlation identifier for this failed request.
              schema:
                type: string
            Retry-After:
              description: Minimum number of seconds to wait before retrying.
              schema:
                type: integer
                minimum: 1
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: Machine-readable problem response.
          headers:
            X-Request-Id:
              description: Support correlation identifier for this failed request.
              schema:
                type: string
            Retry-After:
              description: Minimum number of seconds to wait before retrying.
              schema:
                type: integer
                minimum: 1
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      tags:
      - Selected
  /api/v1/selected/changes:
    get:
      operationId: selectedChanges
      summary: Fetch atomic selected-item changes
      description: 'Adds, edits and removals since your cursor, so a local copy stays correct without re-downloading anything. Apply a page, then save the returned cursor — never the other way round. The cursor is a ledger watermark, not a session: it does not expire on a timer, so a client may go offline for days and resume exactly where it stopped. On 409 snapshot_required, re-bootstrap from /api/v1/selected/snapshot; that response is the only signal that resuming is no longer safe.'
      parameters:
      - $ref: '#/components/parameters/ActorUserAgent'
      - $ref: '#/components/parameters/IfNoneMatch'
      - name: cursor
        in: query
        required: true
        schema:
          type: string
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
      responses:
        '200':
          description: OK
          headers:
            ETag:
              schema:
                type: string
            Cache-Control:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SelectedChanges'
        '304':
          description: Not Modified
          headers:
            ETag:
              schema:
                type: string
            Cache-Control:
              schema:
                type: string
        '400':
          description: Machine-readable problem response.
          headers:
            X-Request-Id:
              description: Support correlation identifier for this failed request.
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Machine-readable problem response.
          headers:
            X-Request-Id:
              description: Support correlation identifier for this failed request.
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '405':
          description: Machine-readable problem response.
          headers:
            X-Request-Id:
              description: Support correlation identifier for this failed request.
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '409':
          description: Machine-readable problem response.
          headers:
            X-Request-Id:
              description: Support correlation identifier for this failed request.
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Machine-readable problem response.
          headers:
            X-Request-Id:
              description: Support correlation identifier for this failed request.
              schema:
                type: string
            Retry-After:
              description: Minimum number of seconds to wait before retrying.
              schema:
                type: integer
                minimum: 1
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: Machine-readable problem response.
          headers:
            X-Request-Id:
              description: Support correlation identifier for this failed request.
              schema:
                type: string
            Retry-After:
              description: Minimum number of seconds to wait before retrying.
              schema:
                type: integer
                minimum: 1
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      tags:
      - Selected
components:
  schemas:
    SelectedChanges:
      type: object
      required:
      - schemaVersion
      - fields
      - cursor
      - count
      - hasMore
      - changes
      properties:
        schemaVersion:
          const: 1
        fields:
          type: string
          enum:
          - default
          - minimal
        cursor:
          type: string
        count:
          type: integer
          minimum: 0
        hasMore:
          type: boolean
        changes:
          type: array
      oneOf:
      - properties:
          fields:
            const: default
          changes:
            type: array
            items:
              oneOf:
              - $ref: '#/components/schemas/SelectedUpsert'
              - $ref: '#/components/schemas/SelectedRemove'
      - properties:
          fields:
            const: minimal
          changes:
            type: array
            items:
              oneOf:
              - $ref: '#/components/schemas/SelectedUpsertMinimal'
              - $ref: '#/components/schemas/SelectedRemove'
    Problem:
      type: object
      required:
      - type
      - title
      - status
      - detail
      - code
      - requestId
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        code:
          type: string
        requestId:
          type: string
        retryAfter:
          type: integer
          minimum: 1
          description: Minimum number of seconds to wait before retrying (present on 429 and 503 responses).
    ItemMinimal:
      type: object
      required:
      - id
      - title
      - source
      - links
      - publishedAt
      - discoveredAt
      - category
      - score
      - selected
      properties:
        id:
          type: string
        title:
          type: string
        source:
          type: object
          required:
          - name
          properties:
            name:
              type: string
        links:
          type: object
          required:
          - aihot
          properties:
            aihot:
              type: string
              format: uri
        publishedAt:
          type:
          - string
          - 'null'
          format: date-time
        discoveredAt:
          type: string
          format: date-time
        category:
          type:
          - string
          - 'null'
          examples:
          - '{{categories}}'
          description: 'Current values: {{categoryList}}. Clients must tolerate future string values.'
        score:
          type:
          - number
          - 'null'
          minimum: 0
          maximum: 100
        selected:
          type: boolean
    SelectedUpsertMinimal:
      type: object
      required:
      - op
      - changedAt
      - item
      properties:
        op:
          const: upsert
        changedAt:
          type: string
          format: date-time
        item:
          $ref: '#/components/schemas/ItemMinimal'
    SelectedRemove:
      type: object
      required:
      - op
      - changedAt
      - id
      properties:
        op:
          const: remove
        changedAt:
          type: string
          format: date-time
        id:
          type: string
    Item:
      type: object
      required:
      - id
      - title
      - originalTitle
      - summary
      - source
      - links
      - publishedAt
      - discoveredAt
      - category
      - score
      - selected
      properties:
        id:
          type: string
        title:
          type: string
        originalTitle:
          type:
          - string
          - 'null'
        summary:
          type:
          - string
          - 'null'
        source:
          type: object
          required:
          - name
          properties:
            name:
              type: string
        links:
          type: object
          required:
          - aihot
          - original
          properties:
            aihot:
              type: string
              format: uri
            original:
              type: string
              format: uri
        publishedAt:
          type:
          - string
          - 'null'
          format: date-time
        discoveredAt:
          type: string
          format: date-time
        category:
          type:
          - string
          - 'null'
          examples:
          - '{{categories}}'
          description: 'Current values: {{categoryList}}. Clients must tolerate future string values.'
        score:
          type:
          - number
          - 'null'
          minimum: 0
          maximum: 100
        selected:
          type: boolean
        reason:
          type:
          - string
          - 'null'
          description: Reader-facing recommendation reason, the same text shown as 推荐理由 on the website. Always present on /api/v1/items; null when the item is not selected or has no reader-facing reason. Selected snapshot and changes do not include this field yet.
        attribution:
          $ref: '#/components/schemas/Attribution'
    SelectedUpsert:
      type: object
      required:
      - op
      - changedAt
      - item
      properties:
        op:
          const: upsert
        changedAt:
          type: string
          format: date-time
        item:
          $ref: '#/components/schemas/Item'
    SelectedSnapshot:
      type: object
      required:
      - schemaVersion
      - asOf
      - fields
      - cursor
      - count
      - hasMore
      - nextPage
      - items
      properties:
        schemaVersion:
          const: 1
        asOf:
          type: string
          format: date-time
        fields:
          type: string
          enum:
          - default
          - minimal
        cursor:
          type: string
        count:
          type: integer
          minimum: 0
        hasMore:
          type: boolean
        nextPage:
          type:
          - string
          - 'null'
        items:
          type: array
      oneOf:
      - properties:
          fields:
            const: default
          items:
            type: array
            items:
              $ref: '#/components/schemas/Item'
      - properties:
          fields:
            const: minimal
          items:
            type: array
            items:
              $ref: '#/components/schemas/ItemMinimal'
    Attribution:
      type: object
      description: Machine-readable {{siteName}} provenance for traceability. Retain it where technically feasible. Attribution alone is not authorization; see the public terms.
      required:
      - name
      - url
      properties:
        name:
          type: string
        url:
          type: string
          format: uri
  parameters:
    IfNoneMatch:
      name: If-None-Match
      in: header
      required: false
      description: Previously received ETag for this exact URL. A match returns 304 without a response body.
      schema:
        type: string
    ActorUserAgent:
      name: User-Agent
      in: header
      required: false
      description: The client's normal User-Agent (optional; any value works).
      schema:
        type: string
        maxLength: 2048
      example: my-reader/1.0
externalDocs:
  description: Machine-readable OpenAPI document
  url: '{{siteUrl}}/openapi-v1.json'