US API Reference

Complete reference for GET /v1/us/persona.

Base URL


https://api.personagen.dev

Authentication

API key (recommended)


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

Demo mode


X-Demo: true

Demo mode is rate-limited to 25 requests/hour per IP.

Endpoint

Generate one US persona with 77 dimensions.


GET /v1/us/persona

Query parameters

Parameter	Type	Required	Description
`seed`	string	No	Deterministic seed. Same seed + same route = same output.

Request examples

cURL


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

JavaScript


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

Python


import requests
 
response = requests.get(
  "https://api.personagen.dev/v1/us/persona",
  params={"seed": "test-123"},
  headers={"X-API-Key": "your-api-key-here"}
)
 
data = response.json()

HTTP


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

Success response


{
  "success": true,
  "data": {
    "name": {
      "first_name": "Ava",
      "last_name": "Ramirez"
    },
    "identity": {
      "gender": "female",
      "political_orientation": "liberal"
    },
    "origin": {
      "region": "california",
      "local_area": "los_angeles_county"
    },
    "work": {
      "income_band": "75k_to_100k_usd",
      "occupation_domain": "technology_computing"
    },
    "behavior": {
      "technology_confidence": "confident_advanced_user",
      "interests": ["watching_soccer", "home_improvement", "podcasts"]
    },
    "decisioning": {
      "message_processing_style": "analytical_deliberate",
      "communication_preference": "evidence_data_led",
      "purchase_risk_tolerance": "risk_balanced"
    }
  },
  "metadata": {
    "id": "persona_xxx",
    "version": "1.1.x",
    "generated_at": "2026-03-05T12:00:00.000Z",
    "seed": "test-123",
    "country": "us",
    "usage": {
      "requests_remaining": 4999,
      "reset_date": "2026-04-01T00:00:00.000Z"
    }
  }
}

Status Codes

Success

Status	Description
`200 OK`	Persona generated successfully

Client Errors

Status	Code	Description
`400 Bad Request`	`INVALID_SEED`	Seed parameter is invalid (too long, invalid characters)
`401 Unauthorized`	`MISSING_API_KEY`	No API key or demo header provided
`401 Unauthorized`	`INVALID_API_KEY`	API key is invalid or revoked
`403 Forbidden`	`API_KEY_DISABLED`	API key has been disabled
`429 Too Many Requests`	`RATE_LIMIT_EXCEEDED`	Rate limit exceeded (demo or API key)
`429 Too Many Requests`	`QUOTA_EXCEEDED`	Monthly quota exhausted

Server Errors

Status	Code	Description
`500 Internal Server Error`	`GENERATION_FAILED`	Temporary generation failure
`503 Service Unavailable`	`SERVICE_UNAVAILABLE`	Service temporarily unavailable

Error Response Format


{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please wait before making another request.",
    "details": {
      "retry_after_seconds": 60
    }
  }
}

Error Fields

Field	Type	Description
`code`	string	Machine-readable error code
`message`	string	Human-readable error description
`details`	object	Additional context (optional)

Rate Limit Error Example


{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Demo mode rate limit exceeded. Maximum 10 requests per hour per IP.",
    "details": {
      "retry_after_seconds": 3420,
      "limit": 10,
      "window": "hour"
    }
  }
}

Quota Exceeded Example


{
  "success": false,
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Monthly quota exhausted. Quota resets on 2026-04-01.",
    "details": {
      "reset_date": "2026-04-01T00:00:00.000Z",
      "requests_used": 5000,
      "requests_limit": 5000
    }
  }
}

Rate limits

Demo mode

Limit: 25 requests/hour/IP

API key

Default: 5,000 requests/month/key
Higher limits: request in dashboard

Usage metadata


{
  "metadata": {
    "usage": {
      "requests_remaining": 4999,
      "reset_date": "2026-04-01T00:00:00.000Z"
    }
  }
}

Notes

Route-country is fixed: this endpoint always returns US personas.
Legacy docs URLs redirect to US pages.
Full schema details: US Persona Structure.