OpenAPI Specification

The agentkernel HTTP API is documented using OpenAPI 3.1.

Specification File

Download: openapi.yaml

Quick Reference

Endpoints

Method	Path	Description
GET	/health	Health check (no auth required)
POST	/run	Run command in temporary sandbox
GET	/sandboxes	List all sandboxes
POST	/sandboxes	Create a sandbox
GET	/sandboxes/{name}	Get sandbox info
GET	/sandboxes/by-uuid/{uuid}	Get sandbox info by UUID
DELETE	/sandboxes/{name}	Remove a sandbox
POST	/sandboxes/{name}/exec	Execute command in sandbox
GET	/orchestrations	List orchestrations
POST	/orchestrations	Create orchestration
GET	/orchestrations/definitions	List orchestration definitions
POST	/orchestrations/definitions	Create/update orchestration definition
GET	/orchestrations/definitions/{name}	Get orchestration definition by name
DELETE	/orchestrations/definitions/{name}	Delete orchestration definition by name
GET	/orchestrations/{id}	Get orchestration by id
POST	/orchestrations/{id}/events	Raise external event
POST	/orchestrations/{id}/terminate	Terminate orchestration
GET	/objects	List objects
POST	/objects	Create object
GET	/objects/{id}	Get object by id
GET	/schedules	List schedules
POST	/schedules	Create schedule
GET	/schedules/{id}	Get schedule by id
GET	/stores	List durable stores
POST	/stores	Create durable store
GET	/stores/{id}	Get durable store by id
DELETE	/stores/{id}	Delete durable store by id
POST	/stores/{id}/query	Query durable store
POST	/stores/{id}/execute	Execute write on durable store
POST	/stores/{id}/command	Execute command on durable store (Redis)

Authentication

Set AGENTKERNEL_API_KEY environment variable to enable authentication.

# Start server with API key
AGENTKERNEL_API_KEY=secret123 agentkernel serve

# Make authenticated request
curl -H "Authorization: Bearer secret123" http://localhost:18888/sandboxes

Example: Run Command

curl -X POST http://localhost:18888/run \
  -H "Content-Type: application/json" \
  -d '{"command": ["echo", "hello"]}'

Response:

{
  "success": true,
  "data": {
    "output": "hello\n"
  }
}

Example: Create and Use Sandbox

# Create
curl -X POST http://localhost:18888/sandboxes \
  -H "Content-Type: application/json" \
  -d '{"name": "my-sandbox", "image": "python:3.12-alpine"}'

# Execute
curl -X POST http://localhost:18888/sandboxes/my-sandbox/exec \
  -H "Content-Type: application/json" \
  -d '{"command": ["python3", "-c", "print(1+1)"]}'

# Remove
curl -X DELETE http://localhost:18888/sandboxes/my-sandbox

Using with API Clients

Import openapi.yaml into your favorite API client:

• Swagger UI: Paste URL or upload file
• Postman: Import → OpenAPI 3.0
• Insomnia: Import/Export → Import Data
• HTTPie: Use directly with endpoints

Code Generation

Generate client SDKs using OpenAPI Generator:

# Python client
openapi-generator generate -i api/openapi.yaml -g python -o sdk/python

# TypeScript client
openapi-generator generate -i api/openapi.yaml -g typescript-fetch -o sdk/typescript

# Go client
openapi-generator generate -i api/openapi.yaml -g go -o sdk/go