Agent HTTP API Reference

Base Path

The normalized Agent HTTP API lives under:

https://api.humandesign.ai/agent/v1/tools

Every route is POST only and requires header authentication.

Authentication

X-Api-Key: your_api_key_here
Authorization: Bearer your_api_key_here

Query-string API keys are rejected on Agent HTTP routes.

Response Envelope

Every successful response uses the same shape:

{
  "version": "v1",
  "tool": "resolve_timezone",
  "data": { ... },
  "meta": { ... },
  "error": null
}

Endpoints

• POST /agent/v1/tools/resolve-timezone
• POST /agent/v1/tools/generate-chart
• POST /agent/v1/tools/generate-composite-chart
• POST /agent/v1/tools/get-reference-item
• POST /agent/v1/tools/get-transits
• POST /agent/v1/tools/search-celebrities

Example: Generate a Chart

POST /agent/v1/tools/generate-chart
{
  "birthDateTime": "1990-05-15T14:30:00",
  "timezone": "America/New_York",
  "detailLevel": "core"
}

detailLevel accepts core or full. The full variant requires Startup or above.

Example: Get Transits

POST /agent/v1/tools/get-transits
{
  "date": "2026-03-12T00:00:00",
  "timezone": "UTC"
}

Add natalChart if you want a natal-versus-transit response:

{
  "date": "2026-03-12T00:00:00",
  "timezone": "UTC",
  "natalChart": {
    "birthDateTime": "1990-05-15T14:30:00",
    "timezone": "America/New_York"
  }
}

Billing

Each successful Agent HTTP request consumes 1 API unit from the same monthly quota used by REST and MCP.