API Reference
Complete REST API documentation for AgenticAnts platform.
Base URL
code
https://api.agenticants.ai/v1
Authentication
All API requests require authentication via API key:
bash
curl https://api.agenticants.ai/v1/traces \
-H "Authorization: Bearer ants_sk_your_api_key_here"
Rate Limits
| Plan | Rate Limit | Burst |
|---|---|---|
| Pro | 1,000 req/min | 100 |
| Enterprise | Custom | Custom |
Rate limit headers:
code
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1635724800
Common Headers
Request Headers
code
Authorization: Bearer <api_key>
Content-Type: application/json
X-Request-ID: <unique_id>
Response Headers
code
Content-Type: application/json
X-Request-ID: <unique_id>
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
Endpoints
Traces
Create Trace
http
POST /v1/traces
Request:
json
{
"name": "customer-support-query",
"input": "Help with my order",
"metadata": {
"userId": "user_123",
"sessionId": "session_abc"
},
"tags": {
"environment": "production",
"team": "support"
}
}
Response:
json
{
"id": "trace_abc123",
"name": "customer-support-query",
"startTime": "2025-10-23T14:23:45Z",
"status": "in_progress",
"input": "Help with my order",
"metadata": {...},
"tags": {...}
}
Get Trace
http
GET /v1/traces/{trace_id}
Response:
json
{
"id": "trace_abc123",
"name": "customer-support-query",
"startTime": "2025-10-23T14:23:45Z",
"endTime": "2025-10-23T14:23:48Z",
"duration": 2500,
"status": "completed",
"input": "Help with my order",
"output": "I can help you track your order...",
"spans": [...],
"tokens": 350,
"cost": 0.0105,
"metadata": {...}
}
List Traces
http
GET /v1/traces?limit=100&offset=0&status=completed
Query Parameters:
limit- Number of results (default: 100, max: 1000)offset- Pagination offsetstatus- Filter by status:in_progress,completed,erroragent- Filter by agent namestartDate- ISO 8601 dateendDate- ISO 8601 date
Response:
json
{
"data": [
{...},
{...}
],
"pagination": {
"total": 1234,
"limit": 100,
"offset": 0,
"hasMore": true
}
}
Update Trace
http
PATCH /v1/traces/{trace_id}
Request:
json
{
"output": "I can help you track your order...",
"status": "completed",
"metadata": {
"success": true
}
}
Spans
Create Span
http
POST /v1/traces/{trace_id}/spans
Request:
json
{
"name": "llm-inference",
"parentId": null,
"startTime": "2025-10-23T14:23:46Z",
"attributes": {
"model": "gpt-4",
"temperature": 0.7
}
}
End Span
http
PATCH /v1/spans/{span_id}
Request:
json
{
"endTime": "2025-10-23T14:23:48Z",
"status": "ok",
"output": {...}
}
Metrics
Query Metrics
http
POST /v1/metrics/query
Request:
json
{
"metric": "latency_p95",
"agent": "customer-support",
"startDate": "2025-10-01T00:00:00Z",
"endDate": "2025-10-31T23:59:59Z",
"granularity": "1h"
}
Response:
json
{
"metric": "latency_p95",
"data": [
{"timestamp": "2025-10-01T00:00:00Z", "value": 1850},
{"timestamp": "2025-10-01T01:00:00Z", "value": 1920},
...
]
}
Available Metrics
| Metric | Description | Unit |
|---|---|---|
latency_p50 | 50th percentile latency | ms |
latency_p95 | 95th percentile latency | ms |
latency_p99 | 99th percentile latency | ms |
throughput | Requests per second | req/s |
error_rate | Error percentage | % |
token_count | Total tokens used | tokens |
cost | Total cost | USD |
Agents
List Agents
http
GET /v1/agents
Response:
json
{
"data": [
{
"id": "agent_123",
"name": "customer-support",
"version": "1.2.3",
"framework": "langchain",
"model": "gpt-4",
"status": "active",
"createdAt": "2025-10-01T00:00:00Z"
}
]
}
Get Agent Metrics
http
GET /v1/agents/{agent_id}/metrics
Response:
json
{
"agent": "customer-support",
"period": "last_24h",
"metrics": {
"totalRequests": 1234,
"avgLatency": 1850,
"errorRate": 0.5,
"totalCost": 45.67
}
}
Webhooks
Create Webhook
http
POST /v1/webhooks
Request:
json
{
"url": "https://your-app.com/webhooks/agenticants",
"events": ["trace.completed", "alert.triggered"],
"secret": "whsec_your_webhook_secret"
}
Webhook Events
| Event | Description |
|---|---|
trace.completed | Trace finished |
trace.error | Trace had error |
alert.triggered | Alert condition met |
budget.exceeded | Budget threshold exceeded |
pii.detected | PII found in data |
Webhook Payload:
json
{
"event": "trace.completed",
"timestamp": "2025-10-23T14:23:48Z",
"data": {
"traceId": "trace_abc123",
"agent": "customer-support",
"duration": 2500,
"status": "completed"
}
}
Error Handling
Error Response Format
json
{
"error": {
"code": "invalid_request",
"message": "Missing required field: name",
"details": {
"field": "name",
"reason": "required"
}
}
}
Error Codes
| Code | HTTP Status | Description |
|---|---|---|
invalid_request | 400 | Invalid request body |
authentication_failed | 401 | Invalid API key |
permission_denied | 403 | Insufficient permissions |
not_found | 404 | Resource not found |
rate_limit_exceeded | 429 | Too many requests |
internal_error | 500 | Server error |
SDKs
JavaScript/TypeScript
bash
npm install @agenticants/sdk
typescript
const ants = new AgenticAnts({
apiKey: process.env.AGENTICANTS_API_KEY
})
Python
bash
pip install agenticants
python
from agenticants import AgenticAnts
ants = AgenticAnts(api_key=os.getenv('AGENTICANTS_API_KEY'))
Code Examples
Complete Trace Example
bash
# 1. Create trace
curl -X POST https://api.agenticants.ai/v1/traces \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "customer-support",
"input": "Help with order"
}'
# Response: {"id": "trace_123", ...}
# 2. Create span
curl -X POST https://api.agenticants.ai/v1/traces/trace_123/spans \
-H "Authorization: Bearer $API_KEY" \
-d '{
"name": "llm-call",
"startTime": "2025-10-23T14:23:45Z"
}'
# Response: {"id": "span_456", ...}
# 3. End span
curl -X PATCH https://api.agenticants.ai/v1/spans/span_456 \
-H "Authorization: Bearer $API_KEY" \
-d '{
"endTime": "2025-10-23T14:23:47Z",
"status": "ok"
}'
# 4. Complete trace
curl -X PATCH https://api.agenticants.ai/v1/traces/trace_123 \
-H "Authorization: Bearer $API_KEY" \
-d '{
"output": "Your order is on the way!",
"status": "completed"
}'
Versioning
API version is specified in the URL: /v1/
- Current version: v1
- Stable: Yes
- Deprecation notice: 6 months minimum
Support
- Documentation: https://agenticants.ai/docs
- Status: https://status.agenticants.ai
- Support: support@agenticants.ai
Next Steps
- Authentication - Detailed auth guide
- Traces API - Complete traces documentation
- Webhooks - Set up webhooks