I-Ching oracle API with all 64 hexagrams, 384 changing lines, 8 trigrams, and modern interpretations for love, career, and decision-making. Cast readings with the authentic three-coin method, get a daily hexagram, and explore the Book of Changes programmatically. Built for divination apps, AI oracle chatbots, fortune-telling platforms, daily wisdom features, and spiritual guidance products. One key covers every RoxyAPI domain, with Remote MCP and typed SDKs.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/roxyapi-i-ching-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Roxy I Ching API
version: 2.0.0
description: '# RoxyAPI: AI-Native Insight Infrastructure
> **Base URL:** `https://roxyapi.com/api/v2`
> All endpoint paths below are relative to this base URL.'
contact:
name: RoxyAPI Support
url: https://roxyapi.com/contact
license:
name: Proprietary
url: https://roxyapi.com/policy/terms
servers:
- url: /api/v2
description: Production API v2
security:
- apiKey: []
tags:
- name: I-Ching
description: I-Ching oracle API with all 64 hexagrams, 384 changing lines, 8 trigrams, and modern interpretations for love, career, and decision-making. Cast readings with the authentic three-coin method, get a daily hexagram, and explore the Book of Changes programmatically. Built for divination apps, AI oracle chatbots, fortune-telling platforms, daily wisdom features, and spiritual guidance products. One key covers every RoxyAPI domain, with Remote MCP and typed SDKs.
paths:
/iching/daily:
post:
operationId: getDailyHexagram
tags:
- I-Ching
summary: Get daily I-Ching hexagram
description: Receive a daily I-Ching hexagram for guidance and reflection. This endpoint uses seeded randomness to ensure the same seed gets the same hexagram on the same day - perfect for "Hexagram of the Day" features in oracle apps, meditation platforms, and daily wisdom tools. Returns the hexagram with judgment, image, and interpretations for love, career, decisions, and practical advice based on ancient Chinese wisdom from the Book of Changes.
security:
- apiKey: []
parameters:
- schema:
type: string
enum:
- en
- tr
- de
- es
- hi
- pt
- fr
- ru
- zh-Hans
- zh-Hant
default: en
example: en
description: 'Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.'
required: false
description: 'Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.'
name: lang
in: query
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
seed:
type: string
example: user123
description: Optional seed for reproducible readings. Same seed + same date = same hexagram every time. Pass any unique identifier (userId, email hash, session token). Omit for anonymous daily readings.
date:
type: string
format: date
example: '2026-03-06'
description: Date for the reading in YYYY-MM-DD format. Defaults to today (UTC). Useful for viewing past daily readings or pre-generating future ones.
responses:
'200':
description: Daily hexagram reading with full interpretation
content:
application/json:
schema:
type: object
properties:
date:
type: string
example: '2026-01-28'
description: Date this daily hexagram is for (YYYY-MM-DD, UTC).
seed:
type: string
example: user123-2026-01-28
description: Computed seed used for this reading. Same seed always produces the same hexagram.
hexagram:
type: object
properties:
number:
type: number
example: 1
description: Hexagram number in King Wen sequence (1-64).
symbol:
type: string
example: ䷀
description: Unicode hexagram symbol for display.
chinese:
type: string
example: 乾
description: Original Chinese name.
english:
type: string
example: The Creative
description: English translation of the hexagram name.
pinyin:
type: string
example: Qián
description: Pinyin romanization with tone marks.
upperTrigram:
type: string
example: Heaven
description: Upper trigram (lines 4-6).
lowerTrigram:
type: string
example: Heaven
description: Lower trigram (lines 1-3).
judgment:
type: string
example: Pure creative force is available and it runs from origin to completion without obstruction, so the situation rewards initiative that stays correct and does not slacken. Success here is built by sustained effort held to a straight line, not by a single burst.
description: The Judgment (Tuan) text, the primary oracle statement of the hexagram offering core guidance.
image:
type: string
example: 'Heaven above heaven: the same motion repeated without pause and without fatigue. Renew your own strength on your own schedule rather than waiting to be driven by circumstances.'
description: The Image (Xiang) text, symbolic guidance derived from the trigram combination describing the ideal action.
interpretation:
type: object
properties:
general:
type: string
example: A time of great creative power and initiative. The universe supports bold action and forward movement. Success comes through strength of character and unwavering perseverance.
description: General life situation interpretation.
love:
type: string
example: A time of strong creative energy and passionate connection. Take the initiative in expressing your feelings, but avoid arrogance.
description: Love and relationship guidance.
career:
type: string
example: Exceptional opportunities for advancement and recognition await. Your creative ideas and leadership abilities are at their peak.
description: Career and professional interpretation.
decision:
type: string
example: The time is right for bold action. Trust your instincts and move forward with confidence.
description: Decision-making guidance for whether to act, wait, or change course.
advice:
type: string
example: 'Be like the heavens: consistent, powerful, and untiring. Make yourself strong through steady effort, not through force.'
description: Practical wisdom and actionable advice.
required:
- general
- love
- career
- decision
- advice
description: Modern interpretations across life areas based on ancient I-Ching wisdom.
required:
- number
- symbol
- chinese
- english
- pinyin
- upperTrigram
- lowerTrigram
- judgment
- image
- interpretation
dailyMessage:
type: string
example: 'Your hexagram for 2026-01-28: The Creative (乾). Be like the heavens: consistent, powerful, and untiring.'
description: Concise daily message summarizing the hexagram guidance
required:
- date
- seed
- hexagram
- dailyMessage
'400':
description: Validation error. `issues[]` lists every failed field.
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: First issue summary.
code:
type: string
enum:
- validation_error
issues:
type: array
description: Every validation failure. Use this to rebuild a valid request.
items:
type: object
properties:
path:
type: string
description: Dot-separated field path, or "(root)" for top-level.
message:
type: string
code:
type: string
description: Zod issue code (invalid_type, too_small, too_big, invalid_string, ...).
expected:
type: string
description: Expected type for invalid_type.
minimum:
description: Minimum bound for too_small issues.
oneOf:
- type: number
- type: string
maximum:
description: Maximum bound for too_big issues.
oneOf:
- type: number
- type: string
inclusive:
type: boolean
format:
type: string
description: Format name for string issues (regex, email, url, uuid).
pattern:
type: string
description: Regex pattern when format is regex.
required:
- path
- message
required:
- error
- code
- issues
'401':
description: Invalid or missing API key
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Human-readable error message. May change wording.
code:
type: string
description: Machine-readable error code. Stable identifier.
required:
- error
- code
'405':
description: Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.
headers:
Allow:
description: Comma-separated list of allowed methods (RFC 9110).
schema:
type: string
content:
application/json:
schema:
type: object
properties:
error:
type: string
code:
type: string
enum:
- method_not_allowed
allow:
type: array
items:
type: string
description: Allowed HTTP methods for this path. Mirrors the Allow response header.
docs:
type: string
description: Link to the product page for this domain.
required:
- error
- code
- allow
'429':
description: Monthly rate limit exceeded
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Human-readable error message. May change wording.
code:
type: string
description: Machine-readable error code. Stable identifier.
required:
- error
- code
'500':
description: Failed to generate daily hexagram
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Resource not found
description: Human-readable error message. The wording may change, so do not parse it programmatically. Switch on the stable code instead.
code:
type: string
example: not_found
description: Machine-readable error code. Stable identifier for programmatic error handling.
required:
- error
- code
/iching/daily/cast:
post:
operationId: castDailyReading
tags:
- I-Ching
summary: Cast daily I-Ching reading with changing lines
description: Cast a complete daily I-Ching reading using the traditional three-coin method with seeded randomness. Unlike the simple daily hexagram, this provides the full casting experience with line values (6-9), changing line positions, and the resulting hexagram if transformation occurs. Same seed + same date = same casting result. Perfect for I-Ching divination apps requiring authentic oracle experience with daily consistency.
security:
- apiKey: []
parameters:
- schema:
type: string
enum:
- en
- tr
- de
- es
- hi
- pt
- fr
- ru
- zh-Hans
- zh-Hant
default: en
example: en
description: 'Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.'
required: false
description: 'Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.'
name: lang
in: query
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
seed:
type: string
example: user123
description: Optional seed for reproducible readings. Same seed + same date = same hexagram every time. Pass any unique identifier (userId, email hash, session token). Omit for anonymous daily readings.
date:
type: string
format: date
example: '2026-03-06'
description: Date for the reading in YYYY-MM-DD format. Defaults to today (UTC). Useful for viewing past daily readings or pre-generating future ones.
responses:
'200':
description: Complete daily casting with primary and resulting hexagrams
content:
application/json:
schema:
type: object
properties:
date:
type: string
example: '2026-01-28'
description: Date this daily casting is for (YYYY-MM-DD, UTC).
seed:
type: string
example: user123-2026-01-28
description: Computed seed for reproducible castings.
hexagram:
type: object
properties:
number:
type: number
example: 1
description: Hexagram number in King Wen sequence (1-64).
symbol:
type: string
example: ䷀
description: Unicode hexagram symbol for display.
chinese:
type: string
example: 乾
description: Original Chinese name.
english:
type: string
example: The Creative
description: English translation of the hexagram name.
pinyin:
type: string
example: Qián
description: Pinyin romanization with tone marks.
upperTrigram:
type: string
example: Heaven
description: Upper trigram (lines 4-6).
lowerTrigram:
type: string
example: Heaven
description: Lower trigram (lines 1-3).
judgment:
type: string
example: Pure creative force is available and it runs from origin to completion without obstruction, so the situation rewards initiative that stays correct and does not slacken. Success here is built by sustained effort held to a straight line, not by a single burst.
description: The Judgment (Tuan) text, the primary oracle statement of the hexagram offering core guidance.
image:
type: string
example: 'Heaven above heaven: the same motion repeated without pause and without fatigue. Renew your own strength on your own schedule rather than waiting to be driven by circumstances.'
description: The Image (Xiang) text, symbolic guidance derived from the trigram combination describing the ideal action.
interpretation:
type: object
properties:
general:
type: string
example: A time of great creative power and initiative. The universe supports bold action and forward movement. Success comes through strength of character and unwavering perseverance.
description: General life situation interpretation.
love:
type: string
example: A time of strong creative energy and passionate connection. Take the initiative in expressing your feelings, but avoid arrogance.
description: Love and relationship guidance.
career:
type: string
example: Exceptional opportunities for advancement and recognition await. Your creative ideas and leadership abilities are at their peak.
description: Career and professional interpretation.
decision:
type: string
example: The time is right for bold action. Trust your instincts and move forward with confidence.
description: Decision-making guidance for whether to act, wait, or change course.
advice:
type: string
example: 'Be like the heavens: consistent, powerful, and untiring. Make yourself strong through steady effort, not through force.'
description: Practical wisdom and actionable advice.
required:
- general
- love
- career
- decision
- advice
description: Modern interpretations across life areas based on ancient I-Ching wisdom.
required:
- number
- symbol
- chinese
- english
- pinyin
- upperTrigram
- lowerTrigram
- judgment
- image
- interpretation
lines:
type: array
items:
type: number
example:
- 7
- 8
- 9
- 7
- 6
- 8
description: Line values (6-9) from bottom to top. 6=old yin (changing), 7=young yang, 8=young yin, 9=old yang (changing).
changingLinePositions:
type: array
items:
type: number
example:
- 3
- 5
description: Positions of changing lines (1-6, bottom to top). These lines transform yin to yang or vice versa.
changingLines:
type: array
items:
$ref: '#/components/schemas/ChangingLine'
description: The oracle statement and meaning of each line that came up CHANGING, and only those. The changing lines are what the cast is actually about, so this saves a second call to read them and stops a consuming agent from having to invent them.
resultingHexagram:
type: object
properties:
number:
type: number
example: 1
description: Hexagram number in King Wen sequence (1-64).
symbol:
type: string
example: ䷀
description: Unicode hexagram symbol for display.
chinese:
type: string
example: 乾
description: Original Chinese name.
english:
type: string
example: The Creative
description: English translation of the hexagram name.
pinyin:
type: string
example: Qián
description: Pinyin romanization with tone marks.
upperTrigram:
type: string
example: Heaven
description: Upper trigram (lines 4-6).
lowerTrigram:
type: string
example: Heaven
description: Lower trigram (lines 1-3).
judgment:
type: string
example: Pure creative force is available and it runs from origin to completion without obstruction, so the situation rewards initiative that stays correct and does not slacken. Success here is built by sustained effort held to a straight line, not by a single burst.
description: The Judgment (Tuan) text, the primary oracle statement of the hexagram offering core guidance.
image:
type: string
example: 'Heaven above heaven: the same motion repeated without pause and without fatigue. Renew your own strength on your own schedule rather than waiting to be driven by circumstances.'
description: The Image (Xiang) text, symbolic guidance derived from the trigram combination describing the ideal action.
interpretation:
type: object
properties:
general:
type: string
example: A time of great creative power and initiative. The universe supports bold action and forward movement. Success comes through strength of character and unwavering perseverance.
description: General life situation interpretation.
love:
type: string
example: A time of strong creative energy and passionate connection. Take the initiative in expressing your feelings, but avoid arrogance.
description: Love and relationship guidance.
career:
type: string
example: Exceptional opportunities for advancement and recognition await. Your creative ideas and leadership abilities are at their peak.
description: Career and professional interpretation.
decision:
type: string
example: The time is right for bold action. Trust your instincts and move forward with confidence.
description: Decision-making guidance for whether to act, wait, or change course.
advice:
type: string
example: 'Be like the heavens: consistent, powerful, and untiring. Make yourself strong through steady effort, not through force.'
description: Practical wisdom and actionable advice.
required:
- general
- love
- career
- decision
- advice
description: Modern interpretations across life areas based on ancient I-Ching wisdom.
required:
- number
- symbol
- chinese
- english
- pinyin
- upperTrigram
- lowerTrigram
- judgment
- image
- interpretation
description: Hexagram after transformation (if changing lines present)
required:
- date
- seed
- lines
- changingLinePositions
'400':
description: Validation error. `issues[]` lists every failed field.
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: First issue summary.
code:
type: string
enum:
- validation_error
issues:
type: array
description: Every validation failure. Use this to rebuild a valid request.
items:
type: object
properties:
path:
type: string
description: Dot-separated field path, or "(root)" for top-level.
message:
type: string
code:
type: string
description: Zod issue code (invalid_type, too_small, too_big, invalid_string, ...).
expected:
type: string
description: Expected type for invalid_type.
minimum:
description: Minimum bound for too_small issues.
oneOf:
- type: number
- type: string
maximum:
description: Maximum bound for too_big issues.
oneOf:
- type: number
- type: string
inclusive:
type: boolean
format:
type: string
description: Format name for string issues (regex, email, url, uuid).
pattern:
type: string
description: Regex pattern when format is regex.
required:
- path
- message
required:
- error
- code
- issues
'401':
description: Invalid or missing API key
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Human-readable error message. May change wording.
code:
type: string
description: Machine-readable error code. Stable identifier.
required:
- error
- code
'405':
description: Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.
headers:
Allow:
description: Comma-separated list of allowed methods (RFC 9110).
schema:
type: string
content:
application/json:
schema:
type: object
properties:
error:
type: string
code:
type: string
enum:
- method_not_allowed
allow:
type: array
items:
type: string
description: Allowed HTTP methods for this path. Mirrors the Allow response header.
docs:
type: string
description: Link to the product page for this domain.
required:
- error
- code
- allow
'429':
description: Monthly rate limit exceeded
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Human-readable error message. May change wording.
code:
type: string
description: Machine-readable error code. Stable identifier.
required:
- error
- code
'500':
description: Internal server error
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Human-readable error message. May change wording.
code:
type: string
description: Machine-readable error code. Stable identifier.
required:
- error
- code
/iching/hexagrams:
get:
operationId: listHexagrams
tags:
- I-Ching
su
# --- truncated at 32 KB (96 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/roxyapi/refs/heads/main/openapi/roxyapi-i-ching-api-openapi.yml