First calls in five minutes

First calls in five minutes

This is a worked session against the hosted service. All examples use the same chart subject — 1990-01-01, 12:00, London — so your first response matches the numbers below exactly. Worked JSON uses the plain REST endpoint at https://api.agentastrology.com; MCP calls are identical except for the tool-call envelope and the connection, which the connect guide covers.

1. Cast a natal chart — astro_chart

curl -X POST https://api.agentastrology.com/v1/tools/astro_chart \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "natal",
    "birthData": {
      "year": 1990,
      "month": 1,
      "day": 1,
      "hour": 12,
      "minute": 0,
      "latitude": 51.5074,
      "longitude": -0.1278,
      "timezone": 0
    }
  }'

As an MCP tool call the same request is:

{
  "name": "astro_chart",
  "arguments": {
    "method": "natal",
    "birthData": {
      "year": 1990,
      "month": 1,
      "day": 1,
      "hour": 12,
      "minute": 0,
      "latitude": 51.5074,
      "longitude": -0.1278,
      "timezone": 0
    }
  }
}

2. Read the response

The response is a birthChart object. The verified values for this input:

{
  "summary": {
    "dateTime": "1990-01-01 12:00 (UTC+0)",
    "universalTime": "12:00:00",
    "houseSystem": "Placidus system",
    "coordinates": "51d30'N, 0d8'W",
    "zodiac": "Tropical",
    "ayanamsaOffset": null
  },
  "planets": [
    { "id": "Sun", "longitude": 280.814,
      "sign": { "sign": 9, "signName": "Capricorn", "degrees": 10, "minutes": 48, "seconds": 51 },
      "house": 10 },
    { "id": "ASC",
      "sign": { "signName": "Aries", "degrees": 24, "minutes": 56 } }
  ],
  "houses": [
    { "house": 1, "longitude": 24.934,
      "sign": { "signName": "Aries", "degrees": 24, "minutes": 56 } }
  ]
}

The chart subject's Sun is Capricorn 10°48′ — longitude 280.814° — and the Ascendant is Aries 24°56′. The full output also includes the midheaven, vertex, major aspects, technical coordinates, and the Part of Fortune and Part of Spirit. Planet longitudes are decimal degrees in the tropical zodiac by default.

3. Render the wheel — astro_render_wheel

curl -X POST https://api.agentastrology.com/v1/tools/astro_render_wheel \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "single",
    "birthData": {
      "year": 1990,
      "month": 1,
      "day": 1,
      "hour": 12,
      "minute": 0,
      "latitude": 51.5074,
      "longitude": -0.1278,
      "timezone": 0
    }
  }'

The response is { "svg": string, "style": "wheel", "harmonic": 1 }. The svg field is a full standalone SVG document (about 138 KB for this chart — wheel, houses, planets, and aspect lines). Save it to a file and open it in a browser:

curl -X POST https://api.agentastrology.com/v1/tools/astro_render_wheel \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{ "method": "single", "birthData": { "year": 1990, "month": 1, "day": 1, "hour": 12, "minute": 0, "latitude": 51.5074, "longitude": -0.1278, "timezone": 0 } }' \
  | python3 -c "import json,sys,sysconfig; out=json.load(sys.stdin); open('wheel.svg','w').write(out['svg'])" 2>/dev/null || \
curl -X POST https://api.agentastrology.com/v1/tools/astro_render_wheel \
  -H "Authorization: Bearer <key>" -H "Content-Type: application/json" \
  -d '{ "method": "single", "birthData": { "year": 1990, "month": 1, "day": 1, "hour": 12, "minute": 0, "latitude": 51.5074, "longitude": -0.1278, "timezone": 0 } }' \
  -o response.json

Then pull the svg field out of response.json with any JSON tool. Pass "style": "square" for the square layout or "harmonic": 4 for a harmonic chart (whole numbers from 1 to 360).

4. A flat-input call — astro_moment

astro_moment does not take birthData. Its fields are flat at the top level, so don't nest them:

curl -X POST https://api.agentastrology.com/v1/tools/astro_moment \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "moon-phase",
    "year": 2026,
    "month": 8,
    "day": 9,
    "hour": 12,
    "minute": 0,
    "timezone": -3,
    "houseSystem": "placidus",
    "zodiac": "tropical"
  }'

The response:

{
  "moon": {
    "sign": { "signName": "Cancer", "degrees": 4, "minutes": 26 },
    "longitude": 94.435,
    "isRetrograde": false,
    "house": null
  },
  "phase": {
    "name": "Waning Crescent",
    "displayName": "Balsamic Moon (Waning Crescent)",
    "elongation": 317.386,
    "elongationDegrees": 317,
    "elongationMinutes": 23
  },
  "zodiac": "tropical",
  "ayanamsaOffset": null
}

Only year, month, day, houseSystem, and zodiac are required; hour, minute, second, latitude, longitude, and timezone are optional. Use a current date rather than the 1990 example to see the phase for "now".

5. Debugging a bad call

Wrong payloads do not return charts. Check the body for a missing method, a birthData field passed to a flat tool like astro_moment, or a timezone written as a string ("Europe/London") instead of a number. Every failure comes back with a structured error envelope — the errors guide lists the codes and what each one means.

Related