API Reference
Purl REST API
Ingest, search, and manage logs programmatically. Authenticate with API keys for ingest or session cookies for the dashboard.
Authentication
Purl supports two authentication methods:
API Key
For programmatic access and log ingestion
X-API-Key: your-api-keySession Cookie
For browser-based dashboard access
POST /api/auth/loginQuick Start
Ingest logs
curl — ingest
curl -X POST http://your-purl:3000/api/logs \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '[
{
"timestamp": "2026-02-18T10:30:00Z",
"level": "error",
"message": "Connection timeout to database",
"source": "api-server",
"host": "prod-01"
}
]'Search logs (KQL)
curl — search
curl -H "X-API-Key: your-api-key" \
"http://your-purl:3000/api/logs?q=level:error AND source:api-server&range=1h&limit=50"Ingest via OTLP (OpenTelemetry)
curl — OTLP
curl -X POST http://your-purl:3000/api/v1/otlp/logs \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"resourceLogs": [{
"resource": {
"attributes": [
{"key": "service.name", "value": {"stringValue": "my-app"}}
]
},
"scopeLogs": [{
"logRecords": [{
"timeUnixNano": "1708250000000000000",
"severityText": "ERROR",
"body": {"stringValue": "Connection refused"}
}]
}]
}]
}'Health check
curl — health
curl http://your-purl:3000/api/health
# {"status":"ok","clickhouse":"connected","uptime_secs":86400}Endpoint Reference
Click any section to expand the full list of endpoints. Endpoints marked with a feature badge require the corresponding license feature.
Response Format
Success response
json
{
"hits": [...],
"total": 1234,
"query": "level:error"
}Error response
json
{
"error": "Invalid query syntax",
"status": 400
}Common headers
Response Headers
| Header | Description |
|---|---|
X-Cache | HIT or MISS — indicates if response was served from cache |
X-RateLimit-Limit | Maximum requests per window |
X-RateLimit-Remaining | Remaining requests in current window |
Content-Type | application/json for all API responses |
Feature Gates
Some endpoints require specific license features. Requests to gated endpoints without the required feature return 403 Forbidden.
License Features
| Feature | Plan | Description |
|---|---|---|
pattern_analysis | Pro+ | Log pattern detection and grouping |
saved_searches_unlimited | Pro+ | Unlimited saved searches |
custom_dashboards | Pro+ | Custom dashboard builder |
pipelines | Pro+ | Data processing pipelines |
es_compat | Pro+ | Elasticsearch-compatible search API |
ai_query | Enterprise | Natural language → SQL queries |
sso | Enterprise | SAML 2.0 SSO authentication |
ldap_auth | Enterprise | LDAP / Active Directory auth |
audit_logs | Enterprise | Audit trail for all actions |
backup | Enterprise | Backup and restore operations |
Rate Limiting
All authenticated endpoints are rate-limited. When exceeded, you receive a 429 Too Many Requests response. Check the X-RateLimit-Remaining header to monitor your usage. The ingest endpoint accepts up to 10,000 records per batch.