API Introduction

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

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

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

Feature	SDK	Direct API
Ease of use	⭐⭐⭐⭐⭐	⭐⭐⭐
Type safety	✅	❌
Auto-retry	✅	❌
Streaming support	✅	Manual
Language support	Multiple	Any

Quick Start

cURL
Python
JavaScript

# 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

import requests

headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

# List agents
response = requests.get(
    "https://api.run-agent.ai/v1/agents",
    headers=headers
)

# Invoke agent
response = requests.post(
    "https://api.run-agent.ai/v1/agents/AGENT_ID/invoke",
    headers=headers,
    json={"query": "Hello"}
)

// List agents
const response = await fetch('https://api.run-agent.ai/v1/agents', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

// Invoke agent
const result = await fetch('https://api.run-agent.ai/v1/agents/AGENT_ID/invoke', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ query: 'Hello' })
});

Next Steps

Authentication

Set up API authentication

Endpoints

Explore available endpoints

Still have a question?

Join our Discord Community
Email us: [email protected]
Follow us on X
New here? Sign up

Reference

API Reference

SDK Reference

CLI Reference

Configuration

Overview

Base URL

Authentication

Request Format

Headers

Request Body

Response Format

Success Response

Error Response

Status Codes

Rate Limiting

Versioning

Common Patterns

Async Operations

Streaming Responses

Batch Operations

SDK vs Direct API

Quick Start

Next Steps

Authentication

Endpoints

Still have a question?

​Overview

​Base URL

​Authentication

​Request Format

​Headers

​Request Body

​Response Format

​Success Response

​Error Response

​Status Codes

​Rate Limiting

​Pagination

​Versioning

​Common Patterns

​Async Operations

​Streaming Responses

​Batch Operations

​SDK vs Direct API

​Quick Start

​Next Steps

Authentication

Endpoints

Still have a question?

Overview

Base URL

Authentication

Request Format

Headers

Request Body

Response Format

Success Response

Error Response

Status Codes

Rate Limiting

Pagination

Versioning

Common Patterns

Async Operations

Streaming Responses

Batch Operations

SDK vs Direct API

Quick Start

Next Steps