AIXBT Alerts API

openapi: 3.2.0
info:
  title: AIXBT API v3 Alerts 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: Alerts
  description: Owner-scoped alert subscriptions over the shipped alert system.
paths:
  /v3/alerts:
    get:
      operationId: listAlerts
      tags:
      - Alerts
      summary: List my alert subscriptions
      description: 'Alert subscriptions owned by the calling credential. One owner may

        hold at most 50 subscriptions, paused rows included. Lists the

        API-manageable kinds (`intelligence.material`, `rank.entered`);

        preset subscriptions managed in product Settings do not appear

        here.'
      x-collection: true
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Alert page.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Alert'
                  meta:
                    $ref: '#/components/schemas/CollectionMeta'
              examples:
                success:
                  summary: Owner subscriptions
                  value:
                    data:
                    - id: 66a10a2b1c9d440000d1e2f3
                      status: active
                      trigger: intelligence.material
                      selector:
                        followedProjects: true
                        qualifiers:
                          grades:
                          - polished
                          - flawless
                          categories:
                          - product-launch
                      cadence: hourly
                      destinationIds:
                      - 66a10a2b1c9d440000aa0001
                      createdAt: '2026-08-01T10:00:00Z'
                      updatedAt: '2026-08-05T04:00:00Z'
                    meta:
                      nextCursor: null
                empty:
                  summary: No subscriptions yet
                  value:
                    data: []
                    meta:
                      nextCursor: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/Internal'
    post:
      operationId: createAlert
      tags:
      - Alerts
      summary: Create an alert subscription
      description: 'Creates an owner-scoped subscription: selector + one trigger +

        delivery cadence + explicit destination ids. Destinations are

        provisioned in product Settings and referenced here by id. Chat

        cadence defaults to `hourly`; `instant` is subject to a per-day

        platform safety ceiling. The 50-subscription owner cap and

        selector list bounds (20 values per list) are enforced. An account

        holds at most one `rank.entered` subscription; creating a second

        while one exists fails with `invalid_request`.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AlertCreate'
            examples:
              materialIntel:
                summary: Material intel on followed Projects
                value:
                  trigger: intelligence.material
                  selector:
                    followedProjects: true
                    qualifiers:
                      grades:
                      - polished
                      - flawless
                  cadence: hourly
                  destinationIds:
                  - 66a10a2b1c9d440000aa0001
              rankEntry:
                summary: Rank entry into the top 10
                value:
                  trigger: rank.entered
                  rankThreshold: 10
                  selector:
                    qualifiers:
                      categories:
                      - modular-blockchains
                  cadence: instant
                  destinationIds:
                  - 66a10a2b1c9d440000aa0002
      responses:
        '201':
          description: Created subscription.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    $ref: '#/components/schemas/Alert'
                  meta:
                    $ref: '#/components/schemas/Meta'
              examples:
                success:
                  summary: Created
                  value:
                    data:
                      id: 66a10a2b1c9d440000d1e2f4
                      status: active
                      trigger: rank.entered
                      rankThreshold: 10
                      selector:
                        qualifiers:
                          categories:
                          - modular-blockchains
                      cadence: instant
                      destinationIds:
                      - 66a10a2b1c9d440000aa0002
                      createdAt: '2026-08-05T05:00:00Z'
                      updatedAt: '2026-08-05T05:00:00Z'
                    meta: {}
        '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/alerts/{id}:
    get:
      operationId: getAlert
      tags:
      - Alerts
      summary: Get an alert subscription
      description: Owner-scoped read; another owner's id behaves as `not_found`.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Subscription.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    $ref: '#/components/schemas/Alert'
                  meta:
                    $ref: '#/components/schemas/Meta'
              examples:
                success:
                  summary: One subscription
                  value:
                    data:
                      id: 66a10a2b1c9d440000d1e2f3
                      status: active
                      trigger: intelligence.material
                      selector:
                        followedProjects: true
                      cadence: hourly
                      destinationIds:
                      - 66a10a2b1c9d440000aa0001
                      createdAt: '2026-08-01T10:00:00Z'
                      updatedAt: '2026-08-05T04:00:00Z'
                    meta: {}
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/SubjectMiss'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/Internal'
    patch:
      operationId: updateAlert
      tags:
      - Alerts
      summary: Update an alert subscription
      description: 'Partial update: pause/resume, rename, change cadence, selector,

        threshold, or destinations. Semantics are identical to creation.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AlertUpdate'
            examples:
              pause:
                summary: Pause delivery
                value:
                  status: paused
      responses:
        '200':
          description: Updated subscription.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    $ref: '#/components/schemas/Alert'
                  meta:
                    $ref: '#/components/schemas/Meta'
              examples:
                success:
                  summary: Paused
                  value:
                    data:
                      id: 66a10a2b1c9d440000d1e2f3
                      status: paused
                      trigger: intelligence.material
                      selector:
                        followedProjects: true
                      cadence: hourly
                      destinationIds:
                      - 66a10a2b1c9d440000aa0001
                      createdAt: '2026-08-01T10:00:00Z'
                      updatedAt: '2026-08-05T05:10:00Z'
                    meta: {}
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/SubjectMiss'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/Internal'
    delete:
      operationId: deleteAlert
      tags:
      - Alerts
      summary: Delete an alert subscription
      description: Removes the subscription; delivery history retention is unaffected.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/SubjectMiss'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/Internal'
  /v3/alerts/destinations:
    get:
      operationId: listAlertDestinations
      tags:
      - Alerts
      summary: List my delivery destinations
      description: 'Read-only list of destinations connected in product Settings

        (Telegram and Discord). Connections and repair stay in Settings;

        subscriptions reference these ids.'
      responses:
        '200':
          description: Destinations.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AlertDestination'
                  meta:
                    $ref: '#/components/schemas/Meta'
              examples:
                success:
                  summary: Connected destinations
                  value:
                    data:
                    - id: 66a10a2b1c9d440000aa0001
                      kind: telegram
                      label: Team channel
                      status: active
                    - id: 66a10a2b1c9d440000aa0002
                      kind: discord
                      label: Research channel
                      status: active
                    meta: {}
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/Internal'
components:
  schemas:
    AlertQualifiers:
      type: object
      description: 'Filter qualifiers; each list holds at most 20 values.

        `grades`, `sentiments`, `clusterIds`, `maxRank`, and

        `hasOfficialSource` qualify `intelligence.material` subscriptions;

        `chains` qualifies `rank.entered`; `categories` and `assetTypes`

        qualify both.

        '
      properties:
        categories:
          type: array
          items:
            type: string
        grades:
          type: array
          items:
            $ref: '#/components/schemas/Grade'
        sentiments:
          type: array
          items:
            type: string
        assetTypes:
          type: array
          items:
            type: string
        clusterIds:
          type: array
          items:
            type: string
        chains:
          type: array
          items:
            type: string
        maxRank:
          type: integer
          minimum: 1
          maximum: 100
          description: Only intel on Projects at or above this rank in the Trend cohort.
        hasOfficialSource:
          type: boolean
    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).
    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.
    AlertTrigger:
      type: string
      enum:
      - intelligence.material
      - rank.entered
      description: The set of launch triggers.
    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.

        '
    AlertSelector:
      type: object
      additionalProperties: false
      description: 'What the subscription watches: the owner''s followed Projects, the

        currently ranked cohort, a normalized keyword, or a qualifier-only cohort.

        Explicit per-Project and per-Topic id lists are not yet supported

        and will join additively.

        '
      properties:
        followedProjects:
          type: boolean
          description: Only the owner's followed Projects. Mutually exclusive with the ranked Project scopes.
        trendingProjects:
          type: boolean
          description: Only Projects in the current Trend ranking. Mutually exclusive with `followedProjects`.
        keyword:
          type: string
          minLength: 2
          maxLength: 64
          description: Normalized once at save time; matched case-insensitively against source-derived text.
        qualifiers:
          $ref: '#/components/schemas/AlertQualifiers'
    AlertUpdate:
      type: object
      description: Partial update; omitted fields are unchanged.
      properties:
        status:
          type: string
          enum:
          - active
          - paused
        rankThreshold:
          type: integer
          minimum: 1
          maximum: 100
        ranking:
          type: string
          enum:
          - trend
        selector:
          $ref: '#/components/schemas/AlertSelector'
        cadence:
          $ref: '#/components/schemas/AlertCadence'
        destinationIds:
          type: array
          items:
            type: string
          minItems: 1
    AlertDestination:
      type: object
      required:
      - id
      - kind
      - label
      - status
      properties:
        id:
          type: string
        kind:
          type: string
          enum:
          - telegram
          - discord
        label:
          type: string
        status:
          type: string
          enum:
          - pending
          - active
          - failing
          - disabled
    AlertCreate:
      type: object
      required:
      - trigger
      - selector
      - destinationIds
      properties:
        trigger:
          $ref: '#/components/schemas/AlertTrigger'
        rankThreshold:
          type: integer
          minimum: 1
          maximum: 100
          description: Required when `trigger` is `rank.entered`.
        ranking:
          type: string
          enum:
          - trend
          default: trend
          description: Ranking watched by `rank.entered`.
        selector:
          $ref: '#/components/schemas/AlertSelector'
        cadence:
          allOf:
          - $ref: '#/components/schemas/AlertCadence'
          default: hourly
        destinationIds:
          type: array
          items:
            type: string
          minItems: 1
    Alert:
      type: object
      required:
      - id
      - status
      - trigger
      - selector
      - cadence
      - destinationIds
      - createdAt
      - updatedAt
      properties:
        id:
          type: string
        status:
          type: string
          enum:
          - active
          - paused
        trigger:
          $ref: '#/components/schemas/AlertTrigger'
        rankThreshold:
          type: integer
          minimum: 1
          maximum: 100
          description: Top-N boundary; present only with `rank.entered`.
        ranking:
          type: string
          enum:
          - trend
          default: trend
          description: Ranking watched by `rank.entered`; omitted stored rows mean Trend.
        selector:
          $ref: '#/components/schemas/AlertSelector'
        cadence:
          $ref: '#/components/schemas/AlertCadence'
        destinationIds:
          type: array
          items:
            type: string
          minItems: 1
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
  responses:
    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.
    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'
    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
    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
    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
  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`.

        '