Skip to content

AGENTS.md

Latest commit

 

History

History
86 lines (71 loc) · 7.49 KB

AGENTS.md

File metadata and controls

86 lines (71 loc) · 7.49 KB
Raw

AGENTS.md for Flying Stars API

This repo teaches AI coding agents (Cursor, Claude Code, Aider, Codex, Windsurf, RooCode, Gemini CLI) how to use the RoxyAPI flying star natal chart endpoint.

Endpoint

  • Method: POST
  • URL: https://roxyapi.com/api/v2/feng-shui/flying-stars/natal
  • Auth: X-API-Key header
  • Domain: feng-shui (one of 14+ in the RoxyAPI catalog)
  • Operation ID: generateFlyingStarChart matches the SDK method name in camelCase
  • MCP tool: post_feng_shui_flying_stars_natal on https://roxyapi.com/mcp/feng-shui

TypeScript SDK

import { createRoxy } from '@roxyapi/sdk';
const roxy = createRoxy(process.env.ROXY_API_KEY!);
const { data, error } = await roxy.fengShui.generateFlyingStarChart({
  body: { period: 9, facing: 'wu' },
});

Python SDK

import os
from roxy_sdk import create_roxy
roxy = create_roxy(os.environ["ROXY_API_KEY"])
chart = roxy.feng_shui.generate_flying_star_chart(period=9, facing="wu")

Setup step (no coordinates, no location search)

This endpoint describes a building, not a person. It takes no birth date, no birth time, no latitude and no longitude, so there is nothing to geocode. Do not call /location/search for it. The one setup step worth making is a period lookup: if the caller knows a completion date rather than a period number, GET /feng-shui/periods?date=YYYY-MM-DD first and feed currentPeriod into the natal call.

Request fields

  • period (integer, optional): 1 to 9. The twenty year period the building was completed in, or last renovated heavily enough to reset. Fixed for the life of the building. Periods change at Li Chun in early February, so a building finished in January 2024 is a Period 8 building. Defaults to the period in force now
  • facing (string, conditional): the mountain the front faces, by pinyin id or compass label. The facing side is the open, active, public side, which is not always the side with the front door
  • facingDegrees (number, conditional): 0 to 360, the bearing measured looking out from inside. Resolved to one of the 24 mountains
  • lang (query string, optional): nine locales alongside English, including Simplified and Traditional Chinese

Send facing or facingDegrees. Sending neither returns a 400 with code of bad_request.

The facing enum, verbatim

facing is a 24 value enum, NOT a compass word. Passing "south", "north" or "SE" returns a 400.

  • Pinyin ids: ren zi gui chou gen yin jia mao yi chen xun si bing wu ding wei kun shen geng you xin xu qian hai
  • Compass labels: N1 N2 N3 NE1 NE2 NE3 E1 E2 E3 SE1 SE2 SE3 S1 S2 S3 SW1 SW2 SW3 W1 W2 W3 NW1 NW2 NW3

The two vocabularies are interchangeable and index the same 24 sectors in the same order, so wu and S2 return an identical chart. Matching is case insensitive.

Response top level keys

  • period: the period the chart was built for, echoed or resolved
  • facing: the resolved facing mountain object, with id, label, chinese, pinyin, direction, yuan, polarity, startDegree, endDegree
  • sitting: the mountain directly opposite, same shape
  • facingDegrees: echo of the bearing, present ONLY when a bearing was sent. Branch on presence, never on a sentinel
  • straddling: boolean, true when the bearing fell in the outer 3 degrees of its mountain rather than the central 9. Always false when the facing was named as a mountain
  • mountainCenterStar, waterCenterStar: the star that entered the centre of each plate, 1 to 9
  • mountainFlight, waterFlight: forward or reverse, published separately because the two plates fly independently
  • structure: id, name, chinese, meaning. id is one of prosperous-mountain-prosperous-water, reversed, double-facing, double-sitting
  • palaces[]: all nine, centre first and then along the Lo Shu flight path. Each has palace, base, period, mountain, water, reading, and combination when the pair is a named formation

Domain rules

  • Coordinates are never needed. Never call /location/search for this endpoint.
  • The period is DATED, not assumed. Period 9 opened on 4 February 2024 and runs to 2043. A building completed in January 2024 is Period 8. Never hardcode a period constant: read it from /feng-shui/periods, which resolves currentPeriod for any date.
  • palaces[].palace, structure.id, combination.id, mountainFlight, waterFlight, facing.id, facing.direction and the star numbers are stable English machine values, never localized. Branch on them safely under any language. structure.name, structure.meaning, palaces[].reading and the star meanings translate in place; combination.name keeps its English value and adds nameLocalized beside it.
  • combination is ABSENT for the pairs the tradition does not name. Check presence before reading it. The composed reading is always present and carries the meaning either way.
  • combination.id is canonical with the lower number first, so mountain 9 with water 7 and mountain 7 with water 9 both resolve to 7-9. Nature is on the object as nature.
  • Each of the nine stars appears exactly once on each plate. That invariant is what makes a chart checkable, and it is a cheap assertion to add to a test.
  • Read mountain for health, for the people in the room and for the relationships between them, and water for money, opportunity and whatever arrives from outside. Do not average them into one score.
  • A straddling of true means the bearing sits on a boundary and the case calls for a different construction. Surface the flag rather than presenting the returned chart as settled.
  • The natal chart is fixed for the life of the building. The annual and monthly plates are the moving layer, so overlay /feng-shui/flying-stars/annual/{year} and /feng-shui/flying-stars/monthly on the same nine palaces rather than recasting the natal chart.
  • The annual changeover is Li Chun in early February and NOT Lunar New Year, which in 2026 falls roughly two weeks later. The annual endpoint returns changeoverDate so the plate is applied on the right day.

Related endpoints

  • GET /feng-shui/periods (listNinePeriods, get_feng_shui_periods): the nine periods from 1864 to 2043 with the exact Li Chun date each opened, plus currentPeriod for a date you pass
  • GET /feng-shui/flying-stars/stars (listFlyingStars, get_feng_shui_flying_stars): the nine star catalogue with element, home palace, trigram, ruling period, meaning, and the elements that strengthen or drain each star
  • GET /feng-shui/flying-stars/annual/{year} (getAnnualFlyingStars, get_feng_shui_flying_stars_annual_year): the annual plate, universal to every building, with changeoverDate
  • GET /feng-shui/flying-stars/monthly (getMonthlyFlyingStars, get_feng_shui_flying_stars_monthly): the monthly overlay on SOLAR months, where month 1 begins at Li Chun and no month lines up with a calendar month
  • GET /feng-shui/bagua (listBaguaSectors, get_feng_shui_bagua): the bagua life areas, eight compass sectors plus the centre, with element, colors, trigram and focus
  • POST /feng-shui/eight-mansions (generateEightMansions, post_feng_shui_eight_mansions): the Eight Mansions map for a person rather than a building, ranked best to worst

Verified

2026-Q3 against https://roxyapi.com/api/v2/openapi.json. Re-fetch the spec for ground truth before changing this file.

Discovery