Docs/Api Reference

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 offset
status - Filter by status: in_progress, completed, error
agent - Filter by agent name
startDate - ISO 8601 date
endDate - 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

Metrics and trends are not available through the SDK or REST API. View latency, throughput, error rate, token usage, and cost over time in the dashboard at https://app.agenticants.ai, where you can filter by agent and time range.

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" } ] }

Agent Metrics

Per-agent metrics (request volume, average latency, error rate, total cost) are a dashboard feature. Open the agent in the dashboard at https://app.agenticants.ai to view them.

Webhooks (Automations)

Webhooks are configured as an Automation, not through a REST endpoint. An automation pairs a trigger (an event in your project) with an action (an outbound webhook, Slack, or PagerDuty). Set them up in the dashboard at app.agenticants.ai → Automations:

Trigger - choose an event source and the actions to fire on.
Action - select Webhook, enter your endpoint URL, and generate a signing secret.

Available Events

The trigger event source is currently prompt versions. Each delivery carries a type and an action:

`type`	`action`	Fires when
`prompt-version`	`created`	A new prompt version is created
`prompt-version`	`updated`	A prompt version is updated (e.g. labels changed)
`prompt-version`	`deleted`	A prompt version is deleted

Webhook Payload

The webhook is delivered as an HTTP POST to your endpoint with this body:

json

{ "id": "evt_abc123", "timestamp": "2026-06-24T14:23:48.000Z", "type": "prompt-version", "apiVersion": "v1", "action": "created", "prompt": { "id": "prompt_abc123", "name": "customer-support", "version": 3, "projectId": "proj_abc123", "labels": ["production"], "prompt": "You are a helpful customer support agent...", "type": "text", "config": {}, "commitMessage": "Tighten the system prompt", "tags": ["support"], "createdAt": "2026-06-24T14:23:48.000Z", "updatedAt": "2026-06-24T14:23:48.000Z" } }

Verifying the Signature

Every delivery includes an x-langfuse-signature header so you can verify it came from AgenticAnts:

code

x-langfuse-signature: t=1750772628,v1=3f9a1c...e2

Compute HMAC-SHA256(secret, requestBody) over the raw request body using your webhook signing secret, then compare against the v1= value. The t= value is the unix timestamp the signature was generated (use it to reject stale deliveries).

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 ants-platform

The REST client (AntsPlatformClient) covers prompts, datasets, and scores. It does not capture traces — use the OpenTelemetry-based tracing setup for that.

typescript

const client = new AntsPlatformClient({ publicKey: process.env.ANTS_PLATFORM_PUBLIC_KEY, secretKey: process.env.ANTS_PLATFORM_SECRET_KEY, baseUrl: "https://api.agenticants.ai", })

Python

bash

pip install ants-platform

python

from ants_platform import AntsPlatform client = AntsPlatform( public_key=os.getenv("ANTS_PLATFORM_PUBLIC_KEY"), secret_key=os.getenv("ANTS_PLATFORM_SECRET_KEY"), host="https://api.agenticants.ai", )

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

Explore Traces API →