Builds API Reference

The Builds API manages containerization and versioning of your agents. Each build represents a specific version of your agent's code compiled into an optimized container image ready for deployment.

Build Resource

Build Object

{
  "id": "build-uuid",
  "agent_id": "agent-uuid",
  "organization_id": "org-uuid",
  "name": "market-agent-v1.2.0",
  "version": "1.2.0",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:35:00Z",
  "status": "completed",
  "build_time_seconds": 300,
  "source": {
    "github_repo": "username/market-agent",
    "github_branch": "main",
    "commit_sha": "abc123def456",
    "commit_url": "https://github.com/username/market-agent/commit/abc123def456"
  },
  "config": {
    "dockerfile_path": "./Dockerfile",
    "working_directory": "/app",
    "port": 8080,
    "long_running": true,
    "enable_http": false
  },
  "resources": {
    "cpu": "0.5",
    "memory": "512Mi",
    "cpu_limit": "1.0",
    "memory_limit": "1Gi"
  },
  "env_vars": {
    "NODE_ENV": "production",
    "LOG_LEVEL": "INFO"
  },
  "container": {
    "image_url": "registry.agenthub.app/org-uuid/agent-uuid:build-uuid",
    "image_size_mb": 245,
    "layers": 8
  },
  "metrics": {
    "instance_count": 5,
    "total_deployments": 23,
    "success_rate": 0.956
  }
}

Build Fields

Build Status Values

List Builds

Retrieve builds for an agent or organization.

Request

GET /builds/by_agent_id/{agent_id}

Path Parameters

Query Parameters

Response

{
  "data": [
    {
      "id": "build-1",
      "name": "market-agent-v1.2.0",
      "version": "1.2.0",
      "status": "completed",
      "created_at": "2024-01-15T10:30:00Z",
      "build_time_seconds": 180,
      "source": {
        "commit_sha": "abc123",
        "github_branch": "main"
      },
      "container": {
        "image_size_mb": 245
      },
      "metrics": {
        "instance_count": 3
      }
    }
  ],
  "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/builds/by_agent_id/agent-uuid?status=completed"

JavaScript

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

Get Build

Retrieve a specific build with complete details.

Request

GET /builds/{build_id}

Path Parameters

Response

Returns the complete build object with all metadata and metrics.

Examples

cURL

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

Create Build

Trigger a new build from the agent's GitHub repository.

Request

POST /builds

Request Body

{
  "agent_id": "agent-uuid",
  "organization_id": "org-uuid",
  "name": "market-agent-v2.0.0",
  "version": "2.0.0",
  "source": {
    "github_branch": "release-v2",
    "commit_sha": "def456abc789"
  },
  "config": {
    "dockerfile_path": "./production.Dockerfile",
    "working_directory": "/app",
    "port": 8080,
    "long_running": true
  },
  "resources": {
    "cpu": "1.0",
    "memory": "1Gi",
    "cpu_limit": "2.0",
    "memory_limit": "2Gi"
  },
  "env_vars": {
    "NODE_ENV": "production",
    "LOG_LEVEL": "INFO",
    "CACHE_ENABLED": "true"
  }
}

Required Fields

Optional Fields

Response

Returns the created build object with status queued or building. The build process begins immediately.

Examples

cURL

curl -X POST https://prod-agent-hosting-api.useagenthub.com/builds \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent-uuid",
    "organization_id": "org-uuid",
    "name": "hotfix-build",
    "source": {
      "github_branch": "hotfix/urgent-fix"
    }
  }'

JavaScript

const build = await fetch('https://prod-agent-hosting-api.useagenthub.com/builds', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    agent_id: 'agent-uuid',
    organization_id: 'org-uuid',
    name: 'production-build-v1.5',
    version: '1.5.0',
    source: {
      github_branch: 'main'
    }
  })
});

Update Build

Update build metadata (name, version, etc.). Cannot modify build artifacts.

Request

PUT /builds/{build_id}

Path Parameters

Request Body

{
  "name": "updated-build-name",
  "version": "1.2.1"
}

Response

Returns the updated build object.

Examples

cURL

curl -X PUT https://prod-agent-hosting-api.useagenthub.com/builds/build-uuid \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "stable-release-v1.2.1",
    "version": "1.2.1"
  }'

Delete Build

Remove a build and its associated container image.

Request

DELETE /builds/{build_id}

Path Parameters

Response

First returns deletion preview to show impact:

{
  "build": {
    "id": "build-uuid",
    "name": "build-name",
    "version": "1.0.0"
  },
  "impact": {
    "active_instances": 5,
    "total_instances_created": 23,
    "container_size_mb": 245
  },
  "warnings": [
    "This will stop 5 active instances",
    "245 MB will be freed from container registry"
  ]
}

Force Delete

To actually delete after reviewing the preview:

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

Get Build Status

Get detailed build progress and health information.

Request

GET /builds/{build_id}/status

Path Parameters

Response

{
  "status": "building",
  "progress": {
    "current_step": "Building container image",
    "completed_steps": 5,
    "total_steps": 8,
    "percent_complete": 62.5
  },
  "timeline": {
    "queued_at": "2024-01-15T10:30:00Z",
    "started_at": "2024-01-15T10:30:15Z",
    "estimated_completion": "2024-01-15T10:35:00Z"
  },
  "resource_usage": {
    "cpu_usage": "1.2 cores",
    "memory_usage": "2.5 GB",
    "disk_usage": "1.2 GB"
  }
}

Examples

cURL

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

Build Logs

Get real-time or historical build logs.

Request

GET /builds/{build_id}/logs

Path Parameters

Query Parameters

Response

Historical logs:

{
  "logs": [
    {
      "timestamp": "2024-01-15T10:30:00Z",
      "step": "clone",
      "message": "Cloning repository username/market-agent..."
    },
    {
      "timestamp": "2024-01-15T10:30:05Z", 
      "step": "analyze",
      "message": "Detected Python application with requirements.txt"
    },
    {
      "timestamp": "2024-01-15T10:30:10Z",
      "step": "build",
      "message": "Step 1/8: FROM python:3.11-slim"
    }
  ]
}

Live logs (SSE):

data: {"timestamp": "2024-01-15T10:30:15Z", "step": "build", "message": "Step 2/8: WORKDIR /app"}

data: {"timestamp": "2024-01-15T10:30:20Z", "step": "build", "message": "Step 3/8: COPY requirements.txt ."}

data: {"timestamp": "2024-01-15T10:30:25Z", "step": "build", "message": "Step 4/8: RUN pip install -r requirements.txt"}

Examples

Get Recent Logs

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

Stream Live Build Logs

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

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

eventSource.onerror = (error) => {
  console.log('Build completed or error occurred');
  eventSource.close();
};

Monitor Build Progress

import requests
import json
import time

def monitor_build(build_id, api_key):
    headers = {'Authorization': f'Bearer {api_key}'}
    
    while True:
        # Check build status
        status_response = requests.get(
            f'https://prod-agent-hosting-api.useagenthub.com/builds/{build_id}/status',
            headers=headers
        )
        status = status_response.json()
        
        print(f"Status: {status['status']}")
        print(f"Progress: {status['progress']['percent_complete']}%")
        
        if status['status'] in ['completed', 'failed', 'cancelled']:
            break
            
        time.sleep(10)  # Check every 10 seconds

monitor_build('build-uuid', 'your-api-key')

Automated Builds with Dockerizer

Trigger builds using AgentHub's auto-dockerizer for automatic Dockerfile generation.

Request

POST /builds/dockerize

Request Body

{
  "agent_id": "agent-uuid",
  "organization_id": "org-uuid",
  "name": "auto-dockerized-build",
  "source": {
    "github_repo": "username/my-agent",
    "github_branch": "main"
  },
  "auto_detect": true,
  "optimization_level": "production"
}

Dockerizer Options

Response

Returns Server-Sent Events stream with dockerization progress:

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

data: {"type": "log", "message": "Detected Python Flask application", "timestamp": "2024-01-15T10:30:05Z"}

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

data: {"type": "log", "message": "Starting container build...", "timestamp": "2024-01-15T10:30:10Z"}

data: {"type": "success", "build_id": "build-uuid", "message": "Build completed successfully"}

Examples

Auto-Dockerize Agent

curl -X POST https://prod-agent-hosting-api.useagenthub.com/builds/dockerize \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "agent_id": "agent-uuid",
    "organization_id": "org-uuid",
    "source": {
      "github_repo": "username/my-python-agent"
    },
    "optimization_level": "production"
  }'

Error Responses

Common Errors

Build Not Found (404)

{
  "error": {
    "code": "BUILD_NOT_FOUND",
    "message": "Build with ID 'build-uuid' not found"
  }
}

Build Failed (422)

{
  "error": {
    "code": "BUILD_FAILED",
    "message": "Container build failed",
    "details": {
      "exit_code": 1,
      "last_successful_step": "Installing dependencies",
      "failure_step": "Building application",
      "error_message": "ModuleNotFoundError: No module named 'requests'"
    }
  }
}

Repository Access Error (403)

{
  "error": {
    "code": "REPOSITORY_ACCESS_ERROR",
    "message": "Cannot access GitHub repository",
    "details": {
      "repository": "username/private-repo",
      "reason": "Insufficient permissions or repository does not exist"
    }
  }
}

Build Quota Exceeded (429)

{
  "error": {
    "code": "BUILD_QUOTA_EXCEEDED",
    "message": "Monthly build quota exceeded",
    "details": {
      "current_builds": 1000,
      "quota_limit": 1000,
      "quota_resets_at": "2024-02-01T00:00:00Z"
    }
  }
}

Build Optimization Tips

Dockerfile Best Practices

Multi-stage builds:

# Build stage
FROM python:3.11-slim AS builder
WORKDIR /app
COPY requirements.txt .
RUN pip install --user -r requirements.txt

# Production stage
FROM python:3.11-slim
WORKDIR /app
COPY --from=builder /root/.local /root/.local
COPY . .
CMD ["python", "main.py"]

Layer caching:

# Copy dependencies first (changes less frequently)
COPY requirements.txt package.json ./
RUN pip install -r requirements.txt

# Copy source code last (changes frequently)
COPY . .

Build Configuration

Resource allocation:

{
  "build_resources": {
    "cpu": "2.0",          // More CPU = faster builds
    "memory": "4Gi",       // Prevent OOM during compilation
    "timeout_minutes": 30  // Allow time for complex builds
  }
}

Environment optimization:

{
  "env_vars": {
    "PYTHONUNBUFFERED": "1",    // Python: immediate output
    "NODE_ENV": "production",   // Node.js: optimize builds
    "CGO_ENABLED": "0"         // Go: static binaries
  }
}

---

Next: Organizations API Reference →