Skip to main content

​
Base URL

All API requests should be made to: 
https://api.usethunder.com/v1/

​
Authentication

All endpoints require authentication via the x-api-key header. See Authentication for details.

​
Request Format

  • Content-Type: application/json for POST requests
  • Accept: application/json

​
Response Format

All responses are JSON objects. Successful responses return the requested data directly. Error responses follow a standard format: 
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {}
  }
}

​
Error Codes

CodeHTTP StatusDescription
VALIDATION_ERROR400Request validation failed
BAD_REQUEST400Malformed request
UNAUTHORIZED401Authentication required
MISSING_API_KEY401No API key provided
INVALID_API_KEY401API key is invalid or inactive
FORBIDDEN403Access denied
NOT_FOUND404Resource not found
CONFLICT409Resource conflict (e.g., duplicate)
INTERNAL_ERROR500Internal server error

​
Validation Errors

When request validation fails, the details field contains an array of specific field errors: 
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "path": "messages.0.content",
        "message": "Content must not be empty"
      },
      {
        "path": "instanceId",
        "message": "Invalid uuid"
      }
    ]
  }
}

​
Rate Limits

LimitValue
Requests per second1,000
Rate limit headers are included in responses:
  • X-RateLimit-Limit - Maximum requests allowed
  • X-RateLimit-Remaining - Requests remaining in current window
  • X-RateLimit-Reset - Unix timestamp when the limit resets
When rate limited, you’ll receive a 429 Too Many Requests response.

​
Pagination

The query endpoint supports pagination via limit and offset parameters:
ParameterTypeDefaultDescription
limitinteger50Max results per page (1-10000)
offsetinteger0Number of results to skip
Paginated responses include a pagination object: 
{
  "elements": [...],
  "pagination": {
    "total": 150,
    "limit": 50,
    "offset": 0
  }
}

​
Instance Scoping

All analytics in Thunder are scoped to instances. When you query metrics, you must specify an instanceId and results will only include data from that instance. Topics, signals, gaps, and usage metrics are analyzed separately per instance.

​
Available Endpoints

POST /ingest

Ingest conversation messages

GET /query

Query analytics and metrics