Ablecity 로고
2026.02.13 v2.4 Updated

🔗 Ablecity Manse-force · Saju API Reference

REST API guide for AI fortune, matching, and rental platforms.
Build on infrastructure that guarantees 99.99% SLA and sub-300ms latency globally.

1. Authentication

All API requests must include a Bearer Token in the HTTP Header.

Authorization: Bearer <API_KEY>

You can obtain your API key by submitting a request via the button above.

⚡ Performance & SLAs

Ablecity is designed for high-throughput global applications. We guarantee enterprise-grade performance compared to traditional legacy providers.

Metrics Legacy Competitors Ablecity (Global Cloud)
Global Latency (US West) 1,200ms ~ 2,500ms 180ms ~ 350ms [P90]
Max Concurrency (TPS) ~ 50 TPS (Throttled) 30,000+ TPS
Calculation Precision Mean Solar Time (Fixed KST) GPS-based True Solar Time
Uptime SLA None (Best Effort) 99.99% Guaranteed

2. Standard Response Format

{
  "status": "success",   // or "error"
  "data": ... ,          // Payload
  "message": "..."       // Description or error message
}

3. Endpoints Overview

3.1 GET /api/v1/saju/fortune

Predictive AI

Generates a complete Asian Astrology (Four Pillars of Destiny) chart. It calculates the user's elemental balance, personality archetypes (Ten Gods), and future fortune trends based on precise astronomical data.

GET Request Example
curl -X GET \
"https://api.ablecity.kr/api/v1/saju/fortune?birth=1995-06-15T14:30:00&gender=male&city=NewYork" \
-H "Authorization: Bearer <API_KEY>" \
-H "Accept: application/json"

* midnightType (0: Standard) and calendar (solar) are applied as defaults if omitted.

Query Parameters

Name Type Required Description
birth string Yes Date and time of birth in ISO 8601 format.
(e.g., 1995-06-15T14:30:00 - The 'T' separator is mandatory)
gender string Yes Biological sex for calculation logic. Values: male or female.
city string Optional Birth city for True Solar Time correction. Defaults to Seoul.
See the supported Western cities list below.
midnightType integer Optional 0: Split Rat Hour (Standard / Recommended)
1: Combined Rat Hour (23:00~00:59 as next day)
calendar string Optional solar (Gregorian, default), lunar, leap (Lunar Leap Month)
📍 Supported Cities List (Major Western Cities)

Usage: city=NewYork or city=London

NewYork LosAngeles Chicago Toronto Vancouver SanFrancisco Seattle Boston Washington London Paris Berlin Rome Madrid Amsterdam Sydney Melbourne Singapore HongKong Tokyo Seoul (Default)

Response Example

{
  "status": "success",
  "message": "Request successful.",
  "data": {
    "year": {
      "pillar": "Wu-Yin",
      "translation": "Earth Tiger",
      "archetype": "Direct Resource (The Scholar)"
    },
    "month": {
      "pillar": "Jia-Yin",
      "translation": "Wood Tiger",
      "archetype": "Direct Officer (The Leader)"
    },
    "day": {
      "pillar": "Xin-Hai",
      "translation": "Metal Pig",
      "archetype": "Self (The Core)"
    },
    "hour": {
      "pillar": "Wu-Zi",
      "translation": "Earth Rat",
      "archetype": "Direct Resource (The Mentor)"
    },
    "elemental_balance": {
      "wood": { "count": 3, "percentage": 46.3, "rating": "High" },
      "fire": { "count": 1, "percentage": 5.0,  "rating": "Low" },
      "earth": { "count": 2, "percentage": 19.5, "rating": "Moderate" },
      "metal": { "count": 1, "percentage": 7.3,  "rating": "Low" },
      "water": { "count": 1, "percentage": 21.9, "rating": "Moderate" }
    },
    "chart_strength": "Weak",
    "balancing_element": {
      "primary": "Fire",
      "secondary": "Earth",
      "advice": "Your chart is cold and damp. You need Fire energy (passion, activity) to balance it."
    },
    "lucky_factors": {
      "color": "#FF5733 (Red/Orange)",
      "direction": "South",
      "number": [2, 7]
    }
  }
}

Field Descriptions

Pillars (year, month, day, hour)

Core stem/branch structure including Hanja/Hangul and Ten-Gods mapping.

Five-Element Distribution (five)

Absolute values, percentages, star ratings, and localized label mappings.

Hehua Analysis (hehua)

true / pseudo / failed staging, application flags, and before/after five-element + Yongshin tracking.

Twelve Growth (twelve_growth)

Lifecycle states for each pillar (Birth, Bath, Crown, etc.) in multilingual labels.

Strength (strength)

strength plus quantitative evidence via strength_score, strength_thresholds, and strength_components.

Pattern (geokguk)

Expanded pattern data including geok_detail, pillar_category_counts, and follower/variant signals.

Yongshin / Hishin (yongshin)

Primary and secondary balancing elements for practical guidance.

Branch Relations (branch_relations)

Harmony/clash/punishment/harm plus advanced sets like half_three_harmonies, banghap, and tam_hap_mang_chung.

Distance & Policy

branch_relations_distance (near/mid/far, avg_factor) and branch_relations_policy (core/aux/school tiers).

Analysis Flow (analysis_flow)

Traceable internal calculation steps for QA and debugging workflows.

Luck Cycles (big_luck)

10-year cycles with age ranges and year ranges for long-horizon forecasting.

Lucky Factors (lucky)

Actionable numbers, directions, and color hints (including CSS-style color tokens).

🆕 New Response Fields (Advanced Analysis)

Field Type Description
hehua Object Six-harmony transformation evaluation result with candidates, effective groups, apply flags, adjustments, and before/after balance tracking.
branch_relations_distance Object Distance summary by relation key: near, mid, far, and avg_factor.
branch_relations_policy Object Scoring policy profile and relation tier sets (core, aux, school_specific).
analysis_flow Array<String> Engine flow trace array, e.g. branch_relations → hehua_condition_check → five_elements_recalculate.
strength_* Number / Object Quantified evidence for strength judgment, including score, thresholds, and components.
geokguk (expanded) Object Extended pattern object with geok_detail, pillar-level category counts, and variant signals.
sinsal Array<Object> Detailed list of all applied auspicious/inauspicious stars (up to 56 types) with score and position metadata.

3.1-A Thematic Fortune & Deep Analysis (Add-ons)

Beyond the base natal chart endpoint, Ablecity provides thematic fortune modules, deep narrative analysis, and AI Vision-ready expansion paths.
Endpoints are split into synchronous GET and asynchronous POST + callback flows.

  • GET Synchronous: Returns results immediately in response.
  • POST Asynchronous: Delivers results to X-Callback-URL after processing.

🔗 Endpoint List

Method Endpoint Path Description
GET /api/v1/saju/fortune/daily Today's fortune
GET /api/v1/saju/fortune/zodiac-luck Today's zodiac fortune
POST /api/v1/saju/fortune/request-analysis/match Compatibility analysis (Callback required)
POST /api/v1/saju/fortune/request-analysis/week-luck Weekly fortune (Callback required)
POST /api/v1/saju/fortune/request-analysis/this-year-luck Yearly fortune (Callback required)
POST /api/v1/saju/fortune/request-analysis/love-luck Love forecast (Callback required)
POST /api/v1/saju/fortune/request-analysis/rich-luck Wealth forecast (Callback required)
POST /api/v1/saju/fortune/request-analysis/telling Narrative Saju reading (Callback required)

Request Example (POST + Callback)

* For asynchronous analysis requests, X-Callback-URL is required.

curl -X POST \
"https://api.ablecity.kr/api/v1/saju/fortune/request-analysis/rich-luck" \
-H "Authorization: Bearer <API_KEY>" \
-H "X-Callback-URL: https://your-server.com/webhook/result" \
-H "Content-Type: application/json" \
-d '{
  "birth": "1990-01-01T00:00:00",
  "gender": "male",
  "city": "Seoul",
  "calendar": "solar",
  "midnightType": 0
}'

3.2 POST /api/v1/matching

Creates a matching request for social discovery apps. Supports filtering by age, interests, and geolocation (radius).

POST /api/v1/matching

Request Example

curl -X POST https://api.ablecity.kr/v1/matching \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
-d '{
  "userId": "USER123",
  "preferences": {
    "ageRange": [25, 35],
    "interests": ["tech", "hiking"],
    "location": { "lat": 40.7128, "lng": -74.0060, "radiusKm": 15 }
  },
  "maxResults": 10
}'

3.6 ~ 3.9 OTC & Rental API

Endpoints for building decentralized exchange (OTC) and asset rental platforms.
Please contact sales for full documentation on these modules.

4. Error Codes

HTTP Status Code Description
400 INVALID_REQUEST Bad request. Missing required parameters or invalid syntax.
401 UNAUTHORIZED Authentication failed. Invalid or expired API Key.
404 NOT_FOUND The requested resource could not be found.
429 RATE_LIMIT Too many requests. Quota exceeded.
500 SERVER_ERROR Internal server error. Please contact support.

4.1 Standard Messages

  • Request completed successfully. – 200 OK.
  • Internal Server Error. – Unexpected failure. Check server logs or status page.
  • Service not found. – The requested endpoint URI is invalid.

4.2 Auth & Throttling Messages

  • Invalid API Key.
    The key is missing from the header, malformed, or has been revoked.
  • Minute limit exceeded.
    You have exceeded the per-minute request quota (60 req/min).
  • Daily limit exceeded.
    You have exceeded the daily request quota (50,000 req/day).
  • Service not enabled.
    Your API Key does not have permission to access this specific endpoint.

4.3 Domain Specific Errors (Saju)

  • ℹ️ invalid birth date format
    Must be yyyy-MM-dd HH:mm:ss. Check for the 'T' separator or spacing.
  • ℹ️ gender must be 'male' or 'female'
    Case-sensitive. Only 'male' or 'female' strings are accepted.
  • ℹ️ invalid timezone
    The city parameter does not map to a valid IANA timezone.

5. Rate Limits & Quotas

To maintain high availability and performance stability, API usage is capped on a per-key basis. We enforce both Burst Limits (short-term) and Daily Quotas (long-term).

Burst Limit Per Minute
60 reqs/min
Daily Quota Per Day
50,000 reqs/day

⚠️ Handling Rate Limit Errors

If you exceed these limits, the API will return a 429 Too Many Requests status. Clients should handle this gracefully using an Exponential Backoff strategy.

Need higher throughput for a production launch? Contact Sales to upgrade your quota.

6. FAQ

What is the pricing model?

We offer a Free Tier (first 100 requests) for testing. For production, we use a usage-based pricing model (approx. $0.01 - $0.10 per call) or fixed monthly Enterprise contracts.

Can I increase my Rate Limits?

Yes. The default limit (60 req/min) is sufficient for most startups. If you expect high traffic spikes or batch processing needs, please contact support to upgrade to an Enterprise Plan.

What SDKs or languages are supported?

Our API is language-agnostic. It returns standard RESTful JSON, compatible with any HTTP client in Python, Node.js, Go, Java, PHP, Ruby, etc.

How should I handle errors?

For 429 (Rate Limit) or 5xx (Server) errors, we strongly recommend implementing Exponential Backoff (e.g., retry after 1s, then 2s, then 4s) with a maximum of 3 retries.

How do I get a Test API Key?

Submit your request via the API key form. Our team reviews requests manually and usually replies within 1-2 business days.

7. Developer Support

Stuck on integration?

Our engineering team is available to assist with API integration, debugging, and best practices.
For critical issues, please include your API Key (partial) and request details.

✉️ Contact Engineering

Ablecity (Seoul HQ)

Managing Partner: H.KWON
Email: [email protected]

© 2026 Ablecity. All rights reserved.