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

# Health Check

> Authenticated health check endpoint

Authenticated health check endpoint that returns status, environment, timestamp, and API version.

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer token authentication.
</ParamField>

<ParamField header="X-API-Version" type="string">
  API version to use. Defaults to `2024-09-01` if not specified.
</ParamField>

## Response

<ResponseField name="status" type="string">
  Always `ok` for successful health checks.
</ResponseField>

<ResponseField name="env" type="string">
  Environment indicator: `test` for testmode keys, `prod` for production keys.
</ResponseField>

<ResponseField name="timestamp" type="string">
  Current ISO 8601 timestamp.
</ResponseField>

<ResponseField name="api_version" type="string">
  The API version being used.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl https://api.numeralhq.com/tax/ping \
    -H "Authorization: Bearer sk_test_xxx" \
    -H "X-API-Version: 2026-03-01"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "status": "ok",
    "env": "test",
    "timestamp": "2026-03-01T12:00:00.000Z",
    "api_version": "2026-03-01"
  }
  ```
</ResponseExample>


## OpenAPI

````yaml GET /tax/ping
openapi: 3.0.1
info:
  title: Numeral API
  description: API for sales tax calculations
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.numeralhq.com/
security:
  - bearerAuth: []
paths:
  /tax/ping:
    get:
      summary: Health Check Ping
      description: >-
        Authenticated health check endpoint that returns status, environment,
        timestamp, and API version
      operationId: pingHealthCheck
      parameters:
        - name: X-API-Version
          in: header
          required: false
          schema:
            type: string
            enum:
              - '2025-05-12'
              - '2024-09-01'
            default: '2024-09-01'
          description: API version to use. Defaults to 2024-09-01 if not specified.
          example: '2025-05-12'
      responses:
        '200':
          description: Successful health check response
          headers:
            X-Request-ID:
              description: Unique request identifier
              schema:
                type: string
                example: req_123456789
            Cache-Control:
              description: Cache control directives
              schema:
                type: string
                example: no-cache, no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PingResponse'
              examples:
                testmode:
                  summary: Test environment response
                  description: Response when using a testmode API key
                  value:
                    status: ok
                    env: test
                    timestamp: '2025-09-12T17:30:00.000Z'
                    api_version: '2025-05-12'
                production:
                  summary: Production environment response
                  description: Response when using a production API key
                  value:
                    status: ok
                    env: prod
                    timestamp: '2025-09-12T17:30:00.000Z'
                    api_version: '2024-09-01'
        '400':
          description: Bearer token not provided
          content:
            text/plain:
              schema:
                type: string
                example: Bearer token not provided.
        '401':
          description: Authentication errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthError'
              examples:
                invalid_format:
                  summary: Invalid API key format
                  value:
                    error: Invalid API Key format.
                not_found:
                  summary: API key not found
                  value:
                    error: API key not found.
                not_active:
                  summary: API key not active
                  value:
                    error: API key is not active.
                public_key_not_supported:
                  summary: Public key not supported
                  value:
                    error: No public API key support currently.
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
      security:
        - bearerAuth: []
components:
  schemas:
    PingResponse:
      type: object
      description: >-
        Health check response containing status, environment, timestamp, and API
        version information
      properties:
        status:
          type: string
          description: Always returns 'ok' for successful health checks
          enum:
            - ok
          example: ok
        env:
          type: string
          description: >-
            Environment indicator based on API key type: 'test' for testmode
            keys, 'prod' for production keys
          enum:
            - test
            - prod
          example: test
        timestamp:
          type: string
          format: date-time
          description: Current ISO 8601 timestamp when the request was processed
          example: '2025-09-12T17:30:00.000Z'
        api_version:
          type: string
          description: API version from X-API-Version header, or falls back to 2024-09-01
          enum:
            - '2024-09-01'
            - '2025-05-12'
          example: '2025-05-12'
      required:
        - status
        - env
        - timestamp
        - api_version
    AuthError:
      type: object
      description: Authentication error response
      properties:
        error:
          type: string
          description: Authentication error message
          enum:
            - Invalid API Key format.
            - API key not found.
            - API key is not active.
            - No public API key support currently.
          example: API key not found.
      required:
        - error
    RateLimitError:
      type: object
      description: Rate limit exceeded error response
      properties:
        error:
          type: string
          description: Rate limit error message
          enum:
            - Rate limit exceeded
          example: Rate limit exceeded
      required:
        - error
    InternalServerError:
      type: object
      description: Internal server error response
      properties:
        error_message:
          type: string
          description: Human-readable error description
          example: Internal server error
        error_code:
          type: string
          description: Machine-readable error code
          example: ERROR_ERROR
      required:
        - error_message
        - error_code
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````