Flezi AgentBox

API Reference

Public REST API for agent execution, authentication, and marketplace operations

API Reference

The Flezi AgentBox Public API allows you to execute agents programmatically. This guide covers authentication, endpoints, and response formats.

Base URL

https://your-agentbox-instance.com/api/v1

For local development:

http://localhost:4000/api/v1

Authentication

All API requests require an API key in the Authorization header:

bash
curl -H "Authorization: Bearer your-api-key" \
  https://your-instance.com/api/v1/agents

Obtaining an API Key

  1. Log in to Flezi AgentBox
  2. Navigate to Settings > API Keys
  3. Click Generate New Key
  4. Copy the key — it won't be shown again

API keys are sensitive credentials. Never commit them to source control or share them publicly. Use environment variables in your applications.

Endpoints

Execute Agent

Execute an agent and receive results.

Synchronous Mode:

bash
POST /api/v1/agents/:agentId/execute
 
# Request
curl -X POST \
  -H "Authorization: Bearer your-key" \
  -H "Content-Type: application/json" \
  -d '{"input": "Review this code for security issues", "options": {"model": "gpt-4"}}' \
  http://localhost:4000/api/v1/agents/agent-uuid/execute

Response:

json
{
  "executionId": "exec-uuid",
  "status": "completed",
  "output": "The code has the following security concerns...",
  "duration": 2340,
  "tokensUsed": 1250
}

Streaming Mode (SSE):

bash
POST /api/v1/agents/:agentId/execute
Accept: text/event-stream
 
curl -X POST \
  -H "Authorization: Bearer your-key" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"input": "Analyze this dataset"}' \
  http://localhost:4000/api/v1/agents/agent-uuid/execute

SSE Response:

event: token
data: {"text": "The "}

event: token
data: {"text": "analysis "}

event: token
data: {"text": "shows..."}

event: done
data: {"executionId": "exec-uuid", "duration": 3200}

List Agents

Retrieve a list of published agents.

bash
GET /api/v1/agents?category=code-assistant&limit=20&offset=0
 
# Response
{
  "agents": [
    {
      "id": "agent-uuid",
      "name": "Code Review Agent",
      "description": "Automated code review...",
      "category": "code-assistant",
      "rating": 4.5,
      "executions": 1250
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

Get Agent Details

bash
GET /api/v1/agents/:agentId
 
# Response
{
  "id": "agent-uuid",
  "name": "Code Review Agent",
  "description": "...",
  "version": "2.1.0",
  "category": "code-assistant",
  "creator": { "id": "user-uuid", "name": "Creator Name" },
  "config": { "model": "gpt-4", "temperature": 0.7 },
  "stats": { "stars": 42, "executions": 1250, "rating": 4.5 }
}

Rate Limits

| Endpoint | Limit | Window | |----------|-------|--------| | Agent Execution | 60 requests | Per minute | | List/Search | 120 requests | Per minute | | Agent Details | 120 requests | Per minute |

Rate limit headers are included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1640000000

Error Codes

| Code | Status | Description | |------|--------|-------------| | AUTH_REQUIRED | 401 | Missing or invalid API key | | FORBIDDEN | 403 | Insufficient permissions | | NOT_FOUND | 404 | Agent or resource not found | | RATE_LIMITED | 429 | Too many requests | | EXECUTION_ERROR | 500 | Agent execution failed | | TIMEOUT | 504 | Execution timed out |

Error Response Format:

json
{
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "A valid API key is required",
    "details": {}
  }
}

SDK Examples

JavaScript/TypeScript

typescript
const response = await fetch(
  "http://localhost:4000/api/v1/agents/agent-uuid/execute",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.XVISTA_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      input: "Review this pull request",
      options: { model: "claude-3-sonnet" },
    }),
  }
);
 
const result = await response.json();
console.log(result.output);

Python

python
import requests
 
response = requests.post(
    "http://localhost:4000/api/v1/agents/agent-uuid/execute",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "input": "Analyze this code for bugs",
        "options": {"model": "gpt-4"},
    },
)
 
result = response.json()
print(result["output"])

Next Steps