API reference

Quickstart

The real request, against the real host. Swap in your key (from your dashboard) and go.

curl -X POST https://api.chatpersona.ai/v1/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"persona":{"name":"Nova","coreVoice":"playful, flirty, lowercase texting"},"messages":[{"role":"user","content":"hey, you up?"}],"allow_explicit":false}'

const res = await fetch('https://api.chatpersona.ai/v1/chat', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + apiKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    persona: { name: 'Nova', coreVoice: 'playful, flirty, lowercase texting' },
    messages: [{ role: 'user', content: 'hey, you up?' }],
    allow_explicit: false,
  }),
});

const data = await res.json();
console.log(data.reply);

import requests

res = requests.post(
    "https://api.chatpersona.ai/v1/chat",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "persona": {"name": "Nova", "coreVoice": "playful, flirty, lowercase texting"},
        "messages": [{"role": "user", "content": "hey, you up?"}],
        "allow_explicit": False,
    },
)

data = res.json()
print(data["reply"])

Authentication

Every request to /v1/chat carries your API key as a bearer token:

Authorization: Bearer cp_live_...

Get a key by creating an account — one is issued immediately and shown to you once on your dashboard. Access is invite-only: every new account starts pending and is reviewed by a human before it can call the API. Your key already works the moment you're approved — you never need to regenerate it.

POST /v1/chat

Request body

Total request body cap: 1,048,576 bytes (1MB) — see the messages row below for how this interacts with the per-field limits.

Response body (200)

The persona object

Personas are not stored anywhere. You pass the full persona object inline on every request — the API is completely stateless and retains nothing about your conversation between calls. Continuity comes entirely from the messages array you send: resend as much of the conversation history as you want the model to remember on every call.

Every field below is optional (an empty {} persona is valid), but the more you give the model, the more convincing it is. examples is the single highest-leverage field — a handful of real message pairs teaches voice far better than any amount of adjectives in coreVoice.

Schema fields

Additional voice-signature fields

Not part of the formal schema — passed straight through, and genuinely read by the agent's prompt renderer if present.

A complete, realistic persona

Most fields together, ready to copy into the sandbox or your own request:

{
  "name": "Nova",
  "bio": "27, photographer based on the west coast. Loves hiking, film cameras, and late-night diner runs. Sarcastic but warm once she likes you.",
  "coreVoice": "playful, flirty, a little sarcastic, lowercase texting, quick with a tease but genuinely warm underneath",
  "openers": ["hey stranger 😏", "morning! sleep okay?", "okay I need your opinion on something"],
  "endearments": ["babe", "trouble", "love"],
  "topKinks": ["praise", "lingerie", "roleplay"],
  "bannedWords": ["actually", "moist", "delve"],
  "examples": [
    { "userMessage": "hey what are you up to", "agentResponse": "just got out of the shower lol, thinking about you tbh" },
    { "userMessage": "you always know what to say", "agentResponse": "mm i just say what's true babe" },
    { "userMessage": "i had a rough day", "agentResponse": "come here, tell me what happened. i've got you" }
  ],
  "languages": ["en", "es"],
  "langDefault": "en",
  "locationGuard": "never reveal what city, state, or country you're actually in — deflect playfully if asked",
  "bioFacts": {
    "age": 27,
    "hometown": "Portland, OR",
    "currentCity": "Los Angeles, CA",
    "pets": "one cat named Biscuit",
    "siblings": "younger brother",
    "relationshipStatus": "single"
  },
  "emojiFrequency": "moderate",
  "textingStyle": { "abbreviations": ["lol", "omg", "rn", "tbh"] }
}

Status codes

Precedence: a request that is both over-budget AND over the rate limit always gets 402, never 429 — the credit reserve is checked, and the request turned away, before the rate limit is even evaluated.

Credits & limits

• 1 reply = 1 credit = 2¢.
• New accounts start with 200 free replies — no card required.
• A refusal (flagged:true) still consumes 1 credit — the model still did the work of evaluating the request.
• Default rate limit: 60 requests/minute per API key.
• Total request body cap: 1,048,576 bytes (1MB), across the whole JSON payload — see the request-body table above for how this interacts with the per-field messages limits.

Safety

Adult content is first-class here: set allow_explicit:true (and optionally style.explicitness) and the persona holds frank, explicit conversation without refusing or moralizing.

One hard floor is always enforced, regardless of allow_explicit: content involving minors (or any other illegal material) and bestiality are refused — both on what you send AND on what the model generates (an input check plus an output backstop). A request that trips this returns flagged:true and an in-character decline, never the requested content.