AgentHub API Overview

The AgentHub API provides programmatic access to all platform functionality, enabling you to integrate agent management into your applications, automate deployments, and build custom workflows.

Base URLs

Production API: https://prod-agent-hosting-api.useagenthub.com
Frontend: https://www.useagenthub.com
Interactive Documentation: OpenAPI UI

API Design Principles

RESTful Architecture

Resource-based URLs - /agents, /instances, /builds
HTTP methods - GET (read), POST (create), PUT (update), DELETE (remove)
Standard status codes - 200 (success), 404 (not found), 403 (forbidden)
JSON payloads - All requests and responses use JSON format

Consistent Response Format

All API responses follow a consistent structure:

{
  "id": "uuid-string",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "data": { ... },
  "status": "active"
}

Error Handling

Error responses include helpful details:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid environment variable format",
    "details": {
      "field": "env.API_KEY",
      "reason": "Missing required environment variable"
    }
  }
}

Authentication

AgentHub supports multiple authentication methods:

1. Session Authentication (Web UI)

Used by the web interface after GitHub OAuth login:

// Automatically handled by frontend
fetch('/api/agents', {
  credentials: 'include'  // Includes session cookie
})

2. Bearer Token Authentication (API)

For programmatic access using API keys:

curl -H "Authorization: Bearer your-api-key" \
  https://prod-agent-hosting-api.useagenthub.com/agents

3. GitHub OAuth (Third-party Apps)

For applications integrating on behalf of users:

# OAuth flow - see authentication guide for details
curl -H "Authorization: Bearer github-oauth-token" \
  https://prod-agent-hosting-api.useagenthub.com/agents

Rate Limiting

API requests are rate limited to ensure fair usage:

Authenticated requests: 1,000 requests per hour
Unauthenticated requests: 100 requests per hour
Real-time endpoints: 10 requests per minute

Rate limit headers are included in responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642271400

API Versioning

The API uses URL-based versioning:

Current version: v1 (default)
Future versions: v2, v3, etc.

# Explicit version
curl https://prod-agent-hosting-api.useagenthub.com/v1/agents

# Default to latest stable
curl https://prod-agent-hosting-api.useagenthub.com/agents

Core Resources

Agents

Manage agent blueprints and templates:

GET    /agents              # List all agents
POST   /agents              # Create new agent
GET    /agents/{id}         # Get agent details
PUT    /agents/{id}         # Update agent
DELETE /agents/{id}         # Delete agent

Instances

Control running agent instances:

GET    /instances           # List instances
POST   /instances           # Deploy new instance
GET    /instances/{id}      # Get instance status
PUT    /instances/{id}      # Update instance
DELETE /instances/{id}      # Stop instance

Builds

Manage container builds:

GET    /builds              # List builds
POST   /builds              # Trigger new build
GET    /builds/{id}         # Get build status
GET    /builds/{id}/logs    # Stream build logs

Organizations

Team and organization management:

GET    /organizations       # List organizations
POST   /organizations       # Create organization
GET    /organizations/{id}  # Get organization
PUT    /organizations/{id}  # Update organization

Real-time Features

Server-Sent Events (SSE)

Get real-time updates for long-running operations:

// Stream build logs
const eventSource = new EventSource(
  'https://prod-agent-hosting-api.useagenthub.com/builds/123/logs'
);

eventSource.onmessage = function(event) {
  const logData = JSON.parse(event.data);
  console.log(logData.message);
};

Webhooks

Configure webhooks for event notifications:

{
  "webhook_url": "https://your-app.com/webhook",
  "events": [
    "instance.created",
    "instance.started",
    "build.completed",
    "deployment.failed"
  ]
}

Pagination

List endpoints support cursor-based pagination:

# First page (default: 50 items)
curl "https://prod-agent-hosting-api.useagenthub.com/agents?limit=20"

# Next page using cursor
curl "https://prod-agent-hosting-api.useagenthub.com/agents?limit=20&cursor=eyJpZCI6InNvbWUtaWQi"

Response format:

{
  "data": [...],
  "pagination": {
    "limit": 20,
    "has_more": true,
    "next_cursor": "eyJpZCI6InNvbWUtaWQi"
  }
}

Content Types

Request Headers

Content-Type: application/json
Authorization: Bearer your-api-key
User-Agent: your-app/1.0.0

Response Headers

Content-Type: application/json
X-Request-ID: req-123456789
X-Response-Time: 45ms

API Libraries and SDKs

JavaScript/TypeScript

npm install @agenthub/sdk

import { AgentHubClient } from '@agenthub/sdk';

const client = new AgentHubClient({
  apiKey: 'your-api-key',
  baseURL: 'https://prod-agent-hosting-api.useagenthub.com'
});

const agents = await client.agents.list();

Python

pip install agenthub-python

from agenthub import AgentHubClient

client = AgentHubClient(
    api_key='your-api-key',
    base_url='https://prod-agent-hosting-api.useagenthub.com'
)

agents = client.agents.list()

cURL Examples

Throughout this documentation, we provide cURL examples for direct HTTP access:

# List agents with authentication
curl -H "Authorization: Bearer your-api-key" \
     -H "Content-Type: application/json" \
     https://prod-agent-hosting-api.useagenthub.com/agents

Getting Started

Authentication - Set up API keys and authentication
Agents API - Create and manage agent blueprints
Instances API - Deploy and control running instances
Builds API - Manage container builds and deployments

Interactive Documentation

Explore the complete API using our interactive OpenAPI documentation:

🔗 Open Interactive API Docs →

The interactive docs include:

Try it out - Execute API calls directly from the browser
Complete schemas - Detailed request/response models
Authentication testing - Test your API keys
Code generation - Generate client code in multiple languages

Ready to start building? Check out the Authentication Guide →