API Reference

OpenAlloy exposes a local HTTP API when running in daemon mode, and validates licenses against the OpenAlloy cloud API.

License Validation API

The Go binary calls this endpoint periodically to validate the license.

POST /api/license/validate

Request:

{
    "license_key": "OA-XXXX-XXXX-XXXX",
    "machine_id": "abc123",
    "hostname": "dev-laptop",
    "os": "darwin",
    "arch": "arm64",
    "version": "1.2.0"
}

Response (valid):

{
    "valid": true,
    "license": {
        "license_key": "OA-XXXX-XXXX-XXXX",
        "license_type": "individual",
        "status": "active",
        "seats": 1,
        "expires_at": null
    }
}

Response (invalid):

{
    "valid": false,
    "error": "License key not found or revoked"
}

Local Daemon API

When running openalloy daemon, a local HTTP server starts on 127.0.0.1:9100.

POST /v1/chat

Send a chat message and get a response.

{
    "provider": "anthropic",
    "model": "claude-sonnet-4-20250514",
    "messages": [
        {"role": "user", "content": "Hello"}
    ],
    "max_tokens": 4096
}

GET /v1/models

List available models.

GET /v1/status

Get daemon status, active conversations, and license info.

POST /v1/chat/stream

Same as /v1/chat but returns Server-Sent Events for streaming responses.

Webhook Telemetry (Enterprise)

Enterprise licenses can configure a webhook endpoint to receive HMAC-signed usage events.

openalloy config set webhook.url https://your-server.com/webhook
openalloy config set webhook.secret your-hmac-secret

Event payload:

{
    "event": "chat.completion",
    "timestamp": "2026-04-07T12:00:00Z",
    "license_key": "OA-XXXX-XXXX-XXXX",
    "provider": "anthropic",
    "model": "claude-sonnet-4-20250514",
    "input_tokens": 150,
    "output_tokens": 500,
    "duration_ms": 2300,
    "machine_id": "abc123"
}

The X-OpenAlloy-Signature header contains an HMAC-SHA256 signature of the body using your webhook secret.