API Reference

The Hoziron HTTP API provides programmatic access to all platform capabilities. URLs are unversioned — the API version is specified via request header.

Base URL

http://127.0.0.1:4200/

In production with TLS:

https://hoziron.company.com/

Authentication

When authentication is enabled, include the API key in the Authorization header:

curl -H "Authorization: Bearer hzn_sk_a1b2c3d4..." https://hoziron.company.com/agents

Without authentication (local development), no header is needed.

Common Response Format

Success

{
  "agents": [...]
}

Error

{
  "error": {
    "category": "ValidationError",
    "message": "Agent configuration requires at least one trigger",
    "details": {
      "missing_field": "triggers"
    }
  }
}

Error Categories

Content Type

All request and response bodies use application/json unless noted otherwise.

The /metrics endpoint returns text/plain (Prometheus exposition format).

Endpoint Reference

ID Format

All resource IDs are UUIDs (v4):

550e8400-e29b-41d4-a716-446655440000

Invalid IDs return:

{
  "error": {
    "category": "ValidationError",
    "message": "Invalid agent ID: 'not-a-uuid'"
  }
}

HTTP Status Codes