API & MCP Reference

Overview

The persona endpoint is OpenAI-compatible. If your code already calls chat/completions, point it at Staraze by changing two things — the base URL and the API key — and it will talk to the persona instead of a raw model. Replies are AI-generated by a licensed persona of a real expert and are always disclosed as AI. The persona's training data, prompt, and retrieved knowledge never leave Staraze; you receive replies only.

Get an API key

1. Sign in at Staraze and add funds to your wallet — API usage is billed from this prepaid balance.
2. Open the persona you want to use. When the creator has enabled API access, you'll see a Generate key button.
3. Click it to create a key starting with pk_. It's shown once — copy it somewhere safe. You can rotate or revoke it any time from the same place.

One key is scoped to you + that one persona. Generate a separate key for each persona you use. Treat keys like passwords — never ship them in client-side code.

Authentication

Send your key as a Bearer token in the Authorization header.

Authorization: Bearer pk_your_key_here

There are two kinds of key:

The rest of this guide uses a personal pk_ key.

Quickstart

Your first request — the persona replies to the last user message:

curl https://staraze.com/api/hire/v1/chat/completions \
  -H "Authorization: Bearer pk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "How should I price my first product?" }
    ]
  }'

Chat completions

POST https://staraze.com/api/hire/v1/chat/completions

Request body

Response

Standard OpenAI chat.completion object, plus two Staraze billing fields (on pk_ keys):

{
  "id": "chatcmpl-8f2a…",
  "object": "chat.completion",
  "created": 1737800000,
  "model": "staraze-persona-<botId>",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Start with value-based pricing…" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 572,
    "completion_tokens": 66,
    "total_tokens": 638
  },
  "staraze_charge_usd": 0.00385,   // what this call cost you (pk_ only)
  "staraze_balance_usd": 4.91615   // wallet balance remaining (pk_ only)
}

Conversations & memory

The persona keeps context for your key automatically — you don't have to resend the whole history for it to remember your earlier turns. Standard OpenAI clients send the full messages array and that's fine; the persona simply responds to your latest user message with your prior conversation in mind.

history = [
    {"role": "user", "content": "I run a small coffee brand."},
    {"role": "assistant", "content": "Nice — what's your margin goal?"},
    {"role": "user", "content": "Around 60%. What should I charge?"},
]
resp = client.chat.completions.create(model="staraze-persona", messages=history)
print(resp.choices[0].message.content)

Usage & billing

You're billed per token from your prepaid wallet — you only pay for what you use.

• $5.00 / 1M input tokens  ·  $15.00 / 1M output tokens.
• A typical reply (~3k in + 300 out) costs about $0.02.
• Every response includes usage plus staraze_charge_usd and staraze_balance_usd so you can track spend in real time.
• When your balance reaches $0 the API returns 402 — top up your wallet to continue.
• Part of every charge goes to the creator whose persona you're using.

Use it in Claude (MCP)

Prefer no code? Add the persona as a tool in Claude (or any MCP client) and just talk to it. It exposes one tool, ask_persona, billed exactly like the API. There are two ways to connect.

Option A — Hosted connector (no install)

Point any client that supports remote MCP servers at the hosted URL below — your pk_ key goes in the URL, so no local setup or Node required. This is what claude.ai (browser), Claude Desktop custom connectors, and ChatGPT developer-mode MCP use.

https://staraze.com/api/mcp/pk_your_key_here

In Claude, go to Settings → Connectors → Add custom connector, paste the URL, and choose No authentication (the key is already in the URL). You'll then see an ask_persona tool. Treat this URL like a password — it carries your key; rotate the key on the persona page if it leaks. The key may also be sent as an Authorization: Bearer header instead, if your client supports it.

Option B — Local server (npx)

1. Generate a pk_ key (see Get an API key).
2. Open Claude Desktop → Settings → Developer → Edit Config and add the block below.
3. Restart Claude. An ask_persona tool appears — say things like “ask the persona how to price my product.”

{
  "mcpServers": {
    "staraze": {
      "command": "npx",
      "args": ["-y", "staraze-mcp"],
      "env": {
        "STARAZE_API_KEY": "pk_your_key_here"
      }
    }
  }
}

The local server works in any client that supports stdio MCP servers — point the client's MCP config at npx -y staraze-mcp with your key in the environment. That includes Claude Desktop, Cursor, Cline, Zed, Windsurf, Continue, and others.

ChatGPT & other apps

Because the endpoint is OpenAI-compatible, there are two more ways to use a persona outside of code.

1. Any app with a custom OpenAI endpoint

Many chat apps let you point them at a custom OpenAI-compatible server. Just fill in three fields — no code:

Works in apps like LibreChat, Open WebUI, Jan, Chatbox, TypingMind, BoltAI, and any other “custom OpenAI base URL” client. Look for a Base URL / API host setting.

2. A Custom GPT in ChatGPT (Actions)

In ChatGPT (Plus), create a Custom GPT → Configure → Create new Action, paste the schema below, and set Authentication → API Key → Bearer with your pk_ key. Then just chat with your GPT.

openapi: 3.1.0
info:
  title: Staraze Persona
  version: 1.0.0
servers:
  - url: https://staraze.com/api/hire/v1
paths:
  /chat/completions:
    post:
      operationId: askPersona
      summary: Ask the hired Staraze persona
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [messages]
              properties:
                messages:
                  type: array
                  items:
                    type: object
                    properties:
                      role: { type: string }
                      content: { type: string }
      responses:
        "200": { description: OK }
components:
  securitySchemes:
    bearerAuth: { type: http, scheme: bearer }
security:
  - bearerAuth: []

3. Claude & ChatGPT (as a connector)

claude.ai and ChatGPT won't let you re-point their built-in model at a persona — but you can add the persona as a connector/tool, and then ask for it in normal chat. Use the hosted MCP connector URL (Claude: Settings → Connectors → Add custom connector; ChatGPT: developer-mode MCP), or in ChatGPT the Custom GPT Action shown above.

Grok has no end-user tool/connector option today — use the API from your own code, or one of the custom-endpoint apps above.

Serving your own users

A pk_ key represents one Staraze account and one wallet. That has a direct consequence when you build something on top of it:

• One shared key. If you embed a single pk_ key in an app that many people use, every request bills your one wallet, and you can't tell whose usage is whose. Fine for a personal tool or a prototype; risky for a public app.
• Per-user billing. To charge each of your end-users for their own usage, have each of them sign in to Staraze, fund their own wallet, and generate their own pk_ key. Your app sends each user's request with their key — usage and cost land on their wallet.
• B2B / high volume. If you want to license a persona for a product at scale under one agreement, that's a company hire (hk_ key) — contact us to set up a contract.

Keys are also persona-scoped: one key talks to exactly one persona. Using several personas means one key each.

Errors

Errors use standard HTTP status codes. The body is { "error": "…" }.

FAQ