Total Human DesignDashboard|
Documentation

Penta (Group Dynamics) API

POST/api/pentaExperimental

Generate a BG5 Penta — the group-level (trans-auric) energy field for a family or business team of 3 to 5 people, calculated from their birth data. Returns the merged Penta chart with channel dynamics, viability scoring, gaps, and hiring guidance.

Live beta

Penta is live and returns real data on any Advanced key, but it is still in beta: the response shape may add fields before the official launch and is not yet covered by our no-breaking-changes guarantee. We will never remove the endpoint silently. See Beta & Roadmap.

What a Penta is

A Penta is the BG5 (Business Gene Keys / Human Design for Business) model for the energetic field that forms when 3 to 5 people operate as a single unit — a family or a small business team. Above five people the field shifts to a different structure (the WA/Wave), so Penta is bounded at 3-5 participants.

Instead of analysing each person's chart, the Penta looks at 12 specific gates across the Throat, G, and Sacral centers, which form 6 Penta channels that map to the functional roles a group needs to run well (vision, operations, foundation, and resources). A channel is active when the group, collectively, holds both of its gates — even if no single person holds the whole channel (an electromagnetic connection between two members). The result tells you where the group is strong, where it has structural gaps, and what kind of person would fill those gaps.

Chart-request billing

Each Penta call costs 5 Chart requests, flat — one for each potential participant, regardless of whether you send 3, 4, or 5 people. Charts are calculated in parallel server-side.

Request

The request body accepts a participants array of 3 to 5 people, each with birth data, plus an optional type selecting the family or business interpretation lens. Each participant uses the same birth-data parameters as the single Chart API.

Body Parameters

ParameterTypeRequiredDescription
participantsarrayYesArray of 3 to 5 participant objects. Fewer than 3 or more than 5 returns 400.
participants[].birthDatestringYesDate of birth (YYYY-MM-DD)
participants[].birthTimestringYesTime of birth (HH:MM, 24-hour format)
participants[].birthLocationstringYesBirth city (e.g. "New York, NY")
participants[].namestringNoLabel for this person (defaults to "Person 1", "Person 2", …). Used throughout the response.
participants[].latitudenumberNoLatitude override for geocoding
participants[].longitudenumberNoLongitude override for geocoding
typestringNoInterpretation lens: "family" or "business". Default: "family". Controls the skill/shadow labels in the analysis.
thd-api

Response

A successful call returns { success, meta, data }. The meta.type echoes the lens you requested. Everything substantive lives under data, which has two top-level keys: participants (per-person contribution) and composite (the merged group analysis).

Response200

{
"success": true,
"meta": {
  "version": "2.0.0",
  "timestamp": "2026-06-23T10:30:00.000Z",
  "endpoint": "v1-penta",
  "type": "business"
},
"data": {
  "participants": [
    {
      "index": 0,
      "name": "Ava",
      "birthDate": "1990-05-15",
      "birthTime": "14:30",
      "birthLocation": "New York, NY",
      "bg5Gates": [8, 1, 5],
      "bg5GateDetails": [
        { "gate": 8, "polarity": "conscious", "lines": [3], "planets": ["Sun"] }
      ],
      "contribution": {
        "gateCount": 3,
        "gatePct": 25.0,
        "channelsPartial": 3,
        "channelsFull": 1
      },
      "v1Mini": {
        "type": "Generator",
        "authority": "Sacral",
        "profile": "2/4",
        "definedCenters": ["sacral", "throat"],
        "channels": ["1-8"]
      }
    }
  ],
  "composite": {
    "gateActivationGrid": [
      { "gate": 31, "theme": "Discipline", "center": "throat", "direction": "Future", "activatedBy": [{ "name": "Ben", "index": 1 }], "activated": true }
    ],
    "channels": [
      {
        "id": "1-8",
        "name": "Inspiration",
        "gates": [1, 8],
        "type": "contained",
        "defined": true,
        "participantsAtGateA": [{ "name": "Ava", "index": 0 }],
        "participantsAtGateB": [{ "name": "Ava", "index": 0 }]
      }
    ],
    "centers": {
      "throat": {
        "defined": true,
        "gates": [31, 8, 33, 7, 1, 13],
        "activatedGates": [8, 1],
        "participants": [{ "name": "Ava", "gates": [8, 1] }],
        "gaps": [31, 33, 7, 13],
        "themeColumns": ["Discipline", "Demonstration", "Family Traditions"]
      },
      "g": { "defined": true, "gates": ["..."], "activatedGates": ["..."], "participants": ["..."], "gaps": ["..."], "themeColumns": ["..."] },
      "sacral": { "defined": true, "gates": [5, 14, 29], "activatedGates": [5], "participants": ["..."], "gaps": [14, 29], "themeColumns": ["..."] }
    },
    "gaps": {
      "missingGates": [33, 7, 13, 46, 14, 29],
      "missingChannels": ["13-33", "29-46"],
      "dysfunctionNotes": ["Missing Gate 33 (Family Traditions) — group lacks consistent family traditions in past direction."]
    },
    "functionalRows": {
      "row1": { "theme": "Discipline", "gates": [31, 8, 33], "filled": [31, 8], "missing": [33] },
      "row2": { "theme": "Operations", "gates": [7, 1, 13], "filled": [1], "missing": [7, 13] },
      "row3": { "theme": "Internal Flow", "gates": [15, 2, 46], "filled": [15, 2], "missing": [46] },
      "row4": { "theme": "Material", "gates": [5, 14, 29], "filled": [5], "missing": [14, 29] }
    },
    "pentaAnatomy": {
      "upper_penta": {
        "label": "Upper Penta (Vision & Direction)",
        "channels": {
          "1-8": {
            "name": "Inspiration",
            "businessLabel": "Creative Role Model & Contribution to the World",
            "status": "Active",
            "typeCode": "DOM",
            "typeLabel": "Solo-Driven",
            "contributors": { "Ava": { "gate_1": { "lines": [2], "polarities": ["conscious"], "lineLabels": ["Hermit"] } } },
            "gapAnalysis": null
          }
        }
      },
      "lower_penta": {
        "label": "Lower Penta (Foundation & Resources)",
        "channels": {
          "29-46": {
            "name": "Discovery",
            "businessLabel": "Perseverance & Success",
            "status": "Inactive",
            "typeCode": "VOID",
            "typeLabel": "Inactive",
            "contributors": {},
            "gapAnalysis": {
              "missingGates": [29, 46],
              "missingSkills": ["Perseverance", "Success"],
              "shadowThemes": ["Overcommitment", "Self-doubt"],
              "severity": "CRITICAL",
              "impact": "Without this channel the group struggles to follow through on what it starts."
            }
          }
        }
      }
    },
    "analyticalMetrics": {
      "stabilityScore": 70,
      "visionScore": 66,
      "actionScore": 33,
      "viabilityLevel": "functional",
      "viabilitySummary": "Core channels are defined. This group has a solid foundation but gaps in some areas will require conscious attention.",
      "bottlenecks": ["Ava"],
      "backboneIntegrity": { "15-5": "Strong", "2-14": "Missing", "46-29": "Missing" }
    },
    "functionalRoles": {
      "Inspiration": ["Ava"]
    },
    "hiringLogic": {
      "urgentNeeds": [33, 13, 46],
      "urgentNeedsDetail": [
        { "gate": 33, "skill": "Privacy", "shadow": "Secrecy" }
      ],
      "insight": "Group has 1/3 backbone channels. Vision dominates."
    }
  }
}
}

data.participants[] — per-person contribution

FieldDescription
indexZero-based position matching the input participants array order
nameThe person's label (your name, or "Person N")
birthDate / birthTime / birthLocationEchoed birth data
bg5GatesThe Penta gates this person holds (subset of the 12 BG5 gates)
bg5GateDetails[]Per-gate polarity (conscious / unconscious / both), lines, and planets
contribution.gateCountHow many of the 12 BG5 gates this person holds
contribution.gatePctThat count as a percentage of 12
contribution.channelsPartialPenta channels this person touches (one gate)
contribution.channelsFullPenta channels this person holds end-to-end (both gates)
v1MiniCondensed chart: type, authority, profile, definedCenters, channels

data.composite — the merged group field

FieldDescription
gateActivationGrid[]All 12 BG5 gates with theme, center, direction, who activatedBy, and an activated boolean
channels[]The 6 Penta channels: id, name, gates, defined, type (contained = one person holds both gates · electromagnetic = two people · incomplete = not formed), and which participants sit at each gate
centersthroat, g, sacral — each with defined, activatedGates, contributing participants, gaps, and themeColumns
gaps.missingGatesBG5 gates no one in the group holds
gaps.missingChannelsPenta channels the group cannot form
gaps.dysfunctionNotesPlain-language notes for each missing gate
functionalRowsThe four functional bands (Discipline / Operations / Internal Flow / Material), each with filled and missing gates
pentaAnatomyupper_penta (Vision & Direction) and lower_penta (Foundation & Resources). Each channel carries status, a dynamics typeCode / typeLabel, contributors, and — when inactive — a gapAnalysis
analyticalMetricsGroup scoring (see below)
functionalRolesMap of active channel name → the people who drive it
hiringLogicurgentNeeds (top missing gates), urgentNeedsDetail (gate → skill + shadow), and a one-line insight

Channel dynamics — typeCode / typeLabel

Each Penta channel is classified by how the group forms it:

typeCodetypeLabelMeaning
EMElectromagneticTwo different people each hold one gate of the channel
COMPElectromagnetic with FrictionMultiple people hold the gates (compromise dynamic)
DOMSolo-DrivenOne person holds the whole channel — a potential bottleneck
MIXEDMixed (Solo + EM)A solo holder plus electromagnetic partners
VOIDInactiveThe channel is not formed; see gapAnalysis

Scoring — analyticalMetrics

FieldDescription
viabilityLeveloptimal (all 6 channels) · functional (≥4) · minimal (≥2) · dysfunctional (<2)
viabilitySummaryPlain-language summary of the viability level
stabilityScore0-100, driven by how many of the 3 backbone channels are active
visionScore0-100, share of the Upper Penta (vision) channels that are active
actionScore0-100, share of the Lower Penta (action) channels that are active
bottlenecksPeople who solo-drive a channel (single points of failure)
backboneIntegrityThe three backbone channels (15-5, 2-14, 46-29) marked Strong or Missing

MCP tool: get_penta

The same calculation is available over the MCP server as the get_penta tool. It takes the same participants and group type, costs the same 5 Chart requests, and returns the Penta result as a JSON string in result.content[0].text.

Argument names match the HTTP body

Over MCP the array is named participants and the group lens is named type ("family" or "business") — identical to the HTTP body. The MCP result wraps the analysis as { "type": "<group type>", "data": { /* same participants + composite shape as above */ } }.

tools/calljson
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
  "name": "get_penta",
  "arguments": {
    "type": "business",
    "participants": [
      { "name": "Ava",  "birthDate": "1990-05-15", "birthTime": "14:30", "birthLocation": "New York, NY" },
      { "name": "Ben",  "birthDate": "1985-12-03", "birthTime": "08:45", "birthLocation": "London, UK" },
      { "name": "Mara", "birthDate": "1992-07-21", "birthTime": "19:10", "birthLocation": "Sydney, Australia" }
    ]
  }
}
}

Errors & limits

ConstraintValue
Min participants3 (fewer returns 400)
Max participants5 (more returns 400)
type valuesfamily, business (anything else returns 400)
Required tieradvanced_chart
Cost5 Chart requests per call (flat)
Per-participant calc timeout10s — a slow participant fails the whole call

Tier requirement

Penta needs the advanced_chart product. Basic chart keys receive a 403 Forbidden. A missing or malformed participant returns 400 with { "success": false, "error": "Participant N missing required fields" }.