API Reference

Complete documentation of Agentopia's APIs and integrations

Table of Contents

API Overview

The Agentopia API provides a comprehensive set of endpoints for creating, managing, and deploying AI agents. Our RESTful API allows developers to integrate agent capabilities into their applications and services.

Base URL

https://api.agentopia.org/v1

API Versioning

The Agentopia API uses versioning to ensure backward compatibility. The current version is v1. We recommend always specifying the version in your API calls.

API Design Principles

  • RESTful: Our API follows REST principles for predictable resource-oriented URLs
  • JSON: All requests and responses use JSON format
  • HTTPS: All API requests must use HTTPS for security
  • Stateless: Each request contains all information needed to complete the operation

Authentication

The Agentopia API uses API keys for authentication. You can obtain an API key from your Agentopia dashboard.

API Keys

Include your API key in the request header:

Authorization: Bearer YOUR_API_KEY

Example Request with Authentication

curl -X GET \
  https://api.agentopia.org/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

API Key Management

Best practices for managing your API keys:

  • Never expose your API key in client-side code
  • Use environment variables to store your API key
  • Rotate your API keys periodically
  • Use different API keys for development and production

Rate Limits

To ensure fair usage and system stability, the Agentopia API implements rate limiting. Rate limits vary based on your subscription tier.

Tier Requests per Minute Requests per Day
Free 60 10,000
Developer 300 50,000
Enterprise 1,000+ Custom

Rate Limit Headers

Each API response includes headers to help you track your rate limit usage:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1622119200

When you exceed your rate limit, you'll receive a 429 Too Many Requests response. The response will include a Retry-After header indicating how long to wait before making another request.

Agent Endpoints

The following endpoints allow you to create, manage, and interact with AI agents in the Agentopia ecosystem.

List Agents

Returns a list of all agents associated with your account.

Endpoint

GET /agents

Query Parameters

  • limit: Maximum number of results (default: 20)
  • offset: Pagination offset (default: 0)
  • category: Filter by agent category

Example Response

{
  "data": [
    {
      "id": "agt_123456789",
      "name": "Research Buddy",
      "description": "AI assistant for academic research",
      "category": "regular_single",
      "created_at": "2025-04-15T12:00:00Z",
      "status": "active"
    },
    {
      "id": "agt_987654321",
      "name": "Code Helper",
      "description": "Programming assistant for developers",
      "category": "regular_single",
      "created_at": "2025-04-10T09:30:00Z",
      "status": "active"
    }
  ],
  "meta": {
    "total": 2,
    "limit": 20,
    "offset": 0
  }
}

Create Agent

Creates a new agent with the specified configuration.

Endpoint

POST /agents

Request Body

  • name: Agent name (required)
  • description: Agent description
  • category: Agent category (required)
  • config: Agent configuration object

Example Request

{
  "name": "Data Analyst",
  "description": "AI assistant for data analysis tasks",
  "category": "autonomous_single",
  "config": {
    "model": "gpt-4",
    "temperature": 0.7,
    "tools": ["search", "calculator", "data_visualization"],
    "memory_capacity": 10
  }
}

Example Response

{
  "id": "agt_567890123",
  "name": "Data Analyst",
  "description": "AI assistant for data analysis tasks",
  "category": "autonomous_single",
  "created_at": "2025-05-29T22:45:00Z",
  "status": "initializing",
  "config": {
    "model": "gpt-4",
    "temperature": 0.7,
    "tools": ["search", "calculator", "data_visualization"],
    "memory_capacity": 10
  }
}

Get Agent

Retrieves details for a specific agent.

Endpoint

GET /agents/{agent_id}

Path Parameters

  • agent_id: Unique identifier for the agent

Example Response

{
  "id": "agt_123456789",
  "name": "Research Buddy",
  "description": "AI assistant for academic research",
  "category": "regular_single",
  "created_at": "2025-04-15T12:00:00Z",
  "status": "active",
  "config": {
    "model": "gpt-4",
    "temperature": 0.5,
    "tools": ["search", "document_retrieval"],
    "memory_capacity": 5
  },
  "stats": {
    "total_interactions": 157,
    "average_response_time": 2.3,
    "last_active": "2025-05-28T18:30:00Z"
  }
}

Update Agent

Updates an existing agent's configuration.

Endpoint

PATCH /agents/{agent_id}

Path Parameters

  • agent_id: Unique identifier for the agent

Example Request

{
  "name": "Advanced Research Buddy",
  "config": {
    "temperature": 0.7,
    "tools": ["search", "document_retrieval", "citation_generator"]
  }
}

Example Response

{
  "id": "agt_123456789",
  "name": "Advanced Research Buddy",
  "description": "AI assistant for academic research",
  "category": "regular_single",
  "created_at": "2025-04-15T12:00:00Z",
  "updated_at": "2025-05-29T22:46:00Z",
  "status": "active",
  "config": {
    "model": "gpt-4",
    "temperature": 0.7,
    "tools": ["search", "document_retrieval", "citation_generator"],
    "memory_capacity": 5
  }
}

Delete Agent

Deletes an agent. This action cannot be undone.

Endpoint

DELETE /agents/{agent_id}

Path Parameters

  • agent_id: Unique identifier for the agent

Example Response

{
  "success": true,
  "message": "Agent successfully deleted"
}

Interact with Agent

Sends a message to an agent and receives a response.

Endpoint

POST /agents/{agent_id}/interact

Path Parameters

  • agent_id: Unique identifier for the agent

Example Request

{
  "message": "What are the latest developments in quantum computing?",
  "conversation_id": "conv_987654321",  // Optional, for continuing a conversation
  "context": {  // Optional, additional context
    "user_expertise": "beginner",
    "preferred_sources": ["academic", "news"]
  }
}

Example Response

{
  "response": "Recent developments in quantum computing include Google's achievement of quantum supremacy, IBM's 127-qubit processor, and advances in error correction. Researchers are now focusing on creating more stable qubits and developing practical quantum algorithms...",
  "conversation_id": "conv_987654321",
  "message_id": "msg_456789012",
  "sources": [
    {
      "title": "Quantum Computing Progress Report 2025",
      "url": "https://example.com/quantum-report-2025",
      "snippet": "The field has seen remarkable progress in the last year..."
    }
  ],
  "thinking_process": [  // Only included if debug mode is enabled
    "Searching for recent quantum computing developments",
    "Filtering academic and news sources",
    "Summarizing key advancements"
  ]
}

Tool Endpoints

The following endpoints allow you to manage and use tools that can be integrated with your AI agents.

List Available Tools

Returns a list of all tools available for integration with agents.

Endpoint

GET /tools

Query Parameters

  • category: Filter by tool category
  • limit: Maximum number of results
  • offset: Pagination offset

Example Response

{
  "data": [
    {
      "id": "tool_search",
      "name": "Web Search",
      "description": "Search the web for information",
      "category": "information_retrieval",
      "parameters": [
        {
          "name": "query",
          "type": "string",
          "required": true,
          "description": "Search query"
        },
        {
          "name": "limit",
          "type": "integer",
          "required": false,
          "description": "Maximum number of results",
          "default": 5
        }
      ]
    },
    {
      "id": "tool_calculator",
      "name": "Calculator",
      "description": "Perform mathematical calculations",
      "category": "utility",
      "parameters": [
        {
          "name": "expression",
          "type": "string",
          "required": true,
          "description": "Mathematical expression to evaluate"
        }
      ]
    }
  ],
  "meta": {
    "total": 15,
    "limit": 10,
    "offset": 0
  }
}

Get Tool Details

Retrieves detailed information about a specific tool.

Endpoint

GET /tools/{tool_id}

Path Parameters

  • tool_id: Unique identifier for the tool

Example Response

{
  "id": "tool_search",
  "name": "Web Search",
  "description": "Search the web for information",
  "category": "information_retrieval",
  "version": "1.2.0",
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2025-03-20T14:30:00Z",
  "parameters": [
    {
      "name": "query",
      "type": "string",
      "required": true,
      "description": "Search query"
    },
    {
      "name": "limit",
      "type": "integer",
      "required": false,
      "description": "Maximum number of results",
      "default": 5,
      "minimum": 1,
      "maximum": 20
    },
    {
      "name": "filter",
      "type": "string",
      "required": false,
      "description": "Filter results by type",
      "enum": ["news", "academic", "general"]
    }
  ],
  "examples": [
    {
      "description": "Basic search",
      "request": {
        "query": "climate change solutions",
        "limit": 3
      },
      "response": "[Example response data...]"
    }
  ],
  "usage_limits": {
    "requests_per_minute": 30,
    "requests_per_day": 5000
  },
  "documentation_url": "https://docs.agentopia.org/tools/search"
}

Execute Tool

Executes a tool with the provided parameters.

Endpoint

POST /tools/{tool_id}/execute

Path Parameters

  • tool_id: Unique identifier for the tool

Example Request (Web Search)

{
  "parameters": {
    "query": "latest advancements in renewable energy",
    "limit": 3,
    "filter": "news"
  }
}

Example Response

{
  "results": [
    {
      "title": "Breakthrough in Solar Panel Efficiency Reaches 32%",
      "url": "https://example.com/solar-breakthrough",
      "snippet": "Researchers have developed a new type of solar panel that achieves 32% efficiency, a significant improvement over current commercial panels...",
      "published_date": "2025-05-20T08:45:00Z",
      "source": "Tech Energy News"
    },
    {
      "title": "Offshore Wind Farm Capacity Doubles in North Sea",
      "url": "https://example.com/wind-farm-expansion",
      "snippet": "The latest expansion of wind farms in the North Sea has doubled the region's capacity, now providing clean energy to over 10 million homes...",
      "published_date": "2025-05-18T14:20:00Z",
      "source": "Green Energy Report"
    },
    {
      "title": "New Battery Technology Extends EV Range by 50%",
      "url": "https://example.com/ev-battery-advance",
      "snippet": "A new solid-state battery technology promises to extend electric vehicle range by up to 50% while reducing charging time to under 15 minutes...",
      "published_date": "2025-05-15T11:30:00Z",
      "source": "Future Transport Daily"
    }
  ],
  "meta": {
    "total_results": 1243,
    "execution_time": 0.82,  // seconds
    "query": "latest advancements in renewable energy"
  }
}

Data Endpoints

The following endpoints allow you to manage data sources and knowledge bases for your AI agents.

List Data Sources

Returns a list of all data sources associated with your account.

Endpoint

GET /data/sources

Query Parameters

  • type: Filter by source type
  • limit: Maximum number of results
  • offset: Pagination offset

Example Response

{
  "data": [
    {
      "id": "src_123456789",
      "name": "Company Documentation",
      "type": "document_collection",
      "created_at": "2025-03-10T14:20:00Z",
      "document_count": 42,
      "status": "processed"
    },
    {
      "id": "src_987654321",
      "name": "Product Database",
      "type": "database",
      "created_at": "2025-02-15T09:45:00Z",
      "record_count": 1250,
      "status": "processed"
    }
  ],
  "meta": {
    "total": 2,
    "limit": 20,
    "offset": 0
  }
}

Create Data Source

Creates a new data source for use with your agents.

Endpoint

POST /data/sources

Request Body

  • name: Source name (required)
  • type: Source type (required)
  • config: Source configuration

Example Request (Document Collection)

{
  "name": "Research Papers",
  "type": "document_collection",
  "config": {
    "chunk_size": 1000,
    "chunk_overlap": 200,
    "embedding_model": "text-embedding-3-large"
  }
}

Example Response

{
  "id": "src_567890123",
  "name": "Research Papers",
  "type": "document_collection",
  "created_at": "2025-05-29T22:50:00Z",
  "status": "created",
  "config": {
    "chunk_size": 1000,
    "chunk_overlap": 200,
    "embedding_model": "text-embedding-3-large"
  },
  "upload_url": "https://upload.agentopia.org/data/sources/src_567890123/documents"
}

Query Data Source

Performs a semantic search query against a data source.

Endpoint

POST /data/sources/{source_id}/query

Path Parameters

  • source_id: Unique identifier for the data source

Example Request

{
  "query": "What are the environmental impacts of quantum computing?",
  "limit": 5,
  "similarity_threshold": 0.75
}

Example Response

{
  "results": [
    {
      "document_id": "doc_123456789",
      "chunk_id": "chunk_123456789_5",
      "similarity_score": 0.92,
      "content": "Quantum computing data centers may consume significantly less energy compared to classical supercomputers for certain computational tasks. A 2024 study by the University of California estimated that quantum computers could reduce energy consumption by up to 90% for specific algorithms like Shor's algorithm and quantum simulation...",
      "metadata": {
        "title": "Quantum Computing: Environmental Considerations",
        "author": "Zhang et al.",
        "year": 2024,
        "page": 42
      }
    },
    {
      "document_id": "doc_987654321",
      "chunk_id": "chunk_987654321_12",
      "similarity_score": 0.87,
      "content": "While quantum computers themselves may be more energy-efficient for certain calculations, the cooling requirements for maintaining quantum coherence present significant energy challenges. Current quantum systems require cooling to near absolute zero temperatures, which demands substantial energy resources...",
      "metadata": {
        "title": "The Future of Sustainable Computing",
        "author": "Johnson et al.",
        "year": 2023,
        "page": 128
      }
    }
  ],
  "meta": {
    "total_matches": 8,
    "returned": 2,
    "query_time_ms": 125
  }
}

Webhooks

Webhooks allow your application to receive real-time notifications about events in the Agentopia ecosystem. This enables you to build event-driven integrations with your AI agents.

Available Events

Event Type Description
agent.created Triggered when a new agent is created
agent.updated Triggered when an agent is updated
agent.deleted Triggered when an agent is deleted
interaction.completed Triggered when an agent interaction is completed
data.processed Triggered when a data source is fully processed

Setting Up Webhooks

To register a webhook, use the following endpoint:

POST /webhooks

Example Request

{
  "url": "https://example.com/webhook",
  "events": ["agent.created", "interaction.completed"],
  "secret": "whsec_abcdefghijklmnopqrstuvwxyz",  // Optional, but recommended
  "description": "Notification webhook for my application"
}

Webhook Payload Format

All webhook payloads follow this general structure:

{
  "id": "evt_123456789",
  "type": "agent.created",
  "created_at": "2025-05-29T22:55:00Z",
  "data": {  // Event-specific data
    "agent": {
      "id": "agt_123456789",
      "name": "Research Buddy",
      "category": "regular_single"
    }
  }
}

Security

To verify that webhooks are sent by Agentopia, we include a signature in the X-Agentopia-Signature header. The signature is an HMAC SHA-256 hash of the payload, using your webhook secret as the key. 

// Example verification in Node.js
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

SDKs & Client Libraries

To simplify integration with the Agentopia API, we provide official client libraries for several programming languages.

Python

Our Python SDK provides a convenient way to interact with the Agentopia API.

Installation

pip install agentopia

Example Usage

import agentopia

# Initialize the client
client = agentopia.Client(api_key="YOUR_API_KEY")

# List agents
agents = client.agents.list(limit=5)

# Create an agent
new_agent = client.agents.create(
    name="Data Analyst",
    description="AI assistant for data analysis",
    category="regular_single",
    config={
        "model": "gpt-4",
        "temperature": 0.7
    }
)

# Interact with an agent
response = client.agents.interact(
    agent_id=new_agent.id,
    message="What insights can you find in this dataset?",
    context={
        "dataset_url": "https://example.com/data.csv"
    }
)

View on GitHub | Documentation

JavaScript

Our JavaScript SDK works in both Node.js and browser environments.

Installation

npm install agentopia

Example Usage

import { Agentopia } from 'agentopia';

// Initialize the client
const agentopia = new Agentopia({
  apiKey: 'YOUR_API_KEY'
});

// Create an agent
async function createAgent() {
  const agent = await agentopia.agents.create({
    name: 'Research Assistant',
    description: 'Helps with academic research',
    category: 'regular_single',
    config: {
      model: 'gpt-4',
      tools: ['search', 'document_retrieval']
    }
  });
  
  console.log('Agent created:', agent.id);
  return agent;
}

// Interact with an agent
async function interactWithAgent(agentId) {
  const response = await agentopia.agents.interact({
    agentId,
    message: 'Summarize the latest research on climate change',
    conversationId: 'conv_123456789' // Optional
  });
  
  console.log('Agent response:', response.response);
}

View on GitHub | Documentation

Additional Libraries

We also provide libraries for the following languages:

If you need a library for a language not listed here, please open an issue on our GitHub repository.

Error Handling

The Agentopia API uses standard HTTP status codes to indicate the success or failure of an API request. Here's how to handle errors when using our API.

HTTP Status Codes

Status Code Description
200 - OK The request was successful
201 - Created The resource was successfully created
400 - Bad Request The request was invalid or could not be understood
401 - Unauthorized Authentication failed or was not provided
403 - Forbidden The authenticated user doesn't have permission
404 - Not Found The requested resource was not found
429 - Too Many Requests Rate limit exceeded
500 - Internal Server Error An error occurred on the server

Error Response Format

When an error occurs, the API returns a JSON object with the following structure:

{
  "error": {
    "type": "invalid_request_error",
    "message": "The agent ID is invalid or does not exist",
    "code": "agent_not_found",
    "param": "agent_id",
    "request_id": "req_123456789"
  }
}

Common Error Codes

Error Code Description
invalid_request_error The request was invalid or malformed
authentication_error Authentication failed or was not provided
permission_error The authenticated user doesn't have permission
resource_not_found The requested resource was not found
rate_limit_error Rate limit exceeded
server_error An error occurred on the server

Error Handling Best Practices

  • Always check the HTTP status code of API responses
  • Parse the error response to get detailed information
  • Implement retry logic with exponential backoff for rate limit errors
  • Log the request_id for troubleshooting
  • Handle different error types appropriately in your application
// Example error handling in JavaScript
async function createAgent() {
  try {
    const agent = await agentopia.agents.create({
      name: 'Research Assistant',
      category: 'regular_single'
    });
    return agent;
  } catch (error) {
    if (error.status === 429) {
      // Handle rate limiting
      console.log(`Rate limited. Retry after ${error.headers['retry-after']} seconds`);
      // Implement retry logic
    } else if (error.status === 400) {
      // Handle validation errors
      console.error(`Validation error: ${error.data.error.message}`);
    } else {
      // Handle other errors
      console.error(`Error: ${error.status} - ${error.data.error.message}`);
      console.error(`Request ID: ${error.data.error.request_id}`);
    }
    throw error;
  }
}