> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beliefstate.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Check API access, credit balance, and usage metering



## OpenAPI

````yaml https://beliefstate.ai/openapi.json get /v1/status
openapi: 3.1.0
info:
  title: BeliefState Intelligence API
  version: '2026-10-05'
  description: >-
    Four read only research resources: Brief for ticker research, Beliefs for
    records and evidence, Sources for the research directory, and Tickers for
    coverage. REST research uses API keys; AI clients use OAuth through /mcp.
servers:
  - url: https://beliefstate.ai
security: []
tags:
  - name: Brief
  - name: Beliefs
  - name: Sources
  - name: Tickers
externalDocs:
  description: Connect an AI
  url: https://beliefstate.ai/agents
paths:
  /v1/status:
    get:
      tags:
        - Access
      summary: Check API access, credit balance, and usage metering
      operationId: getStatus
      parameters:
        - in: header
          name: X-Request-ID
          required: false
          description: >-
            Stable 1–128 character ID for an idempotent retry. Reuse the same
            value only for the same logical request.
          schema:
            type: string
            maxLength: 128
            pattern: ^[A-Za-z0-9._~:+/=-]+$
      responses:
        '200':
          description: Successful read only response
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                type: object
                properties:
                  accessMode:
                    type: string
                    enum:
                      - live
                      - local_live
                      - preview
                  balanceCents:
                    anyOf:
                      - type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                      - type: 'null'
                  catalogVersion:
                    type:
                      - string
                      - 'null'
                  currency:
                    anyOf:
                      - type: string
                        const: usd
                      - type: 'null'
                  dataMode:
                    type: string
                    enum:
                      - live
                      - preview
                  metering:
                    type: string
                    enum:
                      - active
                      - disabled
                  prepaidRequestsRemaining:
                    anyOf:
                      - type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                      - type: 'null'
                  status:
                    type: string
                    const: ready
                  subscriptionPlan:
                    type:
                      - string
                      - 'null'
                  subscriptionRequestsRemaining:
                    anyOf:
                      - type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                      - type: 'null'
                required:
                  - accessMode
                  - balanceCents
                  - catalogVersion
                  - currency
                  - dataMode
                  - metering
                  - prepaidRequestsRemaining
                  - status
                  - subscriptionPlan
                  - subscriptionRequestsRemaining
                additionalProperties: false
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      recovery:
                        type:
                          - string
                          - 'null'
                      retryable:
                        type: boolean
                    required:
                      - code
                      - message
                      - recovery
                      - retryable
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      recovery:
                        type:
                          - string
                          - 'null'
                      retryable:
                        type: boolean
                    required:
                      - code
                      - message
                      - recovery
                      - retryable
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '402':
          description: Paid access required
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      recovery:
                        type:
                          - string
                          - 'null'
                      retryable:
                        type: boolean
                    required:
                      - code
                      - message
                      - recovery
                      - retryable
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '404':
          description: Security unavailable
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      recovery:
                        type:
                          - string
                          - 'null'
                      retryable:
                        type: boolean
                    required:
                      - code
                      - message
                      - recovery
                      - retryable
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '409':
          description: Duplicate request ID
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      recovery:
                        type:
                          - string
                          - 'null'
                      retryable:
                        type: boolean
                    required:
                      - code
                      - message
                      - recovery
                      - retryable
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '503':
          description: Stored intelligence temporarily unavailable
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      recovery:
                        type:
                          - string
                          - 'null'
                      retryable:
                        type: boolean
                    required:
                      - code
                      - message
                      - recovery
                      - retryable
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
      security:
        - ApiKeyBearer: []
components:
  securitySchemes:
    ApiKeyBearer:
      type: http
      scheme: bearer
      bearerFormat: BeliefState API key
      description: >-
        Developer API key created through /auth.md. Never paste it into a retail
        chat.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.