openapi: 3.0.3
info:
  title: Human Design API — v1
  description: |
    v1 endpoints for calculating and analyzing Human Design charts.

    ## Authentication
    All endpoints require two headers:
    - `HD-Api-Key` — your API key
    - `HD-Geocode-Key` — your Google Geocoding API key

  version: "1.1.204"
  contact:
    name: API Support
    email: info@mail.humandesignapi.nl
    url: https://humandesignapi.nl
  license:
    name: Proprietary
    url: https://humandesignapi.nl

servers:
  - url: https://api.humandesignapi.nl/v1
    description: Production server

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: HD-Api-Key
      description: Human Design API key
    GeocodeKeyAuth:
      type: apiKey
      in: header
      name: HD-Geocode-Key
      description: Google Geocoding API key

  schemas:
    BodygraphInput:
      type: object
      required:
        - birthdate
        - birthtime
        - location
      properties:
        birthdate:
          type: string
          description: Date of birth in a valid format
          example: "01-Jan-1990"
        birthtime:
          type: string
          description: Time of birth in HH:MM format
          example: "14:30"
        location:
          type: string
          minLength: 4
          description: Location of birth (city, country)
          example: "Haarlem, The Netherlands"

    BodygraphResponse:
      type: object
      properties:
        type:
          type: string
          description: "Human Design type: Generator, Manifesting Generator, Projector, Manifestor, or Reflector"
          example: "Generator"
        profile:
          type: string
          description: Profile line combination (e.g. 6/2)
          example: "6/2"
        channels_short:
          type: array
          items:
            type: string
          description: Active channel connections as gate pairs
          example: ["20-34", "10-57"]
        centers:
          type: array
          items:
            type: string
          description: Defined (active) energy centers
          example: ["G", "Sacral", "Spleen", "Throat"]
        strategy:
          type: string
          description: Decision-making strategy based on type
          example: "To Respond"
        authority:
          type: string
          description: Inner authority for decision-making
          example: "Sacral"
        incarnation_cross:
          type: string
          description: Incarnation cross with gate numbers
          example: "Right Angle Cross of Tension (39/38 | 51/57)"
        definition:
          type: string
          description: "How defined centers connect: Single, Split, Triple Split, Quad Split, or No Definition"
          example: "Split Definition"
        signature:
          type: string
          description: Emotional signature when living correctly
          example: "Satisfaction"
        not_self_theme:
          type: string
          description: Emotional indicator of misalignment
          example: "Frustration"
        cognition:
          type: string
          description: Cognitive processing style
          example: "Smell"
        determination:
          type: string
          description: Dietary determination for wellbeing
          example: "Calm Appetite"
        variables:
          type: string
          description: Variable configuration (arrow directions)
          example: "PLL DRL"
        motivation:
          type: string
          description: Underlying motivation theme
          example: "Hope"
        transference:
          type: string
          description: Not-self motivation pattern
          example: "Guilt"
        perspective:
          type: string
          description: Perspective awareness theme
          example: "Survival"
        distraction:
          type: string
          description: Not-self perspective pattern
          example: "Power"
        environment:
          type: string
          description: Optimal physical environment
          example: "Selective Caves"
        circuitries:
          type: string
          description: Active circuitry types (comma-separated)
          example: "Individual, Tribal"
        channels_long:
          type: array
          items:
            type: string
          description: Full channel names with gate numbers
          example: ["The Channel of Charisma (20-34)", "The Channel of the Brainwave (57-10)"]
        gates:
          type: array
          items:
            type: string
          description: All activated gate numbers
          example: ["20", "34", "10", "57"]
        activations:
          type: object
          description: Planetary gate/line activations for both sides
          properties:
            design:
              type: object
              description: Design (unconscious) planetary activations
              properties:
                sun:
                  type: string
                  example: "20.1"
                earth:
                  type: string
                  example: "34.1"
                north_node:
                  type: string
                  example: "10.3"
                south_node:
                  type: string
                  example: "15.3"
                moon:
                  type: string
                  example: "57.4"
                mercury:
                  type: string
                  example: "48.2"
                venus:
                  type: string
                  example: "18.5"
                mars:
                  type: string
                  example: "28.1"
                jupiter:
                  type: string
                  example: "32.6"
                saturn:
                  type: string
                  example: "50.3"
                uranus:
                  type: string
                  example: "44.2"
                neptune:
                  type: string
                  example: "26.4"
                pluto:
                  type: string
                  example: "54.1"
            personality:
              type: object
              description: Personality (conscious) planetary activations
              properties:
                sun:
                  type: string
                  example: "10.3"
                earth:
                  type: string
                  example: "15.3"
                north_node:
                  type: string
                  example: "57.4"
                south_node:
                  type: string
                  example: "51.4"
                moon:
                  type: string
                  example: "20.1"
                mercury:
                  type: string
                  example: "34.6"
                venus:
                  type: string
                  example: "5.2"
                mars:
                  type: string
                  example: "14.3"
                jupiter:
                  type: string
                  example: "46.1"
                saturn:
                  type: string
                  example: "29.5"
                uranus:
                  type: string
                  example: "2.4"
                neptune:
                  type: string
                  example: "23.6"
                pluto:
                  type: string
                  example: "43.2"

    SimpleBodygraphResponse:
      type: object
      properties:
        type:
          type: string
          description: "Human Design type: Generator, Manifesting Generator, Projector, Manifestor, or Reflector"
          example: "Generator"
        profile:
          type: string
          description: Profile line combination
          example: "6/2"
        gates:
          type: array
          items:
            type: string
          description: All activated gate numbers
          example: ["20", "34", "10", "57"]
        channels_short:
          type: array
          items:
            type: string
          description: Active channel connections as gate pairs
          example: ["20-34", "10-57"]
        centers:
          type: array
          items:
            type: string
          description: Defined (active) energy centers
          example: ["G", "Sacral", "Spleen", "Throat"]

    StandardErrorResponse:
      type: object
      description: Standard error response envelope
      properties:
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp
        success:
          type: boolean
          example: false
        message:
          type: string
          description: Human-readable error description
        errorCode:
          type: string
          description: Machine-readable error code
        type:
          type: string
          example: ""
        data:
          type: object
          nullable: true
          example: null

paths:
  /bodygraphs:
    post:
      summary: Generate a complete bodygraph
      description: Generates a full Human Design bodygraph chart from birth data and location.
      operationId: generateBodygraph
      security:
        - ApiKeyAuth: []
          GeocodeKeyAuth: []
      tags:
        - Bodygraph
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BodygraphInput"
      responses:
        "200":
          description: Successful bodygraph generation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BodygraphResponse"
        "400":
          description: Invalid input — birthdate, birthtime, or location is malformed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StandardErrorResponse"
        "401":
          description: Authentication failed — API key missing, invalid, or geocode key missing
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StandardErrorResponse"
        "403":
          description: Access denied — user does not have access to this feature
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StandardErrorResponse"
        "404":
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StandardErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StandardErrorResponse"

  /bodygraphs/simple:
    post:
      summary: Generate a simplified bodygraph
      description: Generates a simplified Human Design chart with type, profile, gates, channels, and centers.
      operationId: generateSimpleBodygraph
      security:
        - ApiKeyAuth: []
          GeocodeKeyAuth: []
      tags:
        - Bodygraph
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BodygraphInput"
      responses:
        "200":
          description: Successful simplified bodygraph generation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SimpleBodygraphResponse"
        "400":
          description: Invalid input — birthdate, birthtime, or location is malformed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StandardErrorResponse"
        "401":
          description: Authentication failed — API key missing, invalid, or geocode key missing
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StandardErrorResponse"
        "403":
          description: Access denied — user does not have access to this feature
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StandardErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StandardErrorResponse"