# Freem Agent API

> One API key is the universal credential for every freem product. Create a key, send it as a Bearer token, and call any product API. A key carries a recharge balance (for the LLM gateway) and a per-product subscription level (for product daily quotas).

Auth: Authorization: Bearer sk-...
Get a key: https://api.clssai.com/key (anonymous GET)
Machine-readable spec: https://freem.ai/agents.json
Human guide: https://freem.ai/agents
Runnable examples: https://github.com/gaoym121/freem-agent-examples
MCP server (Streamable HTTP): https://freem.ai/mcp — tools: freem_search, freem_key_balance

## Quickstart
- 1) Get a key — Open https://api.clssai.com/key in a browser — anonymous, instant, and every key carries a $0.10 trial credit (no card required). Signed-in at freem.ai? GET /api/agent/my-keys auto-creates your bound default key.
- 2) Verify the key — see balance & per-product subs: `curl https://freem.ai/api/agent/me -H 'Authorization: Bearer sk-YOURKEY'`
- 3) First model call — OpenAI-compatible gateway: `curl https://clssai.com/v1/chat/completions -H 'Authorization: Bearer sk-YOURKEY' -H 'Content-Type: application/json' -d '{"model":"claude-haiku-4-5","messages":[{"role":"user","content":"hi"}]}'`
- 4) Call a product API — e.g. AI search with sources: `curl -X POST https://freem.ai/api/search -H 'Authorization: Bearer sk-YOURKEY' -H 'Content-Type: application/json' -d '{"query":"what changed in AI agents this week","model":"auto"}'`

## Key model
- recharge balance: Universal pay-as-you-go USD balance. Used ONLY by the LLM gateway (clssai.com/v1, per-token billing). balance = recharge + credit - allocated - consumption.
- subscription level: Per-product tier in key.subs (e.g. { search: 'pro', notebook: 'plus' }). Tiers: free | plus | pro | ent. Gates each product's daily quota. Absent => 'free'. Product APIs are gated by subscription level only (they do not draw down the recharge balance).

## Pricing (USD)
- USD. Every fresh key includes a $0.10 trial credit for the LLM gateway — no card required. Search membership tiers (Stripe, live). Other products gate by the same tier ladder (free/plus/pro/ent); their standalone pricing is published as each product's commerce goes live. LLM gateway is pay-as-you-go per token against the key's recharge balance (model prices via GET /v1/models on the gateway).
- search: plus $25/mo · pro $250/mo · ent $2500/mo (6-month and yearly discounts available)

## Endpoints
### Freem Search / Chat
- POST /api/search [bearer] — { query, model: 'auto'|'pro', stream?: bool, instant?: bool, private?: bool, attachments?: [{dataUrl,mime}] }
- POST /api/follow-up [bearer] — { history:[{role,text}], query, model, stream?, instant?, private? }
- GET /api/job?id= [bearer] — ?id=<jobId>
### Notebooks (Cortex)
- POST /api/notebook/create [bearer] — { title? }
- POST /api/notebook/source/add [bearer] — { notebook_id, type:'url'|'youtube'|'text', content }
- POST /api/notebook/chat [bearer] — { notebook_id, query, source_ids[] }
- POST /api/notebook/generate [bearer] — { notebook_id, kind:'audio'|'video'|'slide_deck'|'infographic'|'report'|'quiz'|... , source_ids[], options }
- GET /api/notebook/artifact?id= [bearer] — ?id=<artifactId>
### Speak (pronunciation)
- GET /api/speak/tts [cookie] — ?text=&voice=&rate=&fmt=wav|mp3
### Account / membership
- GET /api/membership [bearer] — 
- GET /api/agent/me [bearer] — 
### ViaAI — AI Branch (merchant presence)
- POST /api/via/audit [cookie] — { merchant, category, city, facts?, lang:'zh'|'en' }
- POST /api/via/branch [cookie] — { facts:{ name, category, city, tagline, intro, address, phone, hours, price_range, services:[{name,price,desc}], faq:[{q,a}], ... }, lang }
- POST /api/via/keywords [cookie] — { category, city, merchant? }
- GET /via/b/<slug>/facts.json [bearer] — 
### LLM Gateway
- POST https://clssai.com/v1/chat/completions [bearer] — OpenAI-compatible, 100+ models, billed to key balance

## Commerce
- POST /api/agent/keys — Create a fresh key (or a sub-key under a parent). Live & self-serve; signed-in creations bind to your account. IP-rate-limited.
- GET /api/agent/my-keys — List keys bound to the signed-in account; auto-creates and binds a default key on first call.
- POST /api/agent/recharge — Stripe one-time checkout that tops up the key's recharge balance. Disabled until AGENT_COMMERCE is enabled.
- POST /api/agent/subscribe — Stripe subscription that sets key.subs[product] = tier. Disabled until AGENT_COMMERCE is enabled.