Instances API Reference

The Instances API manages running deployments of your agent blueprints. Each instance represents an isolated, running container with its own environment, resources, and URL.

Instance Resource

Instance Object

{
  "id": "instance-uuid",
  "name": "market-tracker-prod",
  "agent_id": "agent-uuid", 
  "build_id": "build-uuid",
  "organization_id": "org-uuid",
  "user_id": "user-uuid",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "status": "running",
  "deployment": {
    "url": "https://instance-abc123.agenthub.app",
    "resource_name": "instance-abc123",
    "deployment_type": "HTTP_LONG_RUNNING", 
    "replicas": 1,
    "restart_count": 0
  },
  "config": {
    "port": 8080,
    "health_path": "/health",
    "long_running": true,
    "enable_http": true,
    "stdin_enabled": false
  },
  "resources": {
    "cpu": "0.5",
    "memory": "512Mi",
    "cpu_limit": "1.0", 
    "memory_limit": "1Gi"
  },
  "env_vars": {
    "API_KEY": "***REDACTED***",
    "TARGET_QUERY": "renewable energy stocks",
    "LOG_LEVEL": "INFO"
  },
  "metrics": {
    "uptime_seconds": 86400,
    "requests_total": 1250,
    "cpu_usage_percent": 25.5,
    "memory_usage_mb": 384
  }
}

Instance Fields

Instance Status Values

List Instances

Retrieve instances for your organization.

Request

GET /instances/by_org_id/{org_id}

Path Parameters

Query Parameters

Response

{
  "data": [
    {
      "id": "instance-1",
      "name": "market-tracker-prod",
      "agent_id": "agent-uuid",
      "status": "running",
      "deployment": {
        "url": "https://instance-abc123.agenthub.app",
        "replicas": 1
      },
      "created_at": "2024-01-15T10:30:00Z",
      "metrics": {
        "uptime_seconds": 3600,
        "cpu_usage_percent": 15.2
      }
    }
  ],
  "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/instances/by_org_id/org-uuid?status=running"

JavaScript

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

Get Instance

Retrieve a specific instance with complete details.

Request

GET /instances/{instance_id}

Path Parameters

Response

Returns the complete instance object including metrics and configuration.

Examples

cURL

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

Create Instance

Deploy a new instance from an agent blueprint and build.

Request

POST /instances

Request Body

{
  "name": "my-production-instance",
  "agent_id": "agent-uuid",
  "build_id": "build-uuid", 
  "organization_id": "org-uuid",
  "config": {
    "replicas": 2,
    "long_running": true,
    "enable_http": true
  },
  "resources": {
    "cpu": "1.0",
    "memory": "1Gi",
    "cpu_limit": "2.0",
    "memory_limit": "2Gi"
  },
  "env_vars": {
    "API_KEY": "your-secret-api-key",
    "TARGET_QUERY": "artificial intelligence stocks",
    "LOG_LEVEL": "DEBUG"
  }
}

Required Fields

Optional Fields

Response

Returns the created instance object. The instance will initially have status starting.

Examples

cURL

curl -X POST https://prod-agent-hosting-api.useagenthub.com/instances \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "trading-bot-v1",
    "agent_id": "agent-uuid",
    "build_id": "build-uuid",
    "organization_id": "org-uuid",
    "env_vars": {
      "API_KEY": "secret-key-123",
      "TRADING_MODE": "live"
    }
  }'

JavaScript

const instance = await fetch('https://prod-agent-hosting-api.useagenthub.com/instances', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'trading-bot-v1',
    agent_id: 'agent-uuid',
    build_id: 'build-uuid',
    organization_id: 'org-uuid',
    env_vars: {
      API_KEY: 'secret-key-123',
      TRADING_MODE: 'live'
    }
  })
});

Update Instance

Update a running instance's configuration.

Request

PUT /instances/{instance_id}

Path Parameters

Request Body

Only include fields you want to update:

{
  "name": "updated-instance-name",
  "config": {
    "replicas": 3
  },
  "resources": {
    "memory": "2Gi"
  },
  "env_vars": {
    "LOG_LEVEL": "ERROR",
    "NEW_SETTING": "value"
  }
}

Note: Updating certain fields (resources, env_vars) will trigger an instance restart.

Response

Returns the updated instance object.

Examples

cURL

curl -X PUT https://prod-agent-hosting-api.useagenthub.com/instances/instance-uuid \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "replicas": 2
    },
    "env_vars": {
      "LOG_LEVEL": "DEBUG"
    }
  }'

Delete Instance

Stop and remove an instance permanently.

Request

DELETE /instances/{instance_id}

Path Parameters

Query Parameters

Response

Returns 204 No Content on successful deletion.

Examples

cURL

# Graceful shutdown
curl -X DELETE https://prod-agent-hosting-api.useagenthub.com/instances/instance-uuid \
  -H "Authorization: Bearer your-api-key"

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

Get Instance Status

Get detailed deployment status and health information.

Request

GET /instances/status/{org_id}/{instance_id}

Path Parameters

Response

{
  "status": "RUNNING",
  "created_at": 1642271400,
  "replicas": 2,
  "restart_count": 1,
  "health_checks": {
    "last_check": "2024-01-15T10:35:00Z",
    "status": "healthy",
    "response_time_ms": 45
  },
  "resource_usage": {
    "cpu_percent": 25.5,
    "memory_mb": 384,
    "network_rx_bytes": 1024000,
    "network_tx_bytes": 512000
  }
}

Status Values

Examples

cURL

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

Execute Commands (Interactive Instances)

Execute commands inside a running instance with stdin support.

Request

POST /instances/{org_id}/{instance_id}/exec

Path Parameters

Request Body

["python", "-c", "print('Hello from instance!')"]

Response

Returns command output as plain text:

Hello from instance!

Examples

cURL

curl -X POST https://prod-agent-hosting-api.useagenthub.com/instances/org-uuid/instance-uuid/exec \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '["ls", "-la"]'

JavaScript

const response = await fetch(
  'https://prod-agent-hosting-api.useagenthub.com/instances/org-uuid/instance-uuid/exec',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(['python', '--version'])
  }
);

const output = await response.text();
console.log(output); // "Python 3.11.5"

Send Stdin Input

Send input to instances that support stdin interaction.

Request

POST /instances/{org_id}/{instance_id}/stdin

Request Body

{
  "input": "user input text\n"
}

Response

Returns any output generated by the stdin input.

Examples

Interactive Chat Agent

# Send user message to chat agent
curl -X POST https://prod-agent-hosting-api.useagenthub.com/instances/org-uuid/instance-uuid/stdin \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"input": "What is the weather like today?\n"}'

Instance Logs

Get Historical Logs

GET /instances/{org_id}/{instance_id}/logs

Query Parameters

Response

Historical logs:

{
  "logs": [
    {
      "timestamp": "2024-01-15T10:30:00Z",
      "level": "INFO",
      "message": "Agent started successfully"
    },
    {
      "timestamp": "2024-01-15T10:30:15Z",
      "level": "INFO", 
      "message": "Processing market data..."
    }
  ]
}

Live logs (SSE):

data: {"timestamp": "2024-01-15T10:30:30Z", "level": "INFO", "message": "Generated 5 trading signals"}

data: {"timestamp": "2024-01-15T10:30:45Z", "level": "DEBUG", "message": "API response time: 150ms"}

Examples

Get Recent Logs

curl -H "Authorization: Bearer your-api-key" \
  "https://prod-agent-hosting-api.useagenthub.com/instances/org-uuid/instance-uuid/logs?lines=50"

Stream Live Logs

const eventSource = new EventSource(
  'https://prod-agent-hosting-api.useagenthub.com/instances/org-uuid/instance-uuid/logs?follow=true',
  {
    headers: { 'Authorization': 'Bearer your-api-key' }
  }
);

eventSource.onmessage = (event) => {
  const logEntry = JSON.parse(event.data);
  console.log(`[${logEntry.level}] ${logEntry.message}`);
};

Error Responses

Common Errors

Instance Not Found (404)

{
  "error": {
    "code": "INSTANCE_NOT_FOUND",
    "message": "Instance with ID 'instance-uuid' not found"
  }
}

Instance Not Running (409)

{
  "error": {
    "code": "INSTANCE_NOT_RUNNING",
    "message": "Cannot execute command on stopped instance",
    "current_status": "stopped"
  }
}

Resource Limits Exceeded (422)

{
  "error": {
    "code": "RESOURCE_LIMIT_EXCEEDED",
    "message": "Organization has reached maximum instance count",
    "details": {
      "current_instances": 50,
      "max_instances": 50
    }
  }
}

Build Not Ready (409)

{
  "error": {
    "code": "BUILD_NOT_READY",
    "message": "Cannot create instance from incomplete build",
    "build_status": "building"
  }
}

Best Practices

Instance Configuration

Resource Planning:

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

Environment Variables:

{
  "env_vars": {
    "API_KEY": "actual-secret-value", // OK in instance creation
    "LOG_LEVEL": "INFO",             // Use INFO for production
    "TIMEOUT": "30",                 // Always string values
    "CACHE_SIZE": "1000"
  }
}

Scaling Strategies

Horizontal Scaling:

{
  "config": {
    "replicas": 3,              // Multiple replicas for availability
    "enable_http": true,        // Load balancer across replicas
    "health_path": "/health"    // Enable health checks
  }
}

Vertical Scaling:

{
  "resources": {
    "cpu": "2.0",
    "memory": "4Gi",
    "cpu_limit": "4.0",         // Higher limits for burst workloads
    "memory_limit": "8Gi"
  }
}

---

Next: Builds API Reference →