{
  "info": {
    "_postman_id": "saju-api-v0-2-0",
    "name": "Saju API (Korean Four Pillars)",
    "description": "Saju API v0.2.0 — 6 endpoints, 10 languages.\n\nDesign-partner ready. Free tier: 100 req/day.\n\n- Production: https://saju-api.pages.dev\n- Docs (OpenAPI 3.1): /docs/openapi.yaml\n\nGet a free API key with `POST /v1/keys/create`, then set the `api_key` collection variable in Postman. All requests inherit the variable via `X-API-Key: {{api_key}}`.\n\nPostman variable docs (2026): https://learning.postman.com/docs/sending-requests/variables/variables/",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    {
      "key": "base_url",
      "value": "https://saju-api.pages.dev",
      "type": "string"
    },
    {
      "key": "api_key",
      "value": "sajuapi_free_REPLACE_ME_AFTER_CREATING_KEY",
      "type": "string",
      "description": "Paste your key after calling POST /v1/keys/create. Treat as a secret."
    }
  ],
  "auth": {
    "type": "apikey",
    "apikey": [
      { "key": "key", "value": "X-API-Key", "type": "string" },
      { "key": "value", "value": "{{api_key}}", "type": "string" },
      { "key": "in", "value": "header", "type": "string" }
    ]
  },
  "item": [
    {
      "name": "Saju",
      "item": [
        {
          "name": "Calculate — Four Pillars from birthdate",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "url": { "raw": "{{base_url}}/api/v1/calculate", "host": ["{{base_url}}"], "path": ["api", "v1", "calculate"] },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"year\": 1990,\n  \"month\": 5,\n  \"day\": 15,\n  \"hour\": 14,\n  \"gender\": \"M\",\n  \"lang\": \"en\"\n}"
            },
            "description": "Returns the Four Pillars (year/month/day/hour), the five-element distribution, the Day Master stem/element/polarity, and the Chinese zodiac animal."
          },
          "response": [
            {
              "name": "200 — tiger male, May 1990",
              "code": 200,
              "status": "OK",
              "body": "{\n  \"input\": { \"year\": 1990, \"month\": 5, \"day\": 15, \"hour\": 14, \"gender\": \"M\", \"lang\": \"en\" },\n  \"pillars\": {\n    \"year\":  { \"stem\": \"\\uacbd\", \"branch\": \"\\uc624\" },\n    \"month\": { \"stem\": \"\\uc2e0\", \"branch\": \"\\uc0ac\" },\n    \"day\":   { \"stem\": \"\\uacbd\", \"branch\": \"\\uc9c4\" },\n    \"hour\":  { \"stem\": \"\\uacc4\", \"branch\": \"\\ubbf8\" }\n  },\n  \"elements\": { \"wood\": 0, \"fire\": 2, \"earth\": 2, \"metal\": 3, \"water\": 1 },\n  \"day_master\": { \"stem\": \"\\uacbd\", \"element\": \"metal\", \"polarity\": \"yang\" },\n  \"zodiac\": \"horse\",\n  \"tier\": \"free\",\n  \"remaining\": 99\n}"
            }
          ]
        },
        {
          "name": "Interpret — Ten Gods, Yongshin, summaries",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "url": { "raw": "{{base_url}}/api/v1/interpret", "host": ["{{base_url}}"], "path": ["api", "v1", "interpret"] },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"year\": 1990,\n  \"month\": 5,\n  \"day\": 15,\n  \"hour\": 14,\n  \"gender\": \"M\",\n  \"lang\": \"en\"\n}"
            },
            "description": "Full interpretation: Ten Gods per pillar (in the requested lang), 12 Life Stages, hidden stems, harmony/clash interactions, Yongshin (useful god), and 10-year Daeun cycles.\n\nLang values: ko, en, ja, zh, es, pt-br, vi, id, hi, th."
          }
        }
      ]
    },
    {
      "name": "Compatibility",
      "item": [
        {
          "name": "Compatibility — two-person 궁합 score",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "url": { "raw": "{{base_url}}/api/v1/compatibility", "host": ["{{base_url}}"], "path": ["api", "v1", "compatibility"] },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"person_a\": { \"year\": 1990, \"month\": 5, \"day\": 15, \"hour\": 14, \"gender\": \"M\" },\n  \"person_b\": { \"year\": 1992, \"month\": 8, \"day\": 23, \"hour\": 9, \"gender\": \"F\" },\n  \"lang\": \"en\"\n}"
            },
            "description": "Deterministic 0..100 score with four component breakdown: element_balance, day_master_relation, branch_harmony, branch_clash."
          }
        }
      ]
    },
    {
      "name": "Daily",
      "item": [
        {
          "name": "Daily — today's fortune for a Day Master",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/v1/daily?day_master=갑&date=2026-05-28&lang=en",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "daily"],
              "query": [
                { "key": "day_master", "value": "갑", "description": "Korean stem (갑..계) OR English alias (wood_yang, water_yin, ...)" },
                { "key": "date",       "value": "2026-05-28", "description": "Optional. Defaults to today UTC." },
                { "key": "lang",       "value": "en", "description": "Optional. One of ko en ja zh es pt-br vi id hi th." }
              ]
            },
            "description": "Lightweight, edge-cached (1h s-maxage). Best for push-notification fan-out or widgets."
          }
        }
      ]
    },
    {
      "name": "Account",
      "item": [
        {
          "name": "Create API key (free tier, no auth)",
          "request": {
            "auth": { "type": "noauth" },
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "url": { "raw": "{{base_url}}/api/v1/keys/create", "host": ["{{base_url}}"], "path": ["api", "v1", "keys", "create"] },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"email\": \"dev@yourcompany.io\",\n  \"tier\": \"free\"\n}"
            },
            "description": "Self-serve free-tier key issuance. Paid tiers (dev/pro/enterprise) require an `X-Tier-Token` header from the billing webhook.\n\nThe key is shown ONCE in the response. Copy it into the `api_key` collection variable."
          },
          "event": [
            {
              "listen": "test",
              "script": {
                "exec": [
                  "// Auto-capture the issued key into the collection variable.",
                  "if (pm.response.code === 200) {",
                  "  const json = pm.response.json();",
                  "  if (json && json.api_key) {",
                  "    pm.collectionVariables.set('api_key', json.api_key);",
                  "    pm.test('api_key captured', () => pm.expect(json.api_key).to.match(/^sajuapi_/));",
                  "  }",
                  "}"
                ],
                "type": "text/javascript"
              }
            }
          ]
        },
        {
          "name": "Usage — current quota for your key",
          "request": {
            "method": "GET",
            "header": [],
            "url": { "raw": "{{base_url}}/api/v1/usage", "host": ["{{base_url}}"], "path": ["api", "v1", "usage"] },
            "description": "Returns used_today / remaining / reset_at_utc for the supplied X-API-Key. Does NOT increment your daily counter."
          }
        }
      ]
    }
  ]
}