Agents API Reference

The Agents API allows you to create, manage, and configure agent blueprints. Agents represent your published templates that others can deploy as instances.

Agent Resource

Agent Object

{
  "id": "agent-uuid",
  "name": "market-news-agent",
  "summary": "AI agent that analyzes market news and generates trading insights",
  "github_repo": "username/market-news-agent",
  "github_branch": "main",
  "organization_id": "org-uuid",
  "user_id": "user-uuid",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "config": {
    "dockerfile_path": "./Dockerfile",
    "working_directory": "/app",
    "port": 8080,
    "health_path": "/health",
    "long_running": true,
    "enable_http": false,
    "stdin_enabled": false
  },
  "resources": {
    "cpu": "0.5",
    "memory": "512Mi",
    "cpu_limit": "1.0",
    "memory_limit": "1Gi"
  },
  "env_vars": {
    "TARGET_QUERY": "",
    "GEMINI_API_KEY": "",
    "LOG_LEVEL": "INFO"
  },
  "build_count": 3,
  "instance_count": 12,
  "status": "active"
}

Agent Fields

Field	Type	Description
`id`	string	Unique agent identifier
`name`	string	Agent display name
`summary`	string	Brief description of agent functionality
`github_repo`	string	Source repository (format: `owner/repo`)
`github_branch`	string	Default deployment branch
`organization_id`	string	Organization that owns this agent
`user_id`	string	User who created this agent
`config.dockerfile_path`	string	Path to Dockerfile in repository
`config.port`	integer	Port the agent listens on
`config.long_running`	boolean	Whether agent runs continuously
`config.enable_http`	boolean	Whether to expose HTTP endpoint
`resources.cpu`	string	CPU allocation (e.g., "0.5", "1.0")
`resources.memory`	string	Memory allocation (e.g., "512Mi", "1Gi")
`env_vars`	object	Environment variable definitions
`build_count`	integer	Number of builds created
`instance_count`	integer	Number of active instances

List Agents

Retrieve agents for your organization.

Request

GET /agents/by_org_id/{org_id}

Path Parameters

Parameter	Type	Required	Description
`org_id`	string	Yes	Organization ID

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	50	Number of agents to return (1-100)
`cursor`	string	-	Pagination cursor for next page
`status`	string	all	Filter by status: `active`, `archived`, `all`

Response

{
  "data": [
    {
      "id": "agent-1",
      "name": "market-news-agent",
      "summary": "Market analysis agent",
      "github_repo": "user/market-agent",
      "created_at": "2024-01-15T10:30:00Z",
      "build_count": 5,
      "instance_count": 23
    }
  ],
  "pagination": {
    "limit": 50,
    "has_more": false,
    "next_cursor": null
  }
}

Examples

cURL

curl -H "Authorization: Bearer your-api-key" \
  "https://prod-agent-hosting-api.useagenthub.com/agents/by_org_id/org-uuid?limit=20"

JavaScript

const response = await fetch(
  'https://prod-agent-hosting-api.useagenthub.com/agents/by_org_id/org-uuid?limit=20',
  {
    headers: {
      'Authorization': 'Bearer your-api-key'
    }
  }
);
const agents = await response.json();

Python

import requests

response = requests.get(
    'https://prod-agent-hosting-api.useagenthub.com/agents/by_org_id/org-uuid',
    headers={'Authorization': 'Bearer your-api-key'},
    params={'limit': 20}
)
agents = response.json()

Get Agent

Retrieve a specific agent by ID.

Request

GET /agents/{agent_id}

Path Parameters

Parameter	Type	Required	Description
`agent_id`	string	Yes	Agent ID

Response

Returns the complete agent object with all configuration details.

Examples

cURL

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

JavaScript

const response = await fetch(
  'https://prod-agent-hosting-api.useagenthub.com/agents/agent-uuid',
  {
    headers: { 'Authorization': 'Bearer your-api-key' }
  }
);
const agent = await response.json();

Create Agent

Create a new agent blueprint from a GitHub repository.

Request

POST /agents

Request Body

{
  "name": "my-trading-bot",
  "summary": "Automated trading bot with risk management",
  "github_repo": "username/trading-bot",
  "github_branch": "main",
  "organization_id": "org-uuid",
  "config": {
    "dockerfile_path": "./Dockerfile",
    "working_directory": "/app",
    "port": 8080,
    "long_running": true,
    "enable_http": false
  },
  "resources": {
    "cpu": "1.0",
    "memory": "1Gi",
    "cpu_limit": "2.0",
    "memory_limit": "2Gi"
  },
  "env_vars": {
    "API_KEY": "",
    "TRADING_MODE": "simulation",
    "RISK_LEVEL": "conservative"
  }
}

Required Fields

Field	Type	Description
`name`	string	Agent name (unique within organization)
`github_repo`	string	GitHub repository (format: owner/repo)
`organization_id`	string	Organization ID

Optional Fields

Field	Type	Default	Description
`summary`	string	""	Agent description
`github_branch`	string	"main"	Default branch
`config.*`	object	Auto-detected	Runtime configuration
`resources.*`	object	Standard limits	Resource allocation
`env_vars`	object	{}	Environment variables

Response

Returns the created agent object with generated ID.

Examples

cURL

curl -X POST https://prod-agent-hosting-api.useagenthub.com/agents \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-trading-bot",
    "github_repo": "username/trading-bot", 
    "organization_id": "org-uuid",
    "config": {
      "long_running": true
    },
    "env_vars": {
      "API_KEY": "",
      "TRADING_MODE": "simulation"
    }
  }'

JavaScript

const agent = await fetch('https://prod-agent-hosting-api.useagenthub.com/agents', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'my-trading-bot',
    github_repo: 'username/trading-bot',
    organization_id: 'org-uuid',
    config: {
      long_running: true
    },
    env_vars: {
      API_KEY: '',
      TRADING_MODE: 'simulation'
    }
  })
});

Update Agent

Update an existing agent's configuration.

Request

PUT /agents/{agent_id}

Path Parameters

Parameter	Type	Required	Description
`agent_id`	string	Yes	Agent ID

Request Body

Only include fields you want to update:

{
  "name": "updated-agent-name",
  "summary": "Updated description",
  "config": {
    "port": 8080,
    "long_running": false
  },
  "resources": {
    "memory": "2Gi"
  },
  "env_vars": {
    "NEW_VAR": "new-value"
  }
}

Response

Returns the updated agent object.

Examples

cURL

curl -X PUT https://prod-agent-hosting-api.useagenthub.com/agents/agent-uuid \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Updated agent description",
    "resources": {
      "memory": "2Gi"
    }
  }'

Delete Agent

Delete an agent blueprint and all associated resources.

Request

DELETE /agents/{agent_id}

Path Parameters

Parameter	Type	Required	Description
`agent_id`	string	Yes	Agent ID

Response

Returns deletion preview with impact analysis:

{
  "agent": {
    "id": "agent-uuid",
    "name": "agent-name"
  },
  "impact": {
    "builds_to_delete": 5,
    "active_instances": 12,
    "total_instances": 45
  },
  "warnings": [
    "This will stop 12 active instances",
    "All build history will be lost"
  ]
}

Force Delete

To actually delete (after reviewing the preview):

curl -X DELETE https://prod-agent-hosting-api.useagenthub.com/agents/agent-uuid?force=true \
  -H "Authorization: Bearer your-api-key"

Get Agents by GitHub Repository

Find all agents created from a specific GitHub repository.

Request

POST /agents/by_github_repo

Request Body

{
  "github_repo": "username/repository-name",
  "organization_id": "org-uuid"
}

Response

{
  "data": [
    {
      "id": "agent-uuid",
      "name": "agent-name",
      "github_branch": "main",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Examples

cURL

curl -X POST https://prod-agent-hosting-api.useagenthub.com/agents/by_github_repo \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "github_repo": "username/my-agent",
    "organization_id": "org-uuid"
  }'

Host Agent (Deploy from Repository)

Automatically create an agent from a GitHub repository using the auto-dockerizer.

Request

POST /agents/host

This endpoint combines agent creation and build triggering:

Creates agent blueprint from GitHub repo
Analyzes repository structure
Generates optimized Dockerfile
Triggers initial build
Returns real-time build logs via Server-Sent Events

Request Body

{
  "name": "auto-deployed-agent",
  "github_repo": "username/my-agent",
  "github_branch": "main", 
  "organization_id": "org-uuid"
}

Response

Returns Server-Sent Events stream with build progress:

data: {"type": "log", "message": "Cloning repository...", "timestamp": "2024-01-15T10:30:00Z"}

data: {"type": "log", "message": "Analyzing repository structure...", "timestamp": "2024-01-15T10:30:05Z"}

data: {"type": "log", "message": "Detected Python application with requirements.txt", "timestamp": "2024-01-15T10:30:08Z"}

data: {"type": "log", "message": "Generating optimized Dockerfile...", "timestamp": "2024-01-15T10:30:10Z"}

data: {"type": "success", "agent_id": "agent-uuid", "build_id": "build-uuid", "message": "Agent created and build started"}

Examples

JavaScript (SSE)

const eventSource = new EventSource(
  'https://prod-agent-hosting-api.useagenthub.com/agents/host',
  {
    headers: {
      'Authorization': 'Bearer your-api-key'
    }
  }
);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(`[${data.type}] ${data.message}`);
  
  if (data.type === 'success') {
    console.log(`Agent created: ${data.agent_id}`);
    eventSource.close();
  }
};

cURL (HTTP/2 for SSE support)

curl -X POST https://prod-agent-hosting-api.useagenthub.com/agents/host \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  --http2 \
  -d '{
    "name": "my-agent",
    "github_repo": "username/my-agent",
    "organization_id": "org-uuid"
  }'

Error Responses

Common Errors

Agent Not Found (404)

{
  "error": {
    "code": "AGENT_NOT_FOUND",
    "message": "Agent with ID 'agent-uuid' not found"
  }
}

Validation Error (400)

{
  "error": {
    "code": "VALIDATION_ERROR", 
    "message": "Invalid agent configuration",
    "details": {
      "field": "github_repo",
      "reason": "Repository format must be 'owner/repo'"
    }
  }
}

Permission Denied (403)

{
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "You don't have permission to modify this agent"
  }
}

Repository Access Error (422)

{
  "error": {
    "code": "REPOSITORY_ACCESS_ERROR",
    "message": "Cannot access GitHub repository 'username/repo'",
    "details": {
      "reason": "Repository is private or does not exist"
    }
  }
}

Best Practices

Agent Configuration

Resource Planning:

{
  "resources": {
    "cpu": "0.5",        // Conservative start
    "memory": "512Mi",   // Monitor actual usage
    "cpu_limit": "2.0",  // Allow burst capacity
    "memory_limit": "2Gi" // Prevent OOM kills
  }
}

Environment Variables:

{
  "env_vars": {
    "API_KEY": "",           // Always empty for security
    "LOG_LEVEL": "INFO",     // Provide sensible defaults
    "TIMEOUT_SECONDS": "30", // String values for all env vars
    "FEATURE_FLAGS": "experimental=false,debug=false"
  }
}

Next: Instances API Reference →

Documentation

Agents API

Agents API Reference

Agent Resource

Agent Object

Agent Fields

List Agents

Request

Path Parameters

Query Parameters

Response

Examples

cURL

JavaScript

Python

Get Agent

Request

Path Parameters

Response

Examples

cURL

JavaScript

Create Agent

Request

Request Body

Required Fields

Optional Fields

Response

Examples

cURL

JavaScript

Update Agent

Request

Path Parameters

Request Body

Response

Examples

cURL

Delete Agent

Request

Path Parameters

Response

Force Delete

Get Agents by GitHub Repository

Request

Request Body

Response

Examples

cURL

Host Agent (Deploy from Repository)

Request

Request Body

Response

Examples

JavaScript (SSE)

cURL (HTTP/2 for SSE support)

Error Responses

Common Errors

Agent Not Found (404)

Validation Error (400)

Permission Denied (403)

Repository Access Error (422)

Best Practices

Agent Configuration