AIXBT Meta API

openapi: 3.2.0
info:
  title: AIXBT API v3 Meta 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: Meta
  description: The contract itself.
paths:
  /v3/openapi.yaml:
    get:
      operationId: getOpenApiDocument
      tags:
      - Meta
      summary: Get this contract
      description: The canonical v3 OpenAPI document, served verbatim. No credential required.
      security: []
      responses:
        '200':
          description: This document.
          content:
            application/yaml:
              schema:
                type: string
        '500':
          $ref: '#/components/responses/Internal'
components:
  responses:
    Internal:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            internal:
              value:
                code: internal_error
                message: Unexpected error.
  schemas:
    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).
  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`.

        '