AIHOT Items API

openapi: 3.2.0
info:
  title: '{{siteName}} Public Items 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: Items
paths:
  /api/v1/items:
    get:
      operationId: items
      summary: List recent public AI items
      description: 'Start here for feeds, widgets and ''what is new'' views. Covers the last 7 days only. Send If-None-Match and you get a 304 with an empty body whenever nothing changed. To follow new items, page back with cursor only until you reach an id you already have. Do not use this to maintain a complete local copy of the selected set: it is windowed, so anything older than 7 days silently falls out. Use /api/v1/selected/snapshot plus /api/v1/selected/changes for that.'
      parameters:
      - $ref: '#/components/parameters/ActorUserAgent'
      - $ref: '#/components/parameters/IfNoneMatch'
      - name: mode
        in: query
        schema:
          type: string
          enum:
          - selected
          - all
          default: selected
      - name: category
        in: query
        schema:
          type: string
          examples:
          - '{{categories}}'
          description: 'Current values: {{categoryList}}.'
      - name: window
        in: query
        schema:
          type: string
          enum:
          - 24h
          - 7d
          default: 7d
      - name: by
        in: query
        schema:
          type: string
          enum:
          - timeline
          - published
          default: timeline
        description: 'Which timestamp defines the window and ordering. ''timeline'' (default) matches the site''s published timeline: historical or backfilled items can retain their source publication time, including items first found more than 72h after publication; ordinary new items use discovery time, and selected representatives follow their reading group''s first appearance. ''published'' uses source publication time, falling back to discovery time when it is unknown. publishedAt may be null when the original time is unknown; discoveredAt is the site''s receipt time. These returned fields are not client-side cursor or sort keys; pass the returned cursor unchanged.'
      - name: q
        in: query
        schema:
          type: string
          minLength: 2
          maxLength: 200
        description: Leading and trailing whitespace is removed before validation; the remaining value must contain 2 to 200 Unicode code points.
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
      - name: cursor
        in: query
        schema:
          type: string
        description: 'Opaque, query-bound keyset cursor for the rolling window. It carries no issue time and does not expire on a timer, but the window keeps moving: once the cursor''s own anchor has dropped out of the requested 24h or 7d window it is rejected with invalid_cursor, so restart the query from the first page instead of persisting a cursor across days. Older rows may also naturally leave the window between requests. Use selected snapshot + changes for an exact mirror.'
      responses:
        '200':
          description: OK
          headers:
            ETag:
              schema:
                type: string
            Cache-Control:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemsResponse'
        '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'
        '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:
      - Items
components:
  schemas:
    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).
    Page:
      type: object
      required:
      - count
      - hasMore
      - nextCursor
      properties:
        count:
          type: integer
          minimum: 0
          description: Number of records in this page.
        hasMore:
          type: boolean
        nextCursor:
          type:
          - string
          - 'null'
          description: Opaque; only reuse with the same query.
    ItemsResponse:
      type: object
      required:
      - schemaVersion
      - query
      - items
      - page
      properties:
        schemaVersion:
          const: 1
        query:
          type: object
          required:
          - mode
          - category
          - window
          - q
          - by
          - ordering
          properties:
            mode:
              type: string
              enum:
              - selected
              - all
            category:
              type:
              - string
              - 'null'
              examples:
              - '{{categories}}'
              description: 'Current values: {{categoryList}}. Clients must tolerate future string values.'
            window:
              type: string
              enum:
              - 24h
              - 7d
            q:
              type:
              - string
              - 'null'
              minLength: 2
              maxLength: 200
            by:
              type: string
              enum:
              - timeline
              - published
            ordering:
              type: string
              enum:
              - timelineDesc
              - publishedAtDesc
        items:
          type: array
          items:
            $ref: '#/components/schemas/Item'
        page:
          $ref: '#/components/schemas/Page'
    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'
    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'