API Overview

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

Code	HTTP Status	Description
`VALIDATION_ERROR`	400	Request validation failed
`BAD_REQUEST`	400	Malformed request
`UNAUTHORIZED`	401	Authentication required
`MISSING_API_KEY`	401	No API key provided
`INVALID_API_KEY`	401	API key is invalid or inactive
`FORBIDDEN`	403	Access denied
`NOT_FOUND`	404	Resource not found
`CONFLICT`	409	Resource conflict (e.g., duplicate)
`INTERNAL_ERROR`	500	Internal 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

Limit	Value
Requests per second	1,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:

Parameter	Type	Default	Description
`limit`	integer	50	Max results per page (1-10000)
`offset`	integer	0	Number 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.

Overview

Ingest

Query

Base URL

Authentication

Request Format

Response Format

Error Codes

Validation Errors

Rate Limits

Instance Scoping

Available Endpoints

POST /ingest

GET /query

​Base URL

​Authentication

​Request Format

​Response Format

​Error Codes

​Validation Errors

​Rate Limits

​Pagination

​Instance Scoping

​Available Endpoints

POST /ingest

GET /query

Base URL

Authentication

Request Format

Response Format

Error Codes

Validation Errors

Rate Limits

Pagination

Instance Scoping

Available Endpoints