AIXBT Reports API

openapi: 3.2.0
info:
  title: AIXBT API v3 Reports API
  version: 3.0.0-draft.1
  summary: Crypto intelligence API for Projects, Topics, Intel, Reports, and Clusters.
  description: 'The AIXBT API v3 contract. The implementation conforms to this document,

    the reference docs generate from it, and automated tests keep the served

    API and this document in sync. Interactive docs are served at `/v3/docs`;

    this document is served verbatim at `/v3/openapi.yaml`.


    ## Conventions


    - **Envelope**: every JSON success body is `{data, meta}`. There is no

    body-level `status` integer; the HTTP status code is the status.

    - **Errors**: every 4xx/5xx body is a single typed `Error` with a stable

    machine `code`. `401` means the credential is missing or invalid; `403`

    means the credential lacks an entitlement or crossed the history

    boundary.

    - **Pagination**: collections use opaque cursors: request `cursor` +

    `limit`, read `meta.nextCursor` (`null` on the last page). There are no

    page numbers and no total counts.

    - **Measurements**: v3 publishes AIXBT-owned measurements: `trend` for

    continued attention, `rank`, and attention counts,

    together with canonical identity. It does not redistribute third-party market

    data: no prices, market caps, volumes, or candles anywhere in this

    contract. Composition happens through `identifiers`: stable external

    join keys (CoinGecko id, X handle; additively extensible per universe)

    that let a consumer fetch market data under their own license. The one

    bounded exception is the publication-time evidence block inside an

    entitled Report, which quotes attributed observations as part of the

    research artifact. Intel lists accept a coarse `marketCap` band as a

    filter; the band selects results and is never returned as data.

    - **Access tiers**: Current Topic list, detail, and association routes are

    free and served under unauthenticated IP rate limits. Topic measurement

    history and everything else require an API key, and Report detail

    additionally requires the `topic-reports` entitlement. Alert management

    is owner-scoped to the calling credential; destination provisioning (chat

    connections) stays in product Settings and the API references

    destinations by id.

    - **Naming**: `trend` is the public attention measurement; `rank` is its

    position within the relevant Project or Topic cohort.

    Enumerated values are lowercase. Timestamps are ISO 8601 UTC and semantic

    (`detectedAt`, `reinforcedAt`, `observedAt`, never processing time).

    Intel activity keeps claimed `eventTime` separate from detection time;

    legacy `occurredAt` remains a deprecated provider-publication/detection

    fallback; it is never claimed event time.

    - **Locators**: Project path params accept the canonical id or the

    immutable public slug; responses always carry both. Merged or re-slugged

    Projects keep old locators resolving to the canonical resource.

    - **Universe**: every Project and Cluster belongs to the `crypto`

    universe.

    - **Assets**: a Project''s instrument identity is a typed `assets` array

    (`token`, `stablecoin`, `nft-collection` today). New asset types are

    added additively; the array shape never changes.

    - **History**: measurement series endpoints serve recorded history

    through their `from`/`to` windows, subject to the credential''s history

    window (`meta.history`).

    - **Subject misses**: a 404 body distinguishes `not_found` (never

    existed / bad locator) and `not_current` (exists, no longer current).

    - **Stability**: while `x-status` is `draft`, routes, fields, and values may

    change before stabilization. After stabilization, retiring routes first

    serve RFC 9745 `Deprecation` and RFC 8288

    `Link: rel="successor-version"` headers and are marked `deprecated: true`

    here with an `x-successor` pointer.

    - **Caching**: every response is `Cache-Control: private, no-store`.

    Rate limits are surfaced via `X-RateLimit-*` headers; breaches return

    `429` with `Retry-After`.'
  x-status: draft
servers:
- url: https://api.aixbt.tech
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: Reports
  description: Read-only published research artifacts.
paths:
  /v3/reports:
    get:
      operationId: listReports
      tags:
      - Reports
      summary: List published Reports
      description: 'Top-level read-only collection of published research artifacts, newest

        first, with relationship filters. List items are bounded previews;

        the full body requires the `topic-reports` entitlement on the detail

        route.'
      x-collection: true
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      - name: projectId
        in: query
        description: Current canonical Project id. Matches Reports whose frozen publication-time binding used this id or one of its absorbed id aliases.
        schema:
          type: string
      - name: projectSlug
        in: query
        description: Current canonical Project slug or slug alias. Matches the same frozen publication-time bindings as projectId.
        schema:
          type: string
      - name: topicId
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Report page.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ReportListItem'
                  meta:
                    $ref: '#/components/schemas/CollectionMeta'
              examples:
                success:
                  summary: Latest reports
                  value:
                    data:
                    - id: tr_9f2b6c41d8a35e07b1c4f6a2d5e8091c3b7a4f60d2e5c8b1a4f7092c5d8e3b6a
                      title: Restaking Yield Compression
                      publishedAt: '2026-08-04T18:00:00Z'
                      revisedAt: null
                      primarySubject:
                        type: topic
                        topic:
                          id: topic_a1b2c3d4e5f601234567
                          name: Restaking yield compression
                      relatedSubjects:
                      - type: project
                        project:
                          id: 665f0a2b1c9d440000a1b2c3
                          slug: examplechain
                          name: ExampleChain
                      preview: Yields across restaking protocols compress as new AVS demand stalls...
                    meta:
                      nextCursor: null
                empty:
                  summary: No reports for the filter
                  value:
                    data: []
                    meta:
                      nextCursor: null
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/Internal'
  /v3/reports/{id}:
    get:
      operationId: getReport
      tags:
      - Reports
      summary: Get a published Report
      description: 'Full report artifact: body, typed sources, and the publication-time

        evidence block. Requires the `topic-reports` entitlement. The

        evidence block quotes market figures with source attribution as

        part of the published research.'
      x-required-entitlements:
      - topic-reports
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Report detail.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    $ref: '#/components/schemas/Report'
                  meta:
                    $ref: '#/components/schemas/Meta'
              examples:
                success:
                  summary: Full report
                  value:
                    data:
                      id: tr_9f2b6c41d8a35e07b1c4f6a2d5e8091c3b7a4f60d2e5c8b1a4f7092c5d8e3b6a
                      title: Restaking Yield Compression
                      publishedAt: '2026-08-04T18:00:00Z'
                      revisedAt: null
                      primarySubject:
                        type: topic
                        topic:
                          id: topic_a1b2c3d4e5f601234567
                          name: Restaking yield compression
                      relatedSubjects:
                      - type: project
                        project:
                          id: 665f0a2b1c9d440000a1b2c3
                          slug: examplechain
                          name: ExampleChain
                      summary: Yields across restaking protocols compress as new AVS demand stalls.
                      body: '## Thesis


                        Yields compress because...'
                      sources:
                      - title: AVS demand dashboard
                        url: https://dune.com/example/avs
                        publishedAt: '2026-08-03T00:00:00Z'
                      evidence:
                        snapshotAt: '2026-08-04T18:00:00Z'
                        entities:
                        - project:
                            id: 665f0a2b1c9d440000a1b2c3
                            slug: examplechain
                            name: ExampleChain
                          observations:
                          - key: avs_count
                            value: 41
                            unit: count
                            provider: aixbt
                            observedAt: '2026-08-04T17:58:00Z'
                            freshness: fresh
                    meta: {}
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/SubjectMiss'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/Internal'
components:
  schemas:
    TopicRef:
      type: object
      required:
      - id
      - name
      properties:
        id:
          type: string
        name:
          type: string
    Meta:
      type: object
      description: Response metadata. Empty when nothing applies.
      properties:
        history:
          $ref: '#/components/schemas/HistoryMeta'
        versions:
          type: object
          additionalProperties:
            type: string
          description: Named component versions that shaped this response.
    ProjectRef:
      type: object
      required:
      - id
      - slug
      - name
      properties:
        id:
          type: string
        slug:
          type: string
          pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
          maxLength: 64
        name:
          type: string
    ReportSubject:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - project
          - topic
        project:
          $ref: '#/components/schemas/ProjectRef'
        topic:
          $ref: '#/components/schemas/TopicRef'
    Report:
      allOf:
      - $ref: '#/components/schemas/ReportListItem'
      - type: object
        required:
        - summary
        - body
        - sources
        properties:
          summary:
            type: string
          body:
            type: string
            description: Markdown body of the published artifact without internal source-id markers.
          sources:
            type: array
            items:
              type: object
              required:
              - title
              - url
              properties:
                title:
                  type: string
                url:
                  type: string
                  format: uri
                publishedAt:
                  type: string
                  format: date-time
          evidence:
            type: object
            description: 'Publication-time evidence quoted by the artifact, with source

              attribution and observation timestamps. Immutable once

              published.

              '
            properties:
              snapshotAt:
                type: string
                format: date-time
              entities:
                type: array
                items:
                  type: object
                  required:
                  - project
                  - observations
                  properties:
                    project:
                      $ref: '#/components/schemas/ProjectRef'
                    observations:
                      type: array
                      items:
                        type: object
                        required:
                        - key
                        - value
                        - unit
                        - provider
                        - observedAt
                        - freshness
                        properties:
                          key:
                            type: string
                          value:
                            type: number
                          unit:
                            type: string
                          provider:
                            type: string
                          observedAt:
                            description: 'Source-side observation timestamp. Null when

                              the provider publishes the figure without

                              one.

                              '
                            oneOf:
                            - type: string
                              format: date-time
                            - type: 'null'
                          freshness:
                            type: string
                          disagreement:
                            type: number
    HistoryMeta:
      type: object
      description: The history window applied to this response. Both fields are null when the account has no history limit.
      required:
      - lookbackDays
      - earliestAvailableAt
      properties:
        lookbackDays:
          oneOf:
          - type: integer
          - type: 'null'
        earliestAvailableAt:
          oneOf:
          - type: string
            format: date-time
          - type: 'null'
    Error:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          enum:
          - invalid_request
          - credential_required
          - invalid_credential
          - entitlement_required
          - history_window_exceeded
          - not_found
          - not_current
          - rate_limited
          - internal_error
          - service_unavailable
        message:
          type: string
        details:
          type: object
          additionalProperties: true
          description: Optional structured context (field errors, subject locators, limits).
    ReportListItem:
      type: object
      required:
      - id
      - title
      - publishedAt
      - primarySubject
      - preview
      properties:
        id:
          type: string
        title:
          type: string
        publishedAt:
          type: string
          format: date-time
        revisedAt:
          oneOf:
          - type: string
            format: date-time
          - type: 'null'
        primarySubject:
          $ref: '#/components/schemas/ReportSubject'
        relatedSubjects:
          type: array
          items:
            $ref: '#/components/schemas/ReportSubject'
          description: Ordered, deduplicated Project bindings frozen from the Report's evidence membership and resolved to current Project identity; never inferred from prose, live Topic associations, or market evidence.
        preview:
          type: string
    CollectionMeta:
      allOf:
      - $ref: '#/components/schemas/Meta'
      - type: object
        required:
        - nextCursor
        properties:
          nextCursor:
            oneOf:
            - type: string
            - type: 'null'
            description: Cursor for the next page; `null` on the last page.
  responses:
    RateLimited:
      description: Rate limit exceeded; retry after the indicated delay.
      headers:
        Retry-After:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            rateLimited:
              value:
                code: rate_limited
                message: Minute limit reached.
                details:
                  limit: 100
                  window: minute
    SubjectMiss:
      description: The subject was not found or is not current.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            notFound:
              value:
                code: not_found
                message: No Project matches that locator.
                details:
                  subject:
                    type: project
                    locator: examplechain
            notCurrent:
              value:
                code: not_current
                message: The Topic exists but is no longer current.
                details:
                  subject:
                    type: topic
                    locator: topic_a1b2c3d4e5f601234567
    Forbidden:
      description: The credential lacks an entitlement or crossed the history boundary.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            entitlementRequired:
              value:
                code: entitlement_required
                message: This resource requires the topic-reports entitlement.
                details:
                  entitlement: topic-reports
            historyWindow:
              value:
                code: history_window_exceeded
                message: Requested instant is outside the 90-day history window.
                details:
                  earliestAvailableAt: '2026-05-07T00:00:00Z'
    Internal:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            internal:
              value:
                code: internal_error
                message: Unexpected error.
    BadRequest:
      description: The request is invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            invalidRequest:
              value:
                code: invalid_request
                message: minTrend must be numeric
                details:
                  fields:
                  - minTrend
    Unauthorized:
      description: The credential is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            credentialRequired:
              value:
                code: credential_required
                message: Provide an API key via the x-api-key header.
            invalidCredential:
              value:
                code: invalid_credential
                message: The API key is expired or unknown.
  parameters:
    Limit:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 50
        default: 50
    Cursor:
      name: cursor
      in: query
      description: Opaque cursor from `meta.nextCursor`.
      schema:
        type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: 'API key. The `Authorization` header is accepted as an equivalent

        carrier. Responses echo the credential class in `X-API-Key-Type`.

        '