Blueprint Endpoints

Generate complete astrological blueprints with AI interpretations and flexible delivery options.

Complete Blueprint (Modular + AI)

Generate a complete astrological blueprint with flexible module selection and optional AI interpretations per module.

Endpoint

POST /api/v1/generate-blueprint

Pricing

Variable pricing based on selected modules and AI generation

DATA COSTS (charged only for modules that generate successfully — see "Module failures" below):

Astrology data: 1 credit
Human Design data: 2 credits
Numerology data: 1 credit

AI COSTS (only if includeAI[module] === true):

Numerology AI: +26 credits (1 section)
Astrology AI: +500 credits (19 sections)
Human Design AI: +370 credits (14 sections)

Examples:

Data only (all modules, no AI): 4 credits (1+2+1)
Astrology data + AI: 501 credits (1+500)
All modules + Astrology AI only: 504 credits (1+2+1+500)
All modules + ALL AI: 900 credits (1+2+1+26+500+370)

Request Body

{
  "fullName": "John Doe",           // Required
  "birthDate": "1990-12-25",        // Required: YYYY-MM-DD
  "birthTime": "14:30",              // Required: HH:MM (24h)
  "city": "New York",                // Required
  "country": "USA",                  // Required
  "latitude": 40.7128,               // Required
  "longitude": -74.0060,             // Required
  "timezone": "America/New_York",    // Required
  "modules": {                       // Required
    "astrology": true,               // 1 credit data
    "humanDesign": true,             // 2 credits data
    "numerology": true               // 1 credit data
  },
  "includeAI": {                     // Optional: per-module AI generation
    "astrology": true,               // +500 credits (19 AI sections)
    "humanDesign": false,            // Skip AI for this module
    "numerology": false              // Skip AI for this module
  }
}

Note on includeAI:

If omitted, NO AI is generated — only data costs apply
AI is generated ONLY for modules where includeAI[module] === true
Each module generates a fixed number of AI sections (cannot select individual sections)
Field name is case-sensitive: includeAI (capital AI), not includeAi

Module failures:

Each selected module is generated independently. If a module fails (e.g. the external Human Design data provider is unavailable), the response still returns HTTP 200 with the modules that succeeded; the failed module is not delivered (data.humanDesign: null) and not charged.
meta.creditsUsed (and the X-Credits-Used header) reflect only the modules that were actually delivered, never the full requested cost.
Failures are reported in meta.modulesFailed (array of module names, e.g. ["Human Design"]) and meta.warnings (object mapping module key → error message, e.g. {"humanDesign": "Failed to fetch Human Design data: ..."}).
meta.modulesRequested lists the modules the caller asked for, meta.modulesIncluded the ones actually delivered.

What's Included

Astrology Module DATA (1 credit):

✓ Complete natal chart with all planetary positions
✓ 12 house cusps and placements
✓ Major and minor aspects
✓ Ascendant, Midheaven, North/South Nodes, Chiron, Lilith, Part of Fortune

Astrology Module AI (+500 credits if enabled):

✓ 19 AI-generated sections including: Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto, Chiron, Ascendant, IC, Descendant, Midheaven, Lilith, North Node, South Node, Part of Fortune
✓ +500 credits total (all 19 sections bundled)

Human Design Module DATA (2 credits):

✓ Type, Strategy, Authority
✓ 9 Energy Centers (defined/undefined)
✓ Gates and Channels
✓ Profile Line
✓ Definition and Split
✓ Incarnation Cross, Motivation, Perspective

Human Design Module AI (+370 credits if enabled):

✓ 14 AI-generated sections including: Type, Strategy, Authority, Profile, Definition, Incarnation Cross, Signature, Motivation, Perspective, Digestion, Environment, Design Sense, Defined Centers, Undefined Centers
✓ +370 credits total (all 14 sections bundled)

Numerology Module DATA (1 credit):

✓ Life Path Number
✓ Expression Number
✓ Soul Urge Number
✓ Personal Year/Month/Day cycles

Numerology Module AI (+26 credits if enabled):

✓ 1 AI-generated section: Life Path Number interpretation
✓ +26 credits total

Response Format

{
  "success": true,
  "data": {
    "astrology": {
      "celestialBodies": {
        "sun": { "sign": "Sagittarius", "longitude": 255.3, "house": 10 },
        "moon": { "sign": "Cancer", "longitude": 105.7, "house": 4 },
        /* ... all planets, nodes, points */
      },
      "houses": {
        "1": { "sign": "Pisces", "longitude": 340.2 },
        /* ... all 12 houses */
      },
      "aspects": [
        { "planet1": "sun", "planet2": "moon", "type": "trine", "orb": 2.1 }
        /* ... all aspects */
      ]
    },
    "humanDesign": {
      "type": "Generator",
      "strategy": "Respond",
      "authority": "Sacral",
      "profile": "3/5",
      "centers": { /* 9 centers with defined/undefined */ },
      "channels": [ /* activated channels */ ],
      "gates": [ /* activated gates */ ]
    },
    "numerology": {
      "lifePathNumber": 9,
      "expressionNumber": 5,
      "soulUrgeNumber": 3,
      "personalYear": 7,
      "personalMonth": 2,
      "personalDay": 15
    },
    "aiContent": {
      "personality": "Your Sun in Sagittarius in the 10th house...",
      "emotions": "Your Moon in Cancer in the 4th house...",
      "lifePathNumber": "As a Life Path 9...",
      /* ... AI sections for enabled modules only */
    },
    "birthInfo": {
      "fullName": "John Doe",
      "date": "1990-12-25",
      "time": "14:30",
      "location": "New York, USA"
    }
  },
  "meta": {
    "creditsUsed": 384,                 // actual charge — only delivered modules
    "creditsRemaining": 1616,
    "modules": {
      "astrology": true,
      "humanDesign": true,
      "numerology": true
    },
    "modulesRequested": ["Astrology", "Human Design", "Numerology"],
    "modulesIncluded": ["Astrology", "Human Design", "Numerology"],
    "modulesFailed": [],                 // names of modules that errored ([] when all ok)
    "warnings": {},                      // module -> error message, {} when all ok
    "aiModules": {
      "astrology": true,
      "humanDesign": false,
      "numerology": false
    },
    "aiModulesIncluded": ["Astrology"],
    "sectionsGenerated": 19
  }
}

Use Cases

Developer Integration (Data Only - 4 credits):

Get raw astrological data for custom interpretations
All three modules without AI content
Build your own UI/visualization layer
Maximum cost efficiency

Single Module Data (1-2 credits):

Astrology-only data: 1 credit
Human Design-only data: 2 credits
Numerology-only data: 1 credit

Selective AI Generation (27-504 credits):

Choose which modules get AI interpretations
Examples:
- Numerology data + AI: 27 credits (1+26)
- Astrology data + AI: 501 credits (1+500)
- All data + Numerology AI only: 30 credits (4+26)
- All data + Astrology AI only: 504 credits (4+500)

Complete Package (900 credits):

All 3 modules + all AI interpretations
34 total AI sections (1 numerology + 19 astrology + 14 human design)
Comprehensive astrological profile
Ready-to-present content

Export Blueprint as PDF

Export an existing blueprint as a PDF document. The blueprint must belong to the user who owns the API key and must be in completed status.

Endpoint

POST /api/v1/blueprint/pdf

Pricing

0 credits — PDF export is free.

Request Body

{
  "blueprintId": "cmlf5lezs006zhezfkgpqex4z"
}

Field	Type	Required	Description
`blueprintId`	string	Yes	ID of the blueprint to export (must belong to your account)

Response

Returns a binary PDF file.

Header	Value
`Content-Type`	`application/pdf`
`Content-Disposition`	`attachment; filename="blueprint-john-doe.pdf"`

Example

curl -X POST https://mycosmicadvisor.com/api/v1/blueprint/pdf \
  -H "Authorization: Bearer bgapi_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"blueprintId": "cmlf5lezs006zhezfkgpqex4z"}' \
  -o blueprint.pdf

Error Responses

{ "error": "Missing required field: blueprintId" }

{ "error": "Blueprint not found" }

{ "error": "Blueprint is not ready or has no content" }

Error Responses

{
  "error": "Invalid module selection",
  "message": "modules must include numerology, astrology, and/or humanDesign flags"
}

{
  "error": "Insufficient credits",
  "message": "Modular blueprint costs 384 credits. Please purchase more credits to use the API.",
  "required": 384,
  "available": 150,
  "modulesRequested": ["Astrology", "Human Design", "Numerology"]
}