API Reference

v2.0StableLast updated: January 2026

The ThinkHive REST API provides programmatic access to all platform features.

Base URL

https://app.thinkhive.ai

For demo/development:

https://demo.thinkhive.ai

Note: All API endpoints are served from the main application domain. There is no separate api.thinkhive.ai subdomain.

Authentication

All API requests require authentication using either:

API Key (recommended for server-to-server)
Session Token (for browser-based apps)

# API Key authentication
curl -H "Authorization: Bearer thk_your_api_key" \
  https://app.thinkhive.ai/api/agents

See Authentication for details.

Endpoints Overview

Agents Traces & Spans Guardrails Issues & Fixes Evaluation & Grading Explainability & Analysis Business Metrics & ROI Webhooks & Notifications Compliance & Scanning

Quick Reference

Category	Endpoints	Description
Health	4	Health checks and readiness
Agents	6	Agent CRUD and config
Departments	4	Department management
Traces & Spans	10	Trace ingestion (OTLP + simple), querying, spans
Sessions	3	Trace session management
Issues (v2)	5	Failure issue management
Fixes	5	Fix proposals and testing
Shadow Tests	4	Shadow test execution
Guardrails	8	Scanning, scanners, policies, analytics
Evaluation	8	Eval sets, criteria, and runs
Eval Runs	4	Evaluation run management
Deterministic Graders	3	Rule-based evaluation
Human Review	6	Review queue, assignment, calibration
Eval Health	4	Health monitoring, regressions, saturation
Nondeterminism	4	Pass@k analysis, consistency
Conversation Eval	3	Multi-turn conversation analysis
Explainability (v1)	10	Analysis, clusters, counterfactuals
Analyzer (v2)	4	Analysis with cost estimation
Deep Dive (v2)	3	Structured investigation
Error Analysis (v2)	3	Error categorization
Transcript Patterns	3	Pattern detection in conversations
ROI Analytics	6	Revenue impact and correlation
Quality Metrics	5	RAG scores, hallucination detection
Business Metrics	4	Business metric tracking
API Keys (v2)	8	Key management, rotation, testing
Webhooks	6	Webhook endpoint management and delivery
Notifications	6	Rules and channel configuration
Compliance	5	Compliance reporting and scanning
Flagged Traces	4	Trace flagging and review
Drift	3	Drift detection
Intelligence	4	Business intelligence

Total: 150+ endpoints

Request Format

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <api_key>` or session token
`Content-Type`	For POST/PUT	`application/json`
`X-Request-ID`	No	Optional request tracing ID

Request Body

{
  "field": "value",
  "nested": {
    "key": "value"
  }
}

Response Format

Success Response

{
  "success": true,
  "data": {
    // Response data
  }
}

Paginated Response

{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "hasMore": true
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input",
    "details": {
      "field": "agentId",
      "reason": "Required field missing"
    }
  }
}

Error Codes

HTTP Status	Error Code	Description
400	`VALIDATION_ERROR`	Invalid request parameters
401	`UNAUTHORIZED`	Missing or invalid authentication
403	`FORBIDDEN`	Insufficient permissions
404	`NOT_FOUND`	Resource not found
409	`CONFLICT`	Resource already exists
429	`RATE_LIMITED`	Too many requests
500	`INTERNAL_ERROR`	Server error

Rate Limits

Tier	Rate Limit	Burst
Free	10 req/min	20
Starter	60 req/min	100
Professional	300 req/min	500
Enterprise	1,000 req/min	2,000

Rate limit headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1704067200

Pagination

Use page and limit query parameters:

GET /api/traces?page=2&limit=50

Filtering

Use query parameters for filtering:

GET /api/traces?agentId=agent_123&outcome=failure&startDate=2024-01-01

Sorting

Use sortBy and sortOrder parameters:

GET /api/traces?sortBy=createdAt&sortOrder=desc

SDK Integration

For easier integration, use our official SDKs:

// JavaScript/TypeScript
import { ThinkHiveClient } from '@thinkhive/sdk';
 
const client = new ThinkHiveClient({
  apiKey: 'thk_your_api_key',
});
 
const traces = await client.traces.list({
  agentId: 'agent_123',
  limit: 50,
});

# Python
import thinkhive
 
client = thinkhive.Client(api_key='thk_your_api_key')
 
traces = client.traces.list(
    agent_id='agent_123',
    limit=50,
)

OpenAPI Spec: Download the full OpenAPI specification at /api/openapi.json for code generation and API exploration tools.

Next Steps

Authentication — Authentication methods and API keys
Agents — Agent management
Traces — Trace ingestion and querying
Guardrails — Real-time content scanning

API Key Management — Create, rotate, and secure API keys
Webhooks — Real-time event notifications
ThinkEval — Evaluation framework guide
Human Review — Human review queue management
Guardrail Policies — Configuring guardrail policies
Business Metrics & ROI — Connect AI to business outcomes

Authentication & API Keys