Developer documentation

Docs for inference, billing, and agent validation

Current production base is https://www.xpersona.co. Use this page for native OpenCode setup, Xpersona /v1 inference, monthly packages and PAYG billing, usage dashboard endpoints, crawl licensing, and feed-first validation.

Start at $20 Connect AI OpenAPI

Packages

$20 / $100 / $200

Fixed monthly capacity with no surprise overage billing.

Inference

/v1

Xpersona /v1 models, chat completions, pricing, usage, and native OpenCode routing.

OpenCode

Native

Choose Xpersona from the provider picker and paste a setup key.

410

Retired search surfaces point crawlers to feed-based replacements.

Recommended AI flow

1) /api/v1/feeds/agents/latest -> 2) /snapshot -> 3) /contract + /trust -> then decide

Step 1

Discover from feeds

Start with latest, benchmarked, security-reviewed, or openapi-ready feed views.

Step 2

Inspect evidence

Read snapshot, contract, trust, card, and facts before acting.

Step 3

Run or recommend

Use /v1 inference after a signed-in user has an active plan and API key.

Package quick reference

Builder

3.5M tokens each month.

$20/month

Pro

17.5M tokens each month.

$100/month

Studio

70M tokens each month.

$200/month

PAYG

Flexible usage billing remains available.

24h trial

Stripe manages packages and PAYG. Package requests pause at the monthly allowance; PAYG remains uncapped and reports successful usage.

Native OpenCode and /v1 inference

Start from /opencode, connect provider xpersona in OpenCode, select xpersona/claude-fable-5 from /models, or use /v1/models, /v1/chat/completions, /v1/pricing, and /v1/usage directly.

Three fixed monthly packages

Builder, Pro, and Studio provide 3.5M, 17.5M, and 70M monthly tokens. Package requests pause at the allowance instead of creating overage charges.

Dashboard usage control

The dashboard shows PAYG billing state, API key prefix, monthly spend, cycle usage, token totals, latency, recent requests, and the retail price card.

Crawl licensing

Crawler integrations can buy prepaid crawl credits, reveal one-time xpcrawl keys, exchange keys for short-lived crawl tokens, and check status.

Copy-paste examples

Use the current production API

Auth uses $XPERSONA_API_KEY.

List models

curl -s "https://www.xpersona.co/v1/models"

OpenCode native setup

export XPERSONA_API_KEY='xp_your_key'
opencode models xpersona --refresh --verbose
opencode run -m xpersona/claude-fable-5 "Reply with exactly: XPERSONA_OK"
opencode

Chat completions

curl -s "https://www.xpersona.co/v1/chat/completions" \
  -H "Authorization: Bearer $XPERSONA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-fable-5","messages":[{"role":"user","content":"Ship a tiny Next.js route"}],"reasoning":{"effort":"xhigh"}}'

Pricing

curl -s "https://www.xpersona.co/v1/pricing"

Usage

curl -s "https://www.xpersona.co/v1/usage" -H "Authorization: Bearer $XPERSONA_API_KEY"

Latest agent feed

curl -s "https://www.xpersona.co/api/v1/feeds/agents/latest"

Agent evidence

curl -s "https://www.xpersona.co/api/v1/agents/my-agent-slug/snapshot"
curl -s "https://www.xpersona.co/api/v1/agents/my-agent-slug/contract"
curl -s "https://www.xpersona.co/api/v1/agents/my-agent-slug/trust"

Crawl-license info

curl -s "https://www.xpersona.co/api/v1/crawl-license"

Inference and usage

Xpersona /v1 model access plus public pricing and authenticated usage telemetry.

GET

/v1/models

List Xpersona model IDs.

Public

POST

/v1/chat/completions

Run Claude Fable 5.

Bearer API key

GET

/v1/pricing

Retail model price cards.

Public

GET

/v1/usage

Billing, limits, spend, and recent calls.

Bearer API key

GET

/api/v1/inference/pricing

Versioned pricing alias.

Public

GET

/api/v1/inference/usage

Versioned usage alias.

Bearer API key

Billing and dashboard

The customer path for starting the PAYG trial, creating keys, and monitoring spend.

GET

/opencode

Native OpenCode setup and model catalog.

Public

GET

/pricing

24-hour PAYG trial.

Public

POST

/api/v1/me/xpersona-checkout

Stripe Checkout for PAYG trial billing.

Signed-in user

GET

/dashboard/connect-ai

Native OpenCode setup and API key flow.

Signed-in user

GET

/dashboard

Usage, billing, model access, and recent requests.

Signed-in user

Agent discovery and validation

The replacement flow for retired search endpoints: feed first, then evidence endpoints.

GET

/api/v1/feeds/agents/{view}

latest, benchmarked, security-reviewed, openapi-ready, recent-updates.

Public

GET

/api/v1/agents/{slug}/snapshot

Stable summary for extraction.

Public or crawl token

GET

/api/v1/agents/{slug}/contract

Capability and integration contract.

Public or crawl token

GET

/api/v1/agents/{slug}/trust

Verification and reliability signals.

Public or crawl token

GET

/api/v1/agents/{slug}/card

Compact agent card.

Public

GET

/api/v1/agents/{slug}/facts

Fact-level citation surface.

Public

Crawler and tool integrations

Machine-readable entrypoints for crawlers, tools, and LLM framework adapters.

GET

/api/v1/crawl-license

Credit options, token transport, and gated surfaces.

Public

POST

/api/v1/crawl-license/checkout

Prepaid Stripe Checkout for crawl credits.

Public

POST

/api/v1/crawl-license

Exchange API key for a crawl token.

xpcrawl key

GET

/api/v1/tools/langchain

LangChain tool descriptors.

Public

Machine-readable docs

Files and schemas intended for autonomous clients and crawlers.

GET

/api/v1/openapi/ai-public

Curated AI-facing OpenAPI schema.

Public

GET

/api/v1/openapi/public

Broader public OpenAPI schema.

Public

GET

/llms.txt

Short guidance for LLM clients.

Public

GET

/llms-full.txt

Expanded machine guidance.

Public

GET

/chatgpt.txt

Agent-focused entrypoint.

Public

Live schema snapshot

26 AI/public paths loaded

Public OpenAPI JSON AI OpenAPI JSON

/api/v1/agents/{slug}

deleteDELETE /api/v1/agents/{slug}

getGET /api/v1/agents/{slug}

patchPATCH /api/v1/agents/{slug}

/api/v1/agents/{slug}/card

getGET /api/v1/agents/{slug}/card

/api/v1/agents/{slug}/contract

getGET /api/v1/agents/{slug}/contract

/api/v1/agents/{slug}/facts

getGET /api/v1/agents/{slug}/facts

/api/v1/agents/{slug}/snapshot

getGET /api/v1/agents/{slug}/snapshot

/api/v1/agents/{slug}/trust

getGET /api/v1/agents/{slug}/trust

/api/v1/chat/completions

postCreate a chat completion

/api/v1/crawl-license

getDescribe crawl licensing

postExchange crawl API key for token

/api/v1/crawl-license/checkout

postCreate crawl-license Checkout session

/api/v1/crawl-license/render-agent/{slug}

getRender gated agent page with crawl license

/api/v1/crawl-license/reveal

postReveal crawl API key after checkout

/api/v1/crawl-license/rotate-key

postRotate crawl API key

/api/v1/crawl-license/status

getGet crawl-license status

/api/v1/feeds/agents/{view}

getGET /api/v1/feeds/agents/{view}

/api/v1/inference/pricing

getGet Xpersona inference pricing

/api/v1/inference/usage

getGet Xpersona inference usage

/api/v1/me/xpersona-checkout

postCreate Xpersona Stripe Checkout session

/api/v1/models

getList Xpersona inference models

/api/v1/tools/anthropic

getSchema-tool descriptors

/api/v1/tools/langchain

getLangChain tool descriptors

/api/v1/tools/openai

getFunction-tool descriptors

/context/v1

getGET /context/v1

/v1/chat/completions

postCreate a chat completion

/v1/models

getList Xpersona inference models

/v1/pricing

getGet Xpersona inference pricing

/v1/usage

getGet Xpersona inference usage