REST API

Search the catalog, read a free plan, plan a stack and check a repository over HTTPS. No key needed.

Base URL: https://api.clearvia.app/api/zero. Responses are JSON. No API key is needed. The interactive OpenAPI reference is at api.clearvia.app/docs.

Endpoints

Method and path	Purpose
`GET /categories`	Categories with offer counts and the catalog figures
`GET /offers`	Search and filter free plans
`GET /offers/{slug}`	One free plan with evidence, alternatives and recent changes
`GET /providers/{slug}`	A provider with its free plans
`GET /compare`	Two to four free plans side by side
`GET /changes`	The change feed, newest first (page with `before`)
`GET /stats`	Catalog figures
`GET /catalog`	Every provider and offer with evidence, for offline use
`POST /plan`	Plan a zero-cost stack
`POST /check`	Check a repository's manifests

Add locale=zh-CN to read names, summaries, reasons and risks in Simplified Chinese. Names and summaries always carry both languages; notes come as note (English) and noteZh (Simplified Chinese).

A record whose quotes the daily check can no longer find carries review: { since, fields } until a person has corrected it; otherwise review is null.

Each entry in the change feed has a kind: change when the provider changed its plan, correction when Clearvia corrected its own record. Pass kind=change or kind=correction to GET /changes to keep only one of them; the catalog's "changes in 30 days" figure counts providers' changes only, not corrections or newly listed plans.

Search free plans

curl 'https://api.clearvia.app/api/zero/offers?role=postgres&commercialOnly=true&noIdlePause=true'

Filters: q, category, role, provider, freeType, commercialOnly, noCard, noIdlePause, chinaOk, limit (up to 500) and offset.

q matches every word against names, summaries, plan, provider, category and role, in English and Chinese. Common words stand for catalog terms too: login finds auth services and 大模型 finds model APIs.

Compare free plans

curl 'https://api.clearvia.app/api/zero/compare?offers=neon-free,supabase-free'

offers names two to four plans; the order you give is the order returned. limits lines up limits that measure the same thing over the same period for overlapping roles, one entry per plan (null where a plan states no such limit) with differs set when the allowances differ. differences lists the other facts on which the plans differ, such as overage or flags.idlePauseDays.

Plan a stack

curl -X POST https://api.clearvia.app/api/zero/plan \
  -H 'content-type: application/json' \
  -d '{
    "needs": ["web-app", "postgres", "auth", "transactional-email"],
    "constraints": { "commercial": true, "audience": "global", "noCard": true },
    "scale": { "monthlyActiveUsers": 2000, "databaseGb": 0.3, "emailsPerMonth": 1500 },
    "locale": "en"
  }'

needs takes roles such as static-site, web-app, serverless-functions, postgres, sqlite, redis, queue, object-storage, auth, transactional-email, llm, embeddings, vector-db, search, error-tracking and analytics. Constraints: commercial, audience (global, cn, eea), noCard, noPhone, noIdlePause, noDataTraining. Scale: monthlyActiveUsers, requestsPerMonth, databaseGb, fileStorageGb, bandwidthGbPerMonth, emailsPerMonth, tokensPerMonth. Use prefer and exclude with offer or provider slugs.

The response has zeroCost, one entry per need in picks (choice, alternatives, exclusions), warnings, official setup commands, dataAsOf and a disclosure.

Check a repository

curl -X POST https://api.clearvia.app/api/zero/check \
  -H 'content-type: application/json' \
  -d '{"files":[{"path":"package.json","content":"{\"dependencies\":{\"@supabase/supabase-js\":\"^2\"}}"}],"commercial":true}'

Send .env.example rather than a real .env. Environment values are only used to recognise hosts and are never returned.

Saved stacks

Your organization's saved stacks are under https://api.clearvia.app/api/stacks and need an API key, sent as a bearer token. A key works in its own organization; pass that organization's ID, shown when you make the key.

curl 'https://api.clearvia.app/api/stacks?organizationId=ORG_ID' \
  -H "Authorization: Bearer $CLEARVIA_API_KEY"

Method and path	Purpose	Key access
`GET /api/stacks`	The organization's stacks, each with its health and unseen changes	Read
`GET /api/stacks/{stackId}`	One stack: its request, its plans now and the changes it hasn't seen	Read
`POST /api/stacks`	Save a stack: `organizationId`, `name` and a planner `request`	Read and save

Saving runs the planner on the request, as the console does; the plans always come from the planner. A key that has expired, was revoked or whose owner left the organization gets 401 with a message that says which; asking for another organization's stacks gets 403.

Caching and limits

Reads return an ETag and Cache-Control: public, max-age=60, stale-while-revalidate=86400. Send If-None-Match to get 304 Not Modified while nothing changed. GET /catalog is the efficient way to mirror everything.
Each IP address may make 600 reads and 60 plan or check calls per minute. Above that the API answers 429 with Retry-After.
Errors are JSON with a message. Unknown offers and providers answer 404.

Disclosures

When you show a result that carries commercial.referral: true, show its commercial.disclosure next to the link. Plan and check responses carry a disclosure to show with the results.

Using the data

The API is free to use in your own projects and products, including commercial ones. When you show facts to others, keep each fact's source link and freshness, credit Clearvia with a link to clearvia.app, and don't present the facts as your own verification. Reselling the catalog as a dataset or building a competing catalog from it needs our written agreement. The Terms of Service have the details.

On this page