# TimePortal Saju — LLM query guide Use this interface when a user asks you to query Saju and report a text table. An HTTP-capable LLM or agent can use GET or POST; no browser automation is required. - Endpoint: https://timeportal.pro/saju/query.php - OpenAPI schema: https://timeportal.pro/saju/openapi.json - Human application: https://timeportal.pro/saju/ - GET without arguments returns capability metadata and links. `OPTIONS` is supported for browser clients. - `format=markdown` returns plain UTF-8 text containing Markdown tables. `format=json` (default) returns named tables, metadata, normalized query options, and the same `markdown` report. - Every table row is a calculated result or annotation from the existing application. Readings are not generated by an LLM. ## How an agent should work 1. Obtain the required dates and any requested options from the user. Use unambiguous YYYY-MM-DD dates; do not guess missing personal dates. 2. Prefer a structured request using the fields below. For an ordinary language request, send `query` with explicit ISO dates; the site's Jev model selects typed arguments. Explicit structured fields override the interpreted fields. Jev's shortcut covers dates, hemisphere flags, language, aspect selection, masking for Saju, and primary/market-context flags for Future. Supply exact relationship filters, minimum durations, and display names through their structured fields. 3. Submit the request once. Requests use the site's existing access controls and reading limits. Do not automatically retry a limited request. 4. Check HTTP status and `success`. A 422 response asks for corrected inputs; 429 means the existing reading limit; 502/504 means an upstream problem. Never invent a replacement reading. 5. Return the supplied text tables, preserving directions, dates, units, score labels, missing-data notes, and the distinction between the site's symbolic interpretation and a factual prediction. Do not present symbolic scores as measured real-world probabilities. 6. If a result is large, use explicit aspect/date filters with the user's intent and state those filters. Do not silently omit unfavorable rows or turn all features into a single summary. ## Credentials and privacy If the user already has a site access credential, send it as `Authorization: Bearer `, `X-Timeportal-Code`, or the `access_code` field of a JSON POST. Do not put credentials in URLs. The server preserves the backend's access decision; this API does not grant additional privileges. The Jev API key is configured on the server; callers do not supply it. Natural-language `query` text is sent to TypeSafe/Jev for interpretation. Do not put any access credential in that text. Structured queries do not call Jev. Natural-language interpretation is limited to 24 requests per minute across this interface; a busy response also uses HTTP 429. Responses use `Cache-Control: no-store` and are not stored by these endpoints. Treat returned personal readings as private; do not publish or cache them. Return the requested one-off report to the user. Query-side display names never cause a saved-name write. ## Saju fields | Field | Type / default | Meaning | | --- | --- | --- | | date1, date2 | required ISO dates | Two dates, between 1930-01-01 and 2029-12-31 | | southern1, southern2 | boolean / false | Each person's hemisphere flag, passed independently to the existing backend | | aspects | array or comma-separated names / all | Requested aspect rows; the score is computed over returned covered rows | | name1, name2 | optional text / empty | Display labels only, at most 60 characters; not saved | | mask_dates | boolean / false | Replace dates with *** in the report and normalized query metadata | | language | en or ko / en | English or Korean aspect labels and existing explanations | | format | json or markdown / json | Response representation | | query | optional text | Natural-language query containing two explicit ISO dates, interpreted by Jev | Available aspects are the same eleven listed in the Future guide. Removed outer-planet aspects and rows missing coverage are omitted exactly as in the current app. Both directional readings, source elements, colors, powerful-team status, per-row multipliers, pair counts, raw score, displayed site score, and mythological-soulmate result are returned. Explanations reproduce the application's current color-specific text. Each row scores once: powerful team ×47; blue/green ×13; red/purple ×0.1; orange ×0.5; plain neutral ×1. The product is the raw site score. The displayed denominator is rounded to an integer and floored at 1. Mythological-soulmate status requires at least three soulmate pairs, no destructive pairs, and a displayed denominator of at least 1,080. This is the site's symbolic scoring rule, not an empirically established probability of meeting someone. The secret-date feature is browser-local. An LLM cannot retrieve a user's browser-stored secret; obtain the actual authorized date for the request and set `mask_dates=true` if the returned report should hide it. This API does not save names or secret dates. ### Full-feature structured example POST https://timeportal.pro/saju/query.php Content-Type: application/json ```json {"date1":"1990-01-01","date2":"1992-02-02","southern1":false,"southern2":true,"aspects":"all","name1":"Person A","name2":"Person B","mask_dates":false,"language":"en","format":"markdown"} ``` GET example: https://timeportal.pro/saju/query.php?date1=1990-01-01&date2=1992-02-02&southern2=true&format=markdown Jev example: `{"query":"Compare the first person 1990-01-01, northern hemisphere, with the second person 1992-02-02, southern hemisphere. Include every aspect and show the report in Korean.","format":"markdown"}` Copyable user prompt: “Read https://timeportal.pro/saju/llms.txt. Submit a full-feature comparison for [first date] and [second date], using [first hemisphere] and [second hemisphere]. Report every aspect in a text table with both directions, explanations, score breakdown, and the site's soulmate classification. Ask me for any missing required information.”