Overview
The RunAgent API is a RESTful interface that allows you to deploy, manage, and interact with AI agents programmatically. All API access is over HTTPS, and data is sent and received as JSON.
Base URL
https://api.run-agent.ai/v1
Authentication
All API requests require authentication using an API key:
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://api.run-agent.ai/v1/agents
Never expose your API key in client-side code or public repositories.
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json
Request Body
POST and PUT requests accept JSON:
{
"query": "Your input here",
"parameters": {
"temperature": 0.7,
"max_tokens": 150
}
}
Success Response
{
"status": "success",
"data": {
"result": "Agent response here",
"metadata": {
"execution_time": 1.23,
"tokens_used": 150
}
}
}
Error Response
{
"status": "error",
"error": {
"code": "INVALID_INPUT",
"message": "Query parameter is required",
"details": {
"field": "query",
"reason": "missing"
}
}
}
Status Codes
| Code | Meaning |
|---|
| 200 | Success |
| 201 | Created |
| 400 | Bad Request |
| 401 | Unauthorized |
| 404 | Not Found |
| 429 | Rate Limited |
| 500 | Internal Error |
Rate Limiting
API requests are rate limited:
- Free tier: 100 requests per hour
- Pro tier: 1,000 requests per hour
- Enterprise: Custom limits
Rate limit headers:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200
GET /v1/agents?page=2&limit=20
{
"data": [...],
"pagination": {
"page": 2,
"limit": 20,
"total": 100,
"pages": 5
}
}
Versioning
The API is versioned via the URL path:
- Current version:
v1
- Legacy support: 12 months
- Deprecation notices: 6 months in advance
Common Patterns
Async Operations
Long-running operations return immediately:
{
"operation_id": "op_123abc",
"status": "pending",
"check_url": "/v1/operations/op_123abc"
}
Streaming Responses
For streaming endpoints, use Server-Sent Events:
curl -H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: text/event-stream" \
https://api.run-agent.ai/v1/agents/123/stream
Batch Operations
Submit multiple requests in one call:
{
"batch": [
{"query": "Question 1"},
{"query": "Question 2"},
{"query": "Question 3"}
]
}
SDK vs Direct API
| Feature | SDK | Direct API |
|---|
| Ease of use | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ |
| Type safety | ✅ | ❌ |
| Auto-retry | ✅ | ❌ |
| Streaming support | ✅ | Manual |
| Language support | Multiple | Any |
Quick Start
# List agents
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://api.run-agent.ai/v1/agents
# Invoke agent
curl -X POST \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "Hello"}' \
https://api.run-agent.ai/v1/agents/AGENT_ID/invoke
Next Steps
