API Reference

Overview

The AgentMetal REST API is served at http://localhost:8080/v1 and provides programmatic access to all infrastructure resources. The API follows RESTful conventions with JSON request and response bodies.

Authentication

All API requests require authentication via the X-API-Key header:

curl -H "X-API-Key: ak_live_abc123" http://localhost:8080/v1/instances

API keys can be generated from the AgentMetal dashboard or via the CLI.

Request/Response Patterns

Common Patterns

Operation	Method	Response Code	Response Body
List resources	GET	200	`{"items": [...]}`
Get resource	GET	200	Single resource object
Create resource	POST	201 / 202	Created resource or operation
Delete resource	DELETE	202	Operation object

### Asynchronous Operations

Long-running operations (create, delete) return HTTP 202 with an operation ID:

{
  "operation_id": "op-abc123",
  "status": "pending",
  "resource_id": "inst-xyz789"
}

Poll the operation status:

curl -H "X-API-Key: $KEY" http://localhost:8080/v1/operations/op-abc123

Error Format

All errors follow a consistent format:

{
  "error": "instance not found: inst-abc123"
}

Status Code	Meaning
400	Bad Request - invalid input
401	Unauthorized - missing or invalid API key
404	Not Found - resource does not exist
409	Conflict - resource already exists
422	Unprocessable Entity - validation failed
429	Too Many Requests - rate limit exceeded
500	Internal Server Error

## Rate Limiting

The API enforces rate limits per API key:

Standard: 100 requests per minute
Burst: 20 requests per second

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1709312400

Content Type

All requests and responses use application/json:

curl -X POST http://localhost:8080/v1/instances \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"name": "web"}, "spec": {"type": "cx31", "image": "ubuntu-22.04"}}'