API Reference

Complete reference for the Foil REST API

API Reference

The Foil API provides programmatic access to traces, alerts, analytics, and more.

Base URL

https://api.getfoil.ai/api

For self-hosted deployments, use your instance URL.

Authentication

Foil supports two authentication methods:

JWT Bearer Token

For dashboard and user-authenticated requests:

curl -X GET https://api.getfoil.ai/api/users/profile \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Obtain a JWT token via the login endpoint:

POST /api/auth/login
{
  "email": "[e-mail]",
  "password": "your-password"
}

API Key

For SDK and programmatic access:

curl -X POST https://api.getfoil.ai/api/signals \
  -H "x-api-key: sk_live_xxx_yyy" \
  -H "Content-Type: application/json" \
  -d '{"signalName": "user_rating", "value": 5}'

API keys are created in the dashboard under Settings > API Keys.

API keys provide full access to your data. Keep them secure and never expose them in client-side code.

Rate Limits

Tier	Limit	Endpoints
Standard	100 req/min	Users, Analytics, Agents, Events
Strict	20 req/min	API Keys, Admin
Ingestion	500 req/min	Spans, Signals, Logs

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704067200

Response Format

All responses are JSON with consistent structure:

Success Response

{
  "success": true,
  "data": { ... }
}

Error Response

{
  "success": false,
  "error": {
    "message": "Description of what went wrong",
    "code": "ERROR_CODE"
  }
}

Common Error Codes

Code	HTTP Status	Description
UNAUTHORIZED	401	Missing or invalid authentication
FORBIDDEN	403	Insufficient permissions
NOT_FOUND	404	Resource doesn’t exist
VALIDATION_ERROR	400	Invalid request parameters
RATE_LIMITED	429	Too many requests
INTERNAL_ERROR	500	Server error

Pagination

List endpoints support pagination:

GET /api/spans/traces?limit=50&skip=100

Parameter	Default	Description
limit	50	Number of items per page (max 100)
skip	0	Number of items to skip

Response includes pagination info:

{
  "data": [...],
  "pagination": {
    "total": 1250,
    "limit": 50,
    "skip": 100,
    "hasMore": true
  }
}

Date Filtering

Most endpoints accept date filters:

GET /api/analytics/metrics?startDate=2024-01-01&endDate=2024-01-31

Dates should be in ISO 8601 format: YYYY-MM-DD or YYYY-MM-DDTHH:mm:ssZ

Core Endpoints

Authentication

Method	Endpoint	Description
POST	/auth/login	User login
POST	/auth/register	User registration
POST	/auth/forgot-password	Request password reset
POST	/auth/reset-password	Reset password with token
GET	/auth/verify-email	Verify email address

API Keys

Method	Endpoint	Description
POST	/keys	Create new API key
GET	/keys	List all API keys
PUT	/keys/:id/refresh	Rotate API key
POST	/keys/:id/revoke	Revoke API key
DELETE	/keys/:id	Delete API key

Spans & Traces

Method	Endpoint	Description
GET	/spans/traces	List traces (root spans)
GET	/spans/traces/:traceId	Get trace with all spans
GET	/spans/filters	Get available filter options

Signals

Method	Endpoint	Description
POST	/signals	Record a signal
POST	/signals/batch	Record multiple signals
GET	/signals	List signals
GET	/signals/summary	Get signal aggregations
GET	/signals/trace/:traceId	Get signals for trace

Agents

Method	Endpoint	Description
GET	/agents	List all agents
POST	/agents	Create agent
GET	/agents/:agentId	Get agent
PUT	/agents/:agentId	Update agent
DELETE	/agents/:agentId	Delete agent
PUT	/agents/:agentId/alerts	Update alert settings

Alerts

Method	Endpoint	Description
GET	/spans/alerts	List all alerts
GET	/spans/alerts/summary	Alert summary by agent
GET	/spans/alerts/:alertId	Get alert details
PUT	/spans/alerts/:alertId/acknowledge	Acknowledge alert
PUT	/spans/alerts/:alertId/reopen	Reopen alert

Analytics

Method	Endpoint	Description
GET	/analytics/metrics	Dashboard metrics
GET	/analytics/traces/success-failure	Success/failure rates
GET	/analytics/traces/requests-over-time	Request volume
GET	/analytics/traces/latency-percentiles	Latency metrics
GET	/analytics/traces/token-usage	Token consumption
GET	/analytics/costs	Cost breakdown

Experiments

Method	Endpoint	Description
GET	/experiments	List experiments
POST	/experiments	Create experiment
GET	/experiments/:id	Get experiment
POST	/experiments/:id/start	Start experiment
POST	/experiments/:id/pause	Pause experiment
POST	/experiments/:id/stop	Stop experiment
GET	/experiments/:id/assign	Get variant assignment
GET	/experiments/:id/results	Get experiment results

SDKs

For easier integration, use our official SDKs:

JavaScript SDK

npm install @foil-ai/sdk

Python SDK

pip install foil-sdk