API Overview

The HatiData Control Plane exposes a RESTful API for managing organizations, users, environments, policies, API keys, billing, webhooks, audit logs, and more. All management operations go through this API -- the dashboard is a client of the same endpoints.

Base URL

https://api.hatidata.com/v1

All endpoints are prefixed with /v1. The API uses JSON for request and response bodies.

Authentication

Every request must include one of three authentication methods:

Method	Header	Use Case
JWT	Authorization: Bearer <jwt_token>	Dashboard users, SSO sessions
API Key	X-API-Key: hd_live_...	Programmatic access, SDKs, agents
Federated	Authorization: Bearer <cloud_token>	AWS STS, GCP Workload Identity, Azure AD

# JWT authentication
curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  https://api.hatidata.com/v1/organizations/org_abc

# API key authentication
curl -H "X-API-Key: hd_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  https://api.hatidata.com/v1/organizations/org_abc

For details on authentication methods, see Authentication.

Rate Limiting

Rate limits are applied per authentication identity:

Tier	Requests/minute	Burst
Free	60	10
Cloud	300	50
Growth	1,000	100
Enterprise	10,000	500

Rate limit headers are included in every response:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 298
X-RateLimit-Reset: 1708000060

When rate limited, the API returns 429 Too Many Requests with a Retry-After header.

Error Response Format

All errors follow a consistent JSON structure:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Field 'email' is required",
    "details": {
      "field": "email",
      "constraint": "required"
    },
    "request_id": "req_a1b2c3d4"
  }
}

Common Error Codes

HTTP Status	Code	Description
400	VALIDATION_ERROR	Invalid request body or query parameters
401	UNAUTHORIZED	Missing or invalid authentication
403	FORBIDDEN	Insufficient permissions or scope
404	NOT_FOUND	Resource does not exist
409	CONFLICT	Resource already exists or state conflict
422	POLICY_VIOLATION	Request blocked by ABAC policy
429	RATE_LIMITED	Too many requests
500	INTERNAL_ERROR	Unexpected server error
503	SERVICE_UNAVAILABLE	Temporarily unavailable (maintenance)

Pagination

List endpoints support cursor-based pagination:

curl "https://api.hatidata.com/v1/environments/env_abc/audit/queries?limit=50&cursor=cur_xyz"

Response includes pagination metadata:

{
  "data": [...],
  "pagination": {
    "cursor": "cur_next123",
    "has_more": true,
    "total": 1250
  }
}

Endpoint Groups

Group	Description	Reference
Organizations	Create and manage organizations	Organizations
Users	Invite, list, update, and remove users	Users
Environments	Create and promote environments	Environments
Policies	Standard and ABAC policy management	Policies
API Keys	Key lifecycle: create, rotate, revoke	API Keys
Billing	Usage tracking and quota management	Billing
Webhooks	Event notification configuration	Webhooks
Audit	Query and IAM audit log access	Audit
Provisioning	JIT access, agent capabilities, shadow mode	Provisioning
Query Proxy	SQL execution and wire protocol	Query Proxy
MCP Tools	Model Context Protocol tools for AI agents	MCP Tools
Transpile	Hybrid SQL transpilation (cloud API)	Hybrid Search

Data Protocols

HatiData supports three wire protocols for data access:

Postgres Wire Protocol (Primary)

The proxy listens on port 5439 and speaks the Postgres wire protocol. Any Postgres-compatible client (psql, pg, psycopg2, JDBC) can connect directly. This is the recommended protocol for agent workloads.

psql -h localhost -p 5439 -U analyst -d hatidata

Arrow Flight (High-Throughput)

For large result sets and columnar data transfer, HatiData supports Apache Arrow Flight on port 5440. Arrow Flight eliminates serialization overhead by transferring data in columnar Arrow format, making it ideal for analytics workloads and DataFrame integrations.

import pyarrow.flight as flight

client = flight.connect("grpc://localhost:5440")
info = client.get_flight_info(
    flight.FlightDescriptor.for_command(b"SELECT * FROM events")
)
reader = client.do_get(info.endpoints[0].ticket)
table = reader.read_all()  # Returns a PyArrow Table

Arrow Flight is available on Cloud and Enterprise tiers. Enable it in the proxy configuration:

[proxy]
arrow_flight_enabled = true
arrow_flight_port = 5440

MCP (Model Context Protocol)

For AI agents using Claude, Cursor, or other MCP-compatible hosts, HatiData exposes 24 tools via the MCP server. See MCP Tools for the complete reference covering SQL (7 tools), Memory (5), Chain-of-Thought (3), Triggers (4), and Branches (5).

Health Check

GET /health

Public endpoint (no authentication required). Returns service health:

curl https://api.hatidata.com/health

{
  "status": "healthy",
  "version": "1.0.0",
  "uptime_seconds": 86400
}

Request IDs

Every response includes an X-Request-Id header. Include this ID when contacting support:

X-Request-Id: req_a1b2c3d4e5f6g7h8

SDKs

Official SDKs handle authentication, pagination, and error handling:

• Python SDK -- pip install hatidata-agent
• TypeScript SDK -- npm install @hatidata/sdk