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

# API Health Check

> Simple health check endpoint to verify API availability and authentication status. Use this endpoint 
for monitoring and to validate API tokens.

## Use Cases
- Monitoring API health
- Validating API tokens
- Testing CORS configuration
- Checking rate limits

## Response Times
- Expected: < 100ms
- Warning: > 500ms
- Critical: > 1000ms

## Monitoring Guidelines
- Poll every 60 seconds
- Implement circuit breaker pattern
- Track response times
- Monitor error rates

## Example Response
```json
{
  "message": "🎤 We're humming along!",
  "timestamp": "2026-07-13T16:26:17.874Z"
}
```




## OpenAPI

````yaml /swagger.yaml get /ping
openapi: 3.0.1
info:
  title: Hum API
  version: 1.6.0
  description: >
    The Hum API provides a comprehensive solution for discovering and comparing
    Internet service providers (ISPs) at specific addresses. 

    By leveraging AI-powered agents, the API normalizes addresses, identifies
    available providers, and returns detailed information 

    about service plans, pricing, and technology options. This makes it an ideal
    solution for businesses and applications that need 

    to help users find and compare Internet service options in their area.


    The API provides endpoints for creating and managing sessions, as well as
    verifying the connection to the API. Each session represents a service
    address lookup and its provider results.


    ## API Versioning

    This API uses semantic versioning. The current version is v1.6.0. For
    breaking changes, the major version will be incremented.


    ## Rate Limiting

    API requests are protected by a global limit of 100 requests per second per
    client IP. Analytics endpoints have an additional limit of 60 requests per
    minute per client IP. When a limit is exceeded, the API returns HTTP 429
    with a `Retry-After: 60` header. No other rate-limit headers are sent.


    ## Authentication

    All endpoints require Bearer token authentication. Tokens must be included
    in the Authorization header.
  termsOfService: https://www.letshum.com/terms-of-service
  contact:
    name: Hum API Support
    url: https://docs.letshum.com
    email: support@letshum.com
  license:
    name: Proprietary
    url: https://www.letshum.com/terms-of-service
servers:
  - url: https://api-sandbox.letshum.com
    description: Sandbox environment
  - url: https://api.letshum.com
    description: Production environment
security: []
paths:
  /ping:
    get:
      tags:
        - Health Check
      summary: API Health Check
      description: >
        Simple health check endpoint to verify API availability and
        authentication status. Use this endpoint 

        for monitoring and to validate API tokens.


        ## Use Cases

        - Monitoring API health

        - Validating API tokens

        - Testing CORS configuration

        - Checking rate limits


        ## Response Times

        - Expected: < 100ms

        - Warning: > 500ms

        - Critical: > 1000ms


        ## Monitoring Guidelines

        - Poll every 60 seconds

        - Implement circuit breaker pattern

        - Track response times

        - Monitor error rates


        ## Example Response

        ```json

        {
          "message": "🎤 We're humming along!",
          "timestamp": "2026-07-13T16:26:17.874Z"
        }

        ```
      operationId: healthCheck
      responses:
        '200':
          description: API is available, and token is valid
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: 🎤 We're humming along!
                    description: A message confirming the API is available.
                  timestamp:
                    $ref: '#/components/schemas/timestamp'
                required:
                  - message
                  - timestamp
        '401':
          $ref: '#/components/responses/401_unauthorized'
        '415':
          $ref: '#/components/responses/415_unsupported_media_type'
        '429':
          $ref: '#/components/responses/429_rate_limit'
      security:
        - bearerAuth: []
components:
  schemas:
    timestamp:
      type: string
      format: date-time
      example: '2024-09-20T23:13:31.179Z'
      description: A timestamp in ISO 8601 format.
  responses:
    401_unauthorized:
      description: >-
        Unauthorized. Use the HTTP status code, not `request_status`, to detect
        the error.
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Unauthorized access
              request_status:
                type: string
                enum:
                  - warning
                example: warning
            required:
              - message
              - request_status
    415_unsupported_media_type:
      description: The request was rejected because its content type is unsupported.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: Request rejected
              message:
                type: string
                example: The request was rejected due to security concerns
              status:
                type: integer
                enum:
                  - 415
                example: 415
            required:
              - error
              - message
              - status
    429_rate_limit:
      description: Rate Limit Exceeded
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: Too many requests
              message:
                type: string
                example: Rate limit exceeded. Please try again later.
              status:
                type: integer
                enum:
                  - 429
                example: 429
            required:
              - error
              - message
              - status
  headers:
    Retry-After:
      description: Number of seconds to wait before retrying the request.
      schema:
        type: integer
      example: 60
      required: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >
        Bearer token authentication using API tokens.

        Include the token in the Authorization header as: `Authorization: Bearer
        <token>`


        Obtain tokens from your Hum representative or contact
        support@letshum.com. There is no self-serve API key dashboard.

````