SAGE Query

POST`/api/sage`SAGE

Ask a natural-language question and receive an AI-synthesized answer grounded in the THD knowledge base.

Legacy URL

Also available at /api/sage/query — the legacy URL is still fully supported.

Also available as GET /api/sage?q=your+question.

Request

Parameters

Parameter	Type	Required	Description
`query`	string	Yes	Your question (2–500 characters). For GET requests, use the q query parameter instead.

thd-api

Response

Response200

{
"success": true,
"data": {
  "answer": "Gate 1, known as The Creative, is located in the G Center...",
  "domain": "hd"
}
}

Field	Description
`data.answer`	AI-synthesized answer in Markdown format
`data.domain`	Detected domain: `"hd"` (Human Design), `"astrology"` (Western astrology), or `"bazi"` (Four Pillars / BaZi)

The response contains exactly these two data fields. SAGE does not return retrieval metadata (sources, model, knowledge_chunks) — earlier versions of this page documented fields the API never sent. Cached answers return the same shape with header X-Cache: HIT and count 0 SAGE responses.

GET variant

For simple integrations, you can use a GET request with a query parameter:

GET /api/sage?q=What+is+Gate+1

Both q and query are accepted as parameter names.

SAGE responses

Each answered query counts as 1 SAGE response against your monthly SAGE allowance, regardless of response length. A cache hit counts 0.

Errors

Status	Error	Cause
`400`	`Query is required`	Missing query parameter
`400`	`Query must be between 2 and 500 characters`	Query too short or too long
`503`	`Knowledge service unavailable`	Knowledge database is temporarily down
`502`	`AI service error`	LLM provider returned an error