> ## 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 Ping

> Authenticated health check endpoint

## Health Check Endpoint (2025-05-12)

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

<Note>
  The `X-API-Version` header is optional for this endpoint. If provided, it will be reflected in the response's `api_version` field.
</Note>

## Use Cases

Use this endpoint to:

* Verify API connectivity and authentication
* Check which environment your API key is configured for (test vs. production)
* Confirm API version compatibility
* Monitor service availability in your application health checks

## Response Fields

* **status**: Always returns "ok" for successful requests
* **env**: "test" if using a testmode API key, "prod" for production keys
* **timestamp**: Current ISO 8601 timestamp when the request was processed
* **api\_version**: The API version from the X-API-Version header, or falls back to "2024-09-01"

## Authentication Required

This endpoint requires a SECRET API key. PUBLIC keys are not supported and will return a 401 error.

## Rate Limiting

This endpoint is subject to rate limiting per API key and IP address. If you exceed the rate limit, you'll receive a 429 error response.

## Response Headers

* **X-Request-ID**: Unique identifier for the request (useful for debugging)
* **Cache-Control**: Set to "no-cache, no-store" to prevent caching


## 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

````