# PersonaLogic API - LLM-Readable Documentation
# Version: 1.0.0
# Last Updated: 2024-12-25
# Full documentation: /llms-full.txt

## Overview
PersonaLogic provides high-fidelity synthetic personas for market research.
Our API is designed for both AI agents and human developers.

## Quick Start
Base URL: https://api.personalogic.ai/v1
Authentication: Bearer token or API key (X-API-Key header)

## Endpoints

### GET /personas
List all available personas with filtering and pagination.
- Query params: category, fidelity_tier, min_fidelity_score, tags, search, page, per_page
- Credits: 1 per request
- Returns: Array of persona objects with pagination metadata

### GET /personas/{slug}
Get a single persona by its URL-friendly slug.
- Path param: slug (e.g., "urban-millennial-tech")
- Credits: 5-50 depending on fidelity tier
- Returns: Full persona object with demographics, psychographics, and metadata

### POST /personas/{slug}/interview
Conduct a simulated interview with a persona.
- Body: { message: string, context?: { conversation_id, previous_messages } }
- Credits: 10-100 depending on fidelity tier
- Returns: Persona's response with consistency score

## Persona Object Schema
```json
{
  "id": "uuid",
  "slug": "string",
  "name": "string",
  "demographics": {
    "age_range": "[25,35)",
    "gender": "string",
    "location_country": "string",
    "occupation": "string",
    "income_bracket": "string",
    "education_level": "string"
  },
  "psychographics": {
    "interests": ["array"],
    "values": ["array"],
    "pain_points": ["array"],
    "goals": ["array"],
    "communication_style": "string"
  },
  "metadata": {
    "fidelity_tier": "standard|enhanced|premium|ultra",
    "fidelity_score": 0.00-1.00,
    "consistency_token": "ct_xxx",
    "credits_per_query": integer
  }
}
```

## Fidelity Tiers
- standard: 0.60-0.74 score, 5 credits/query
- enhanced: 0.75-0.84 score, 10 credits/query
- premium: 0.85-0.94 score, 25 credits/query
- ultra: 0.95-1.00 score, 50 credits/query

## Billing & Usage Events (Polar Integration)
Usage is tracked via Polar meter events for billing purposes.

### Event: persona_query
Sent when a single persona is queried via GET /personas/{slug}
- name: "persona_query"
- customer_id: Polar customer ID or profile ID
- properties:
  - credits: Number of credits consumed (5, 10, 25, or 50 based on fidelity tier)
  - fidelity_tier: "standard" | "enhanced" | "premium" | "ultra"
  - persona_slug: The slug of the persona queried
  - request_id: Unique request ID for idempotency

### Event: persona_list
Sent when personas are listed via GET /personas
- name: "persona_list"
- customer_id: Polar customer ID or profile ID
- properties:
  - credits: 1 (flat rate for list queries)
  - results_count: Number of personas returned
  - request_id: Unique request ID for idempotency

## Error Handling
- 400: Invalid request parameters
- 401: Authentication required
- 402: Payment required (insufficient credits) - Check X-Payment-Required-URL header
- 404: Persona not found
- 429: Rate limit exceeded - Check Retry-After header

## Rate Limits
- Anonymous: 10/min, 100/day
- Standard: 60/min, 1000/day
- Pro: 300/min, 10000/day
- Enterprise: 1000/min, 100000/day

## Anti-Hallucination Protection
The API detects repeated identical requests (hallucination loops) and returns 429 with reason: "loop".
Agents should vary their queries if encountering this error.

## For AI Agents
1. Always check X-Credits-Remaining header after requests
2. Handle 402 responses by directing users to X-Payment-Required-URL
3. Use consistency_token to verify persona identity across sessions
4. Respect rate limits - check X-RateLimit-Remaining header