AIXBT Vocabulary API

openapi: 3.2.0
info:
  title: AIXBT API v3 Vocabulary 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: Vocabulary
  description: Versioned value sets used by every filter.
paths:
  /v3/vocabulary:
    get:
      operationId: getVocabulary
      tags:
      - Vocabulary
      summary: Get the filter vocabularies
      description: 'One discovery surface for every value a v3 filter accepts. Closed

        vocabularies (grades, sentiments, stances, sort keys, activity modes,

        rankings, universes, asset types, series measures) are versioned with

        the contract; catalog-derived sets (project categories, intel

        categories, chains) are composed from their owning catalogs at read

        time and carry their own versions.'
      responses:
        '200':
          description: Vocabularies.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    $ref: '#/components/schemas/Vocabulary'
                  meta:
                    $ref: '#/components/schemas/Meta'
              examples:
                success:
                  summary: Current vocabularies
                  value:
                    data:
                      grades:
                      - chipped
                      - flawed
                      - cut
                      - polished
                      - flawless
                      sentiments:
                      - positive
                      - neutral
                      - negative
                      stances:
                      - supportive
                      - skeptical
                      - neutral
                      - mixed
                      - unknown
                      assetTypes:
                      - token
                      - stablecoin
                      - nft-collection
                      marketCapBands:
                      - low
                      - mid
                      - large
                      projectSort:
                      - rank
                      - trend
                      - createdAt
                      - reinforcedAt
                      intelSort:
                      - reinforcedAt
                      - detectedAt
                      activityModes:
                      - all
                      - observations
                      - none
                      projectRankings:
                      - trend
                      universes:
                      - crypto
                      seriesMeasures:
                      - trend
                      - rank
                      alertTriggers:
                      - intelligence.material
                      - rank.entered
                      alertCadences:
                      - instant
                      - hourly
                      - every_12h
                      - daily
                      projectCategories:
                      - slug: modular-blockchains
                        name: Modular blockchains
                      intelCategories:
                      - slug: product-launch
                        name: Product launch
                      chains:
                      - ethereum
                      - solana
                      - base
                    meta:
                      versions:
                        vocabulary: 3.0.0-draft.1
                        taxonomy: taxonomy-v2
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/Internal'
components:
  schemas:
    Grade:
      type: string
      enum:
      - chipped
      - flawed
      - cut
      - polished
      - flawless
      description: 'Evidence grade of an Intel item, lowest to highest. Grades describe

        the shape of the evidence, never the truth of the claim.

        '
    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.
    AlertCadence:
      type: string
      enum:
      - instant
      - hourly
      - every_12h
      - daily
      description: 'Chat delivery cadence. First event in a window delivers immediately;

        the window bundles the rest. `instant` is subject to a per-day

        platform safety ceiling.

        '
    Vocabulary:
      type: object
      required:
      - grades
      - sentiments
      - stances
      - assetTypes
      - marketCapBands
      - projectSort
      - intelSort
      - activityModes
      - projectRankings
      - universes
      - seriesMeasures
      - alertTriggers
      - alertCadences
      - projectCategories
      - intelCategories
      - chains
      properties:
        grades:
          type: array
          items:
            $ref: '#/components/schemas/Grade'
        sentiments:
          type: array
          items:
            type: string
        stances:
          type: array
          items:
            $ref: '#/components/schemas/Stance'
        assetTypes:
          type: array
          items:
            type: string
        marketCapBands:
          type: array
          items:
            type: string
        projectSort:
          type: array
          items:
            type: string
        intelSort:
          type: array
          items:
            type: string
        activityModes:
          type: array
          items:
            type: string
        projectRankings:
          type: array
          items:
            type: string
        universes:
          type: array
          items:
            type: string
        seriesMeasures:
          type: array
          items:
            type: string
        alertTriggers:
          type: array
          items:
            $ref: '#/components/schemas/AlertTrigger'
        alertCadences:
          type: array
          items:
            $ref: '#/components/schemas/AlertCadence'
        projectCategories:
          type: array
          items:
            type: object
            required:
            - slug
            - name
            properties:
              slug:
                type: string
              name:
                type: string
        intelCategories:
          type: array
          items:
            type: object
            required:
            - slug
            - name
            properties:
              slug:
                type: string
              name:
                type: string
        chains:
          type: array
          items:
            type: string
    Stance:
      type: string
      enum:
      - supportive
      - skeptical
      - neutral
      - mixed
      - unknown
    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).
    AlertTrigger:
      type: string
      enum:
      - intelligence.material
      - rank.entered
      description: The set of launch triggers.
  responses:
    Internal:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            internal:
              value:
                code: internal_error
                message: Unexpected error.
    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
    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.
  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`.

        '