HumanDesign.ai Logo
Get Started
Back to Blog
DevelopersFeb 21, 20269 min read

How to Build a Custom GPT with the Human Design API

By HumanDesign.ai Team
Featured image for How to Build a Custom GPT with the Human Design API

Learn how to build a Custom GPT in ChatGPT that can generate Human Design charts, or use the same Human Design API in your own AI application with a current OpenAI stack.

What you’ll build

By the end of this tutorial, you will have one of two things:

  • A Custom GPT inside ChatGPT that can collect birth data, call the Human Design API, and explain the results clearly
  • A clear path for using the same Human Design API inside your own AI product if you are building beyond ChatGPT

The Human Design API can help you:

  • Generate natal Human Design charts from birth data
  • Look up locations and timezones
  • Run compatibility or composite analysis when your plan supports it
  • Return structured chart data that your GPT or app can interpret for users

All of this runs on the Human Design API.

Choose the right build path first

One reason this topic gets confusing is that people use “Custom GPT” to describe two different things.

Path A: Custom GPT in ChatGPT

This is the fastest path if you want a GPT that lives inside ChatGPT. You configure instructions, suggested prompts, knowledge, and custom actions in the GPT builder at chatgpt.com/create or chatgpt.com/gpts/editor.

Use this path when you want a no-code or low-code assistant that works inside ChatGPT.

Path B: AI assistant inside your own app

This is not the same thing as a Custom GPT. If you are building your own product, backend, or internal tool, use the Human Design API directly and pair it with OpenAI’s current API stack. For new OpenAI-based assistant builds, use the Responses API rather than starting a new integration on the deprecated Assistants API.

This tutorial focuses first on Path A, then shows how to think about Path B at the end.

What you need

  • An active Human Design API account from humandesignapi.com/pricing
  • Your API key from the Human Design API dashboard
  • A ChatGPT account with GPT creation access if you are building inside ChatGPT. OpenAI’s current GPT creation guide is here: Creating a GPT
  • Optional: an OpenAI API account if you also want to build an app version

Important: plan names, limits, and feature access can change over time. Check the current Human Design API pricing page before hard-coding tier assumptions into your product.

Step 1: Test the Human Design API first

Before touching ChatGPT, make sure your Human Design API key works.

Try a simple request from your terminal:

curl "https://api.humandesign.ai/hd-data?api_key=YOUR_API_KEY&date=1990-01-15T14:30:00&timezone=America/New_York&location=New%20York,%20NY"

If your key and inputs are valid, you should get chart data back as JSON.

This matters because it separates API problems from GPT setup problems. If the direct API call fails, fix that first.

If you do not know the timezone yet

Use the location endpoint first so your chart call is based on a reliable timezone lookup.

curl "https://api.humandesign.ai/locations?api_key=YOUR_API_KEY&location=New%20York,%20NY"

Once you confirm the location and timezone, use that data in your chart request.

Step 2: Create the GPT in ChatGPT

Go to chatgpt.com/create or open chatgpt.com/gpts/editor.

From there:

  1. Create a new GPT
  2. Give it a clear name, such as Human Design Chart Guide
  3. Add a short description so users know it can generate charts from birth data
  4. Use the Configure tab for stable instructions and actions

If you plan to publish it publicly, review OpenAI’s current publishing requirements here: Building and publishing a GPT.

Step 3: Write better instructions than “be a Human Design expert”

Most GPTs fail because the instructions are vague. Give your GPT a narrow job and a clear interaction pattern.

You can start with something like this:

You are a Human Design assistant powered by the Human Design API.

When a user wants a chart reading:
1. Collect the required birth data: date, exact time if available, and birthplace.
2. If timezone or location is unclear, resolve it before attempting chart generation.
3. Call the Human Design API action with the user's data.
4. Explain the result in plain language.
5. Focus first on Type, Strategy, Authority, Profile, and the clearest practical takeaways.

Rules:
- Ask follow-up questions when birth details are incomplete.
- Never invent chart data.
- Keep explanations beginner-friendly unless the user asks for technical depth.
- Avoid medical, legal, or fatalistic claims.
- If the user wants compatibility or transit features, use only endpoints their setup actually supports.

Suggested conversation starters:

  • “Generate my Human Design chart from my birth details”
  • “Help me understand my Type, Strategy, and Authority”
  • “Compare two charts for compatibility”
  • “Look up the timezone for my birthplace before building my chart”

Step 4: Add the Human Design API as a custom action

This is the part that makes the GPT useful instead of decorative.

For a GPT action, prefer header-based authentication rather than putting your API key into every query string. If your setup allows it, configure an API key auth header using X-API-Key.

Here is a minimal OpenAPI schema for chart generation and location lookup:

{
  "openapi": "3.1.0",
  "info": {
    "title": "Human Design API",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.humandesign.ai"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  },
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/hd-data": {
      "get": {
        "operationId": "generateHumanDesignChart",
        "summary": "Generate a Human Design chart from birth data",
        "parameters": [
          {
            "name": "date",
            "in": "query",
            "required": true,
            "description": "Birth date/time in ISO 8601 format",
            "schema": { "type": "string" }
          },
          {
            "name": "timezone",
            "in": "query",
            "required": false,
            "schema": { "type": "string" }
          },
          {
            "name": "location",
            "in": "query",
            "required": false,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Human Design chart response"
          }
        }
      }
    },
    "/locations": {
      "get": {
        "operationId": "lookupLocation",
        "summary": "Resolve a location and timezone",
        "parameters": [
          {
            "name": "location",
            "in": "query",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Location and timezone response"
          }
        }
      }
    }
  }
}

If your plan includes other endpoint groups, add them as separate actions instead of stuffing everything into one giant schema.

Why smaller action sets work better

When you expose too many tools at once, the GPT can make weaker decisions about which one to call. A small, explicit toolset usually leads to more reliable behavior.

Step 5: Test the GPT with real user prompts

Do not stop after the schema validates. Test actual conversations.

Good tests include:

  • A user who gives complete birth data
  • A user who is missing a birth time
  • A user who gives an ambiguous location
  • A user who asks for beginner-friendly interpretation
  • A user who asks for compatibility or advanced analysis

Watch for these common problems:

  • The GPT invents missing chart details instead of asking a follow-up question
  • The GPT explains Human Design in jargon before the user has context
  • The GPT calls chart endpoints before resolving the location
  • The GPT over-explains every gate and channel when the user wanted a simple overview

Refine the instructions whenever you see the same failure pattern twice.

If you are building your own app instead of a ChatGPT GPT

If your real goal is an embedded assistant in your own product, do not force the ChatGPT GPT workflow into that job.

For new OpenAI-based app assistants, use the Responses API. OpenAI has deprecated the Assistants API and published a migration path away from it. If you are starting fresh, build on the current stack.

Your architecture usually looks like this:

  1. User submits birth data in your app
  2. Your backend validates and normalizes the input
  3. Your backend calls the Human Design API
  4. You pass structured chart data into your OpenAI prompt or tool flow
  5. The model explains the results in your chosen tone and format

In many products, the cleanest approach is to call the Human Design API from your own backend first, then give the model the returned chart data. That keeps your API key server-side and makes debugging much easier.

Simple Python example

import os
import requests

response = requests.get(
    "https://api.humandesign.ai/hd-data",
    headers={"X-API-Key": os.environ["HUMAN_DESIGN_API_KEY"]},
    params={
        "date": "1990-01-15T14:30:00",
        "timezone": "America/New_York",
        "location": "New York, NY",
    },
    timeout=30,
)

response.raise_for_status()
chart = response.json()
print(chart["type"], chart["authority"], chart["profile"])

Simple JavaScript example

const response = await fetch("https://api.humandesign.ai/hd-data?date=1990-01-15T14:30:00&timezone=America/New_York&location=New%20York,%20NY", {
  headers: {
    "X-API-Key": process.env.HUMAN_DESIGN_API_KEY
  }
});

if (!response.ok) {
  throw new Error(`Human Design API error: ${response.status}`);
}

const chart = await response.json();
console.log(chart.type, chart.authority, chart.profile);

Then send the structured result into your OpenAI prompt flow instead of asking the model to guess what the chart should be.

Best practices

  • Keep secrets server-side. Do not expose your Human Design API key in client-side code.
  • Use the location endpoint when birth data is fuzzy. Timezone mistakes create chart mistakes.
  • Start with beginner outputs. Most users want Type, Strategy, Authority, and practical interpretation first.
  • Gate advanced endpoints carefully. Only advertise features your current plan supports.
  • Do not treat old OpenAI UI steps as evergreen. Recheck GPT creation and publishing docs periodically.

Troubleshooting

Action validates but never gets called

Your instructions may not clearly tell the GPT when to use the action. Be explicit about required inputs and when the tool should fire.

Location errors

Run the location lookup first and confirm the timezone before generating the chart.

Authentication problems

If possible, use header-based auth with X-API-Key. If you are testing with query parameters, confirm the key is exactly correct.

Publishing issues

If you publish a GPT that uses custom actions, review OpenAI’s current publishing requirements for domain verification and privacy policy expectations.

Next steps

Once the basic chart flow works, you can expand carefully:

  • Add compatibility analysis if your plan supports composite endpoints
  • Add higher-detail chart endpoints for richer interpretation
  • Create separate GPTs for beginner readings, relationship work, or practitioner workflows
  • Move the same API workflow into your own product when you outgrow the ChatGPT builder

If you are just getting started, keep the first version narrow. A GPT that reliably builds a chart and explains the basics is much more useful than a bloated GPT that claims to do everything and calls tools inconsistently.

How to Build a Custom GPT with the Human Design API | HumanDesign.ai Blog