POSTalphaRelationships

Compatibility Score

Score relationship compatibility using synastry, 5-7-8 house activation, love-planet frameworks, and optional StarTypes background comparison.

POST /v1/compatibility/scoreQuickstart OpenAPI JSON

Credits

4 credits per pair

Minimum Plan

Core Compute+

Billing Lane

No AI core

SDK Helper

compatibilityScore / compatibility_score

Inputs

+two birth profiles
+relationship context
+scoring profile
+optional helio background flag

Outputs

+overall score
+5/7/8 sub-scores
+chemistry
+commitment
+risk flags
+interpretation

Tool Functions

Capabilities behind this endpoint

4 functions

compatibility.score.calculate

Creates the numeric compatibility score and tier.

love.578.evaluate

Evaluates 5th, 7th, and 8th house activation patterns.

synastry.signals.weight

Weights personal planet, Saturn, Pluto, Node, Vertex, and Chiron contacts.

helio.background.compare

Optionally compares StarTypes as background context only.

Compatibility Score request

{
  "subject": { "id": "person_a", "dob": "1990-07-23", "tob": "14:30", "pob": "New York, US" },
  "partner": { "id": "person_b", "dob": "1992-11-08", "tob": "09:15", "pob": "Los Angeles, US" },
  "context": { "relationship_type": "dating" },
  "include_helio_background": false
}

Compatibility Score response

{
  "request_id": "req_...",
  "data": {
    "score": 87,
    "tier": "high",
    "subscores": {
      "romance_5th": 0.82,
      "partnership_7th": 0.9,
      "intimacy_8th": 0.78
    },
    "risk_flags": ["strong attraction requires direct communication"]
  },
  "usage": { "lane": "core", "credits": 4, "billableUnits": 1 }
}

curl

curl https://theleokingai.com/api/v1/compatibility/score \
  -X POST \
  -H "Accept: application/json" \
  -H "x-api-key: $LEOKING_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: compatibility-score-subject-123-v1" \
  -d '{
  "subject": { "id": "person_a", "dob": "1990-07-23", "tob": "14:30", "pob": "New York, US" },
  "partner": { "id": "person_b", "dob": "1992-11-08", "tob": "09:15", "pob": "Los Angeles, US" },
  "context": { "relationship_type": "dating" },
  "include_helio_background": false
}'

Node SDK

import { TheLeoKingApi } from "@theleoking/ai-api";

const api = new TheLeoKingApi({
  apiKey: process.env.LEOKING_API_KEY,
  baseUrl: "https://theleokingai.com/api"
});

const result = await api.compatibilityScore(
  {
  "subject": { "id": "person_a", "dob": "1990-07-23", "tob": "14:30", "pob": "New York, US" },
  "partner": { "id": "person_b", "dob": "1992-11-08", "tob": "09:15", "pob": "Los Angeles, US" },
  "context": { "relationship_type": "dating" },
  "include_helio_background": false
},
  "compatibility-score-subject-123-v1"
);

console.log(result.request_id);
console.log(result.usage.credits);

Python SDK

import os
from theleoking_ai_api import TheLeoKingApi

api = TheLeoKingApi(
    api_key=os.environ["LEOKING_API_KEY"],
    base_url="https://theleokingai.com/api",
)

result = api.compatibility_score(
    {
        "subject": {
            "id": "person_a",
            "dob": "1990-07-23",
            "tob": "14:30",
            "pob": "New York, US",
        },
        "partner": {
            "id": "person_b",
            "dob": "1992-11-08",
            "tob": "09:15",
            "pob": "Los Angeles, US",
        },
        "context": {
            "relationship_type": "dating",
        },
        "include_helio_background": False,
    },
    idempotency_key="compatibility-score-subject-123-v1",
)

print(result["request_id"])
print(result["usage"]["credits"])

Error Behavior

HTTP	Code	Partner Action
400	`INVALID_REQUEST`	Fix the payload shape, enum value, required field, or request body before retrying.
401	`AUTH_REQUIRED`	Send x-api-key from a trusted server environment. Do not expose keys in browser code.
401	`AUTH_INVALID`	Check the key prefix, rotate compromised keys, and verify the target environment.
402	`CREDITS_EXHAUSTED`	Upgrade the plan, add credits, or switch to a lower-cost Core Compute route.
403	`AUTH_FORBIDDEN`	Use a key scoped for this endpoint or upgrade to the required plan.
404	`NOT_FOUND`	Verify the job id, environment, API key, and whether the job belongs to the same workspace.
409	`IDEMPOTENCY_CONFLICT`	Reuse idempotency keys only for the same logical operation and identical request payload.
429	`RATE_LIMITED`	Back off, retry later, reduce concurrency, or request enterprise limits.

Related Endpoints

POSTalpha

Synastry Chart

/v1/charts/synastry