---
title: "Build dispositor tree from planetary placements"
method: POST
path: "/ephemeris/dispositor-tree"
tags: ["ephemeris"]
---

# Build dispositor tree from planetary placements

`POST /ephemeris/dispositor-tree`

## Request

- Base URL: `https://api.openephemeris.com`
- URL: `https://api.openephemeris.com/ephemeris/dispositor-tree`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-OpenEphemeris-API-Key`
  - API key in header `X-API-Key`
  - API key in header `X-Service-Key`

Build a dispositor tree from a set of planetary sign placements. Each planet is "disposed" by the ruler of the sign it occupies. The algorithm walks these rulership chains to identify final dispositors (planets ruling their own sign) and mutual receptions (pairs disposing each other).

No ephemeris kernel required — pass in pre-computed sign placements. Signs are 0-based in the API (0=Aries … 11=Pisces) and converted internally.

🤖 Agent-first endpoint — pure deterministic math, no ephemeris required.

## Query parameters

- `output_mode` string, nullable
- `format` string

## Headers

- `authorization` string, nullable
- `X-API-Key` string, nullable
- `X-OpenEphemeris-API-Key` string, nullable
- `apikey` string, nullable

## Request body

- DispositorTreeRequest: Input for dispositor tree calculation. Provide each planet's sign placement. Signs use 0-based indexing (0=Aries, 11=Pisces) to match the standard API convention.
  - `planets` object[], required: Array of planetary placements with planet ID and occupied sign.
    - `planet_id` integer, required: Standard planet ID (0=Sun, 1=Moon, 2=Mercury, 3=Venus, 4=Mars, 5=Jupiter, 6=Saturn)
    - `sign` integer, required: Zodiac sign the planet occupies (0=Aries … 11=Pisces). Converted to 1-based internally.

## Response `200`

Successful Response

- DispositorTreeResponse: Dispositor tree analysis — shows the chain of planetary rulership, identifying final dispositors and mutual receptions.
  - `calculation_metadata` object: Processing metadata
  - `final_dispositor` union: Deprecated — use final_dispositors. Populated only when the chart has exactly one final dispositor; null otherwise (including when there are several).
    - DispositorFinalDispositorResponse: The final dispositor of the chart.
      - `planet_id` integer, required
      - `planet_name` string, required
    - object, nullable
  - `final_dispositors` DispositorFinalDispositorResponse[], required: All final dispositors (planets ruling their own sign) in the chart. A chart can have more than one — e.g. Sun in Leo and Moon in Cancer are each the terminus of their own independent chain. Empty if none.
    - `planet_id` integer, required
    - `planet_name` string, required
  - `mutual_receptions` DispositorMutualReceptionResponse[], required: Pairs of planets in mutual reception (each in the other's sign)
    - `planet1_id` integer, required
    - `planet1_name` string, required
    - `planet2_id` integer, required
    - `planet2_name` string, required
  - `nodes` DispositorNodeResponse[], required: All nodes in the dispositor tree
    - `depth` integer, required: Number of hops to the chain terminus (final dispositor or cycle)
    - `dispositor_id` integer, required: Planet ID of the dispositor (ruler of this planet's sign)
    - `dispositor_name` string, required: Dispositor planet name
    - `is_final_dispositor` boolean, required: True if this planet rules its own sign
    - `planet_id` integer, required: Planet SE index
    - `planet_name` string, required: Human-readable planet name
    - `sign` integer, required: Sign number (0-based for API)
    - `sign_name` string, required: Zodiac sign name
  - `success` boolean, required

## Other responses

- `400`: Bad Request
- `422`: Unprocessable Entity - Invalid input format
- `500`: Internal Server Error

---

[API](https://skmtc.dev/openephemeris/apis/open-ephemeris-api.md) · [All operations](https://skmtc.dev/openephemeris/apis/open-ephemeris-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openephemeris/apis/open-ephemeris-api/revisions/d195a769cb89?raw)