​
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
For local development: 
http://localhost:8000

​
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.

​
Request Format

​
Headers

Required headers for all requests: 
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
  }
}

​
Response Format

​
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

CodeMeaning
200Success
201Created
400Bad Request
401Unauthorized
404Not Found
429Rate Limited
500Internal 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

​
Pagination

List endpoints support pagination: 
GET /v1/agents?page=2&limit=20
Response includes pagination metadata: 
{
  "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

FeatureSDKDirect API
Ease of use⭐⭐⭐⭐⭐⭐⭐⭐
Type safety✅❌
Auto-retry✅❌
Streaming support✅Manual
Language supportMultipleAny

​
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

Authentication

Set up API authentication

Endpoints

Explore available endpoints