API Reference — Future AGI
Complete REST API reference for the Future AGI platform. Covers simulations, evaluations, scenarios, personas, datasets, annotations, and more.
About
The Future AGI REST API provides programmatic access to all platform features including simulations, evaluations, datasets, and more.
Base URL
https://api.futureagi.comAuthentication
All API endpoints require authentication via API keys:
| Header | Description |
|---|---|
X-Api-Key | Your API key |
X-Secret-Key | Your secret key |
Tip
Get your API key from the Future AGI Dashboard.
API Categories
Health
Health check operations for monitoring server status
Scenarios
Test scenario management and execution
Agent Definitions
Agent definition CRUD operations
Agent Versions
Agent version control and management
Personas
Persona management for testing
Run Tests
Test execution management
Test Executions
Test execution tracking and analytics
Datasets
Dataset creation, modification, and data management
Dataset Evals
Add and run evaluations on datasets
Annotation Scores
Create, read, and delete annotation scores across traces, spans, sessions, and datasets
Annotation Labels
Manage reusable annotation label templates (categorical, numeric, text, star, thumbs)
Annotation Queues
Create and manage annotation queues with assignment strategies and progress tracking
Queue Items
Add items to queues, submit annotations, complete and skip items
Bulk Annotation
Bulk annotate spans via the legacy tracer API (up to 1000 records per request)
Eval Tasks
Eval task lifecycle — create, pause, resume, and manage evaluation runs on trace spans
Custom Eval Configs
Custom eval config management — create, check, and list evaluation configurations
Rate Limits
- Standard tier: 100 requests per minute
- Pro tier: 1000 requests per minute
- Enterprise: Custom limits
Rate limit headers are included in all responses:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1699900000Error Handling
All errors return a consistent JSON structure:
{
"error": {
"code": "error_code",
"message": "Human readable error message",
"details": {}
}
}Common Error Codes
| Code | Description |
|---|---|
| 400 | Bad Request — Invalid parameters |
| 401 | Unauthorized — Invalid or missing API key |
| 403 | Forbidden — Insufficient permissions |
| 404 | Not Found — Resource doesn’t exist |
| 429 | Too Many Requests — Rate limit exceeded |
| 500 | Internal Server Error |
Questions & Discussion