API Reference

Complete technical specification for the PersonaGen API. This reference covers all endpoints, parameters, responses, and error handling.

Base URL


https://api.personagen.dev

Authentication

PersonaGen supports two authentication methods:

API Key Authentication (Recommended)

Include your API key in the X-API-Key header:


X-API-Key: your-api-key-here

Demo Mode

For testing without an account, use demo mode:


X-Demo: true

Demo mode is rate-limited to 10 requests per hour per IP address.

Endpoints

Generate Persona

Generate a single synthetic persona with 62 dimensions.

Endpoint: GET /v1/persona

Parameters

Parameter	Type	Required	Description
`seed`	string	No	Optional seed for reproducible persona generation. Same seed always produces the same persona.

Request Examples

cURL


# With API key
curl -X GET "https://api.personagen.dev/v1/persona" \
  -H "X-API-Key: your-api-key-here"
 
# With seed parameter
 
curl -X GET "https://api.personagen.dev/v1/persona?seed=test-123" \
 -H "X-API-Key: your-api-key-here"
 
# Demo mode
 
curl -X GET "https://api.personagen.dev/v1/persona" \
 -H "X-Demo: true"

JavaScript


// With API key
const response = await fetch('https://api.personagen.dev/v1/persona', {
  headers: {
    'X-API-Key': 'your-api-key-here'
  }
});
 
// With seed parameter
const response = await fetch('https://api.personagen.dev/v1/persona?seed=test-123', {
  headers: {
    'X-API-Key': 'your-api-key-here'
  }
});
 
// Demo mode
const response = await fetch('https://api.personagen.dev/v1/persona', {
  headers: {
    'X-Demo': 'true'
  }
});
 
const data = await response.json();

Python


import requests
 
# With API key
 
headers = {'X-API-Key': 'your-api-key-here'}
response = requests.get('https://api.personagen.dev/v1/persona', headers=headers)
 
# With seed parameter
 
params = {'seed': 'test-123'}
response = requests.get('https://api.personagen.dev/v1/persona',
headers=headers, params=params)
 
# Demo mode
 
headers = {'X-Demo': 'true'}
response = requests.get('https://api.personagen.dev/v1/persona', headers=headers)
 
data = response.json()

HTTP


GET /v1/persona HTTP/1.1
Host: api.personagen.dev
X-API-Key: your-api-key-here
 
GET /v1/persona?seed=test-123 HTTP/1.1
Host: api.personagen.dev
X-API-Key: your-api-key-here
 
GET /v1/persona HTTP/1.1
Host: api.personagen.dev
X-Demo: true

Response Format

Success Response (200 OK)


{
  "success": true,
  "data": {
    "name": {
      "first_name": "Fabio",
      "last_name": "Tompkins"
    },
    "demographics": {
      "gender": "male",
      "ethnicity": "white",
      "country_of_birth": "united_states",
      "immigration_status": "us_born_third_generation_plus",
      "location": "indiana",
      "geographic_context": "metropolitan_urban",
      "parents_education": "bachelor_degree",
      "childhood_ses": "lower_middle",
      "education": "master_degree",
      "occupational_background": "technology_computing",
      "employment_status": "employed_full_time",
      "income": "50k_to_75k",
      "languages": ["english"],
      "age": 35,
      "birth_year": 1990,
      "birthday": "1990-06-02"
    },
    "psychology": {
      "literacy_level": "proficient",
      "big_five_openness": "average_openness",
      "big_five_conscientiousness": "above_average_conscientiousness",
      "big_five_extraversion": "above_average_extraversion",
      "big_five_agreeableness": "above_average_agreeableness",
      "big_five_neuroticism": "high_neuroticism",
      "iq": 102
    },
    "lifestyle": {
      "sexual_orientation": "heterosexual",
      "relationship_status": "single_never_married",
      "number_of_children": 0,
      "religious_identity": "christian_other",
      "english_proficiency": "native_speaker",
      "political_leaning": "establishment_liberal",
      "has_pets": true,
      "has_criminal_history": false,
      "has_been_married": false,
      "has_been_divorced": false,
      "has_military_experience": false,
      "homeownership_status": "own_with_mortgage",
      "housing_type": "condominium",
      "activity_level": "insufficiently_active",
      "debt_level": "5k_to_25k",
      "technology_comfort": "advanced_user",
      "primary_transportation_method": "personal_vehicle",
      "dietary_restrictions": ["low_sodium"],
      "health_conditions": ["hypertension"],
      "interests": [
        "biographies",
        "watching_baseball",
        "nature_documentaries",
        "astrology",
        "internet_culture",
        "dancing",
        "personal_finance",
        "snowboarding",
        "home_organization",
        "podcasts",
        "sports_betting"
      ]
    },
    "physical": {
      "skin_tone": "porcelain",
      "body_build": "overweight",
      "nose_shape": "button",
      "face_shape": "round",
      "hair": {
        "color": "dark_brown",
        "texture": "type_1_straight"
      },
      "eyes": {
        "color": "medium_brown",
        "shape": "downturned"
      },
      "height": {
        "cm": 174,
        "feet_and_inches": "5'9\""
      },
      "weight": {
        "kg": 91,
        "lbs": 201,
        "bmi": 30.1
      },
      "clothing_sizes": {
        "shirt_size": "XXL",
        "pant_size": "44",
        "shoe_size_us": "8.5"
      },
      "physical_description": "A middle-aged male, 5 feet 9 inches tall, with a heavyset build, straight dark brown hair, downturned medium brown eyes, and porcelain skin."
    }
  },
  "metadata": {
    "id": "persona_1757411127267",
    "version": "1.0",
    "generated_at": "2025-09-09T09:45:27.414Z",
    "seed": "1757411127267_69173660759138",
    "usage": {
      "requests_remaining": 22,
      "reset_date": "2025-09-09T10:37:35.656Z"
    }
  }
}

Error Handling

PersonaGen uses standard HTTP status codes and returns detailed error information.

Error Response Format


{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      // Additional error-specific details
    }
  }
}

HTTP Status Codes

Status Code	Description
`200`	Success
`401`	Unauthorized (invalid or missing API key)
`429`	Too Many Requests (rate limit exceeded)
`500`	Internal Server Error

Error Codes

`RATE_LIMIT_EXCEEDED`

You’ve exceeded your rate limit.

HTTP Status: 429


{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again later.",
    "details": {
      "limit": 1000,
      "window": "1 month",
      "reset_time": "2025-02-01T00:00:00Z"
    }
  }
}

`INVALID_API_KEY`

Your API key format is invalid.

HTTP Status: 429


{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key format.",
    "details": {
      "retry_after": "0s"
    }
  }
}

`API_KEY_NOT_FOUND`

Your API key doesn’t exist or was revoked.

HTTP Status: 401


{
  "success": false,
  "error": {
    "code": "API_KEY_NOT_FOUND",
    "message": "API key not found or has been revoked.",
    "details": {}
  }
}

`API_KEY_LIMIT_EXCEEDED`

Your API key has exceeded its monthly limit.

HTTP Status: 429


{
  "success": false,
  "error": {
    "code": "API_KEY_LIMIT_EXCEEDED",
    "message": "Monthly request limit exceeded for this API key.",
    "details": {
      "limit": 1000,
      "reset_time": "2025-02-01T00:00:00Z"
    }
  }
}

`GENERATION_FAILED`

Temporary server error during persona generation.

HTTP Status: 500


{
  "success": false,
  "error": {
    "code": "GENERATION_FAILED",
    "message": "Failed to generate persona. Please try again.",
    "details": {
      "retry_after": "1s"
    }
  }
}

Rate Limits

Demo Mode

Limit: 10 requests per hour
Window: 1 hour
Scope: Per IP address

API Key

Default Limit: 1000 requests per month
Window: Monthly (resets on key creation anniversary)
Scope: Per API key
Upgrades: Available through your dashboard

Rate Limit Headers

PersonaGen includes rate limiting information in response metadata:


{
  "metadata": {
    "usage": {
      "requests_remaining": 999,
      "reset_date": "2025-02-01T00:00:00Z"
    }
  }
}

Response Headers

PersonaGen returns standard HTTP headers:


HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2048
Cache-Control: no-cache

SDK & Libraries

Official SDKs: Currently, PersonaGen provides a simple REST API that works with any HTTP client. Official TypeScript and Python SDKs are planned based on user demand.

For now, use standard HTTP libraries:

JavaScript/TypeScript: fetch(), axios, node-fetch
Python: requests, httpx, urllib
cURL: Command-line testing
Postman: API testing and development