REST API

OpenAPI specification and endpoint documentation for the AIP backend.

📚 Overview

This section contains the complete REST API reference for the AI Agent Platform. The platform consists of two main services:

Backend API - For managing agents, tools, MCPs, and language models
Runner API - For executing agents and monitoring their execution

Note: The Backend API documentation is maintained in the ai-agent-platform-backend repository and auto-generated from the OpenAPI specification. For the most up-to-date Backend API docs, visit the live endpoints at https://aip.gdplabs.id/docs.

🔄 Auto-Generation

This documentation is automatically generated from the OpenAPI specification and kept in sync with the backend code. The actual OpenAPI specification is hosted at the backend API endpoint.

Live API Documentation

For the most up-to-date API documentation, refer to:

Backend API Production: https://aip.gdplabs.id/docs
Backend API Development: Your local backend URL (e.g., http://localhost:8000/docs)
Runner API: The runner service typically runs on a different port/domain

📋 API Endpoints

The AIP platform consists of two main services, each with their own API endpoints:

Backend API (`https://aip.gdplabs.id`)

The main backend service for managing agents, tools, MCPs, and language models.

Runner API (`https://aip-runner.gdplabs.id`)

The execution service for running agents and monitoring their execution.

🔧 Backend API Endpoints

The Backend API provides the following endpoint categories:

Authentication

X-API-Key header - API key authentication (required for all endpoints)

Agents

GET /agents - List all agents with optional filtering
POST /agents - Create new agent
GET /agents/{agent_id} - Get agent details
PUT /agents/{agent_id} - Update agent (full replacement)
DELETE /agents/{agent_id} - Soft delete agent
POST /agents/{agent_id}/run - Run agent with message and optional file uploads
POST /agents/{agent_id}/restore - Restore soft-deleted agent

Tools

GET /tools - List all tools with optional type filtering
POST /tools - Create new tool entry
GET /tools/{id} - Get tool details by ID
PUT /tools/{id} - Update tool metadata
DELETE /tools/{id} - Delete tool
POST /tools/upload - Upload and register new tool plugin
PUT /tools/{tool_id}/upload - Update tool plugin via file upload
GET /tools/{tool_id}/script - Get tool script content
POST /tools/{id}/restore - Restore soft-deleted tool

MCPs

GET /mcps - List all MCPs (optionally include tools)
POST /mcps - Create new MCP
GET /mcps/{mcp_id} - Get MCP details (optionally include tools)
PUT /mcps/{mcp_id} - Update MCP
DELETE /mcps/{mcp_id} - Soft delete MCP
POST /mcps/{mcp_id}/restore - Restore soft-deleted MCP
GET /mcps/{mcp_id}/tools - List tools from MCP
POST /mcps/connect - Test MCP connection
POST /mcps/connect/tools - Fetch tools from MCP configuration

Language Models

GET /language-models - List all language models
POST /language-models - Create new language model
GET /language-models/{lm_id} - Get language model details
PUT /language-models/{lm_id} - Update language model
DELETE /language-models/{lm_id} - Delete language model

Health & Status

GET /health-check - Health check endpoint
GET /health-check/database - Database health check

🚀 Runner API Endpoints

The Runner API provides the following endpoint categories:

Agent Execution

POST /execute/a2a/stream/agent - Stream agent execution with lifecycle management
POST /execute/a2a/stream/celery/agent - Stream agent execution via Celery
GET /execute/a2a/agents/list - List available agents for execution
GET /execute/a2a/agents/health - Check agent health status

Tool Validation

POST /tools/validation - Validate Python script content for custom tools

Monitoring & Execution Tracking

GET /monitoring/tasks/{task_id} - Get Celery task status
GET /monitoring/agent/{agent_id}/executions - Get recent executions for an agent
GET /monitoring/executions/recent - Get recent executions across all agents
DELETE /monitoring/tasks/{task_id} - Cancel/delete a monitoring task

Health & Status

GET /health-check - Basic health check
GET /health-check/detailed - Detailed health check with service status

🔐 Authentication

The API uses API key authentication via the X-API-Key header:

# Include in request headers
X-API-Key: <your-api-key>

# Example request
curl -H "X-API-Key: $API_KEY" \
     https://aip.gdplabs.id/agents

📊 Request/Response Formats

Standard Response Format

{
  "success": true,
  "data": {
    // Response data
  },
  "message": "Operation successful",
  "timestamp": "2024-01-01T00:00:00Z"
}

Error Response Format

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": {
      "field": "name",
      "issue": "Required field missing"
    }
  },
  "timestamp": "2024-01-01T00:00:00Z"
}

🚨 Error Codes

Code

HTTP Status

Description

AUTHENTICATION_FAILED

401

Invalid or expired token

AUTHORIZATION_FAILED

403

Insufficient permissions

RESOURCE_NOT_FOUND

404

Requested resource not found

VALIDATION_ERROR

422

Invalid request data

RATE_LIMIT_EXCEEDED

429

Too many requests

INTERNAL_ERROR

500

Server error

📝 Examples

Create Agent

curl -X POST https://aip.gdplabs.id/agents \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "math-tutor",
    "instruction": "You are a math tutor",
    "model": "gpt-4"
  }'

Run Agent

curl -X POST https://aip.gdplabs.id/agents/agent-123/run \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What is 2 + 2?",
    "timeout": 60
  }'

Upload File with Agent Run

curl -X POST https://aip.gdplabs.id/agents/agent-123/run \
  -H "X-API-Key: $API_KEY" \
  -F "message=Analyze this document" \
  -F "files=@document.pdf"

🔧 SDK Integration

The Python SDK automatically handles:

Authentication: Token management and refresh
Request Formatting: Proper headers and data serialization
Response Parsing: Automatic JSON parsing and error handling
File Uploads: Multipart form data for file uploads
Retry Logic: Automatic retries for transient failures

from glaip_sdk import Client

client = Client()
# SDK handles all HTTP details automatically
agent = client.create_agent(name="test", instruction="Be helpful")

📈 Rate Limiting

The API implements rate limiting to ensure fair usage:

Default Limit: 100 requests per minute per API key
Burst Allowance: Up to 200 requests in short bursts
Headers: Rate limit information included in response headers

# Response headers include rate limit info
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Python SDK API - Python SDK reference
CLI Commands - Command-line interface
Quick Start - Get started guide

← Back to Reference

REST API documentation is automatically generated from the OpenAPI specification and kept up-to-date with the backend code.

PreviousCLI Commands NextConcepts

📚 Overview

🔄 Auto-Generation

Live API Documentation

📋 API Endpoints

Backend API (https://aip.gdplabs.id)

Runner API (https://aip-runner.gdplabs.id)

🔧 Backend API Endpoints

Authentication

Agents

Tools

MCPs

Language Models

Health & Status

🚀 Runner API Endpoints

Agent Execution

Tool Validation

Monitoring & Execution Tracking

Health & Status

🔐 Authentication

📊 Request/Response Formats

Standard Response Format

Error Response Format

🚨 Error Codes

📝 Examples

Create Agent

Run Agent

Upload File with Agent Run

🔧 SDK Integration

📈 Rate Limiting

🔗 Related Documentation

🔗 Navigation

Backend API (`https://aip.gdplabs.id`)

Runner API (`https://aip-runner.gdplabs.id`)