AIXBT Rank API

openapi: 3.2.0
info:
  title: AIXBT Public Rank API
  version: 2.0.0
  description: 'Documentation for the AIXBT public API (v2).


    Most endpoints require an API key via the `x-api-key` header. Current topics, the deprecated `/grounding` topics alias, and cluster, category, and chain metadata are public. Historical topic data and all project, intel, signal, and recipe endpoints require authentication.


    Self-serve accounts can retrieve a rolling 90 days of proprietary AIXBT history, reported in `meta.history`. The boundary applies to explicit date ranges, historical `at` snapshots, pagination, and by-ID retrieval; older requests return `403 HISTORY_WINDOW_EXCEEDED` with the same `meta.history`. Accounts with the `archive-history` entitlement are uncapped. Current Topics and published Reports are excluded, while price candles and project market metrics retain their endpoint-specific windows.


    For full usage instructions, authentication and example projects, visit the documentation: docs.aixbt.tech.'
security:
- ApiKeyAuth: []
tags:
- name: Rank
paths:
  /v2/projects/{id}/rank:
    get:
      summary: Rank History
      tags:
      - Rank
      description: Returns rank position history with scores over a time window. Only includes timestamps where the project was in the ranked roster, which contains up to 100 projects. Default period is the last 7 days.
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
        description: The project ID
      - in: query
        name: start
        schema:
          type: string
          format: date-time
        description: Start timestamp (ISO 8601 format). Defaults to 7 days ago.
      - in: query
        name: end
        schema:
          type: string
          format: date-time
        description: End timestamp (ISO 8601 format). Defaults to now.
      - in: query
        name: at
        schema:
          type: string
          format: date-time
        description: 'Historical anchor timestamp (ISO 8601). Sets the end of the rank time window.

          Must be in the past.

          '
      responses:
        '200':
          description: Rank position history with scores
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 200
                  meta:
                    $ref: '#/components/schemas/HistoryResponseMeta'
                  data:
                    type: object
                    properties:
                      projectId:
                        type: string
                        example: 507f1f77bcf86cd799439011
                      projectName:
                        type: string
                        example: ethereum
                      data:
                        type: array
                        items:
                          type: object
                          properties:
                            timestamp:
                              type: string
                              format: date-time
                              example: 2026-03-30 12:00:00+00:00
                            rank:
                              type: integer
                              minimum: 1
                              maximum: 100
                              example: 3
                            trendScore:
                              type: number
                              description: Trend score at this timestamp
                              example: 85
        '400':
          description: Invalid project ID format or invalid date parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Authentication required, or requested history is outside the credential window.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Project not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Failed to fetch project rank
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '503':
          description: Rank data temporarily unavailable (TimescaleDB connectivity issue)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      operationId: getV2ProjectsByIdRank
components:
  schemas:
    ApiError:
      type: object
      required:
      - error
      description: Error response. Middleware may include additional rate-limit or access metadata.
      properties:
        error:
          type: string
        message:
          type: string
        code:
          type: string
        status:
          type: integer
        data: {}
        meta:
          type: object
          additionalProperties: true
        details:
          type: object
          additionalProperties: true
        pagination:
          $ref: '#/components/schemas/Pagination'
        limitType:
          type: string
          enum:
          - minute
          - day
          description: Rate-limit window that was exhausted.
        retryAfterMs:
          type: integer
          minimum: 0
          description: Milliseconds until the exhausted window resets.
        limits:
          type: object
          required:
          - minute
          - day
          properties:
            minute:
              $ref: '#/components/schemas/RateLimitWindow'
            day:
              $ref: '#/components/schemas/RateLimitWindow'
        issues:
          type: array
          items:
            type: object
            required:
            - path
            - message
            properties:
              path:
                type: string
              message:
                type: string
      additionalProperties: true
    RateLimitWindow:
      type: object
      required:
      - limit
      - remaining
      - resetAt
      properties:
        limit:
          type: integer
          minimum: 0
        remaining:
          type: integer
          minimum: 0
        resetAt:
          type: string
          format: date-time
    HistoryResponseMeta:
      type: object
      required:
      - history
      properties:
        history:
          $ref: '#/components/schemas/HistoryAccessMeta'
    HistoryAccessMeta:
      type: object
      required:
      - lookbackDays
      - earliestAvailableAt
      properties:
        lookbackDays:
          type:
          - integer
          - 'null'
          example: 90
        earliestAvailableAt:
          type:
          - string
          - 'null'
          format: date-time
    Pagination:
      type: object
      required:
      - page
      - limit
      - totalCount
      - hasMore
      properties:
        page:
          type: integer
          minimum: 1
        limit:
          type: integer
          minimum: 1
        totalCount:
          type: integer
          minimum: 0
        hasMore:
          type: boolean
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key to authorize requests