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, PAYG billing, usage dashboard endpoints, crawl licensing, and feed-first validation.

Pricing Connect AI OpenAPI

Custom domain

www.xpersona.co

The docs use the same canonical host as production.

Inference

/v1

OpenAI-compatible models, chat completions, pricing, usage, and native opencode routing.

Billing

PAYG

Stripe Checkout starts daily metered usage billing from the pricing page.

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.

Plan quick reference

payg

Daily metered usage. No monthly minimum.

$0/day

starter

1x Starter usage for setup and light coding loops.

$5/mo

builder

8x Starter usage for everyday agent runs.

$10/mo

pro

17x Starter usage for longer repo sessions.

$20/mo

PAYG is metered through Stripe. Usage is recorded only for successful inference calls, settled daily, and shown in the dashboard usage cards.

Native opencode and /v1 inference

Start from /opencode, connect provider xpersona in opencode, select xpersona/xpersona-frieren-coder from /models, or use /v1/models, /v1/chat/completions, /v1/pricing, and /v1/usage directly.

Stripe pay as you go

Start from /pricing or POST /api/v1/me/xpersona-checkout. PAYG checkouts create daily usage subscriptions and successful inference requests report metered Stripe events.

Dashboard usage control

The dashboard shows plan 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/xpersona-frieren-coder "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":"xpersona-frieren-coder","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

OpenAI-compatible model access plus public pricing and authenticated usage telemetry.

GET

/v1/models

List Xpersona model IDs.

Public

POST

/v1/chat/completions

Run frieren-coder.

Bearer API key

GET

/v1/pricing

Retail model price cards.

Public

GET

/v1/usage

Plan, 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 usage billing, creating keys, and monitoring spend.

GET

/opencode

Native OpenCode setup and model catalog.

Public

GET

/pricing

PAYG, Starter, Builder, and Pro plans.

Public

POST

/api/v1/me/xpersona-checkout

Stripe Checkout for PAYG or packages.

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

Packages, 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/openai

OpenAI tool descriptors.

Public

GET

/api/v1/tools/anthropic

Anthropic tool descriptors.

Public

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

ChatGPT-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

getAnthropic tool descriptors

/api/v1/tools/langchain

getLangChain tool descriptors

/api/v1/tools/openai

getOpenAI 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