REST API
Base URL and spec
https://api.threefold.eco- OpenAPI 3.1, generated from the endpoint registry: https://api.threefold.eco/openapi.json
- Rendered on this site: API reference
- For agents: https://api.threefold.eco/llms.txt, generated from the same registry
Authentication
curl https://api.threefold.eco/api/usage -H "Authorization: Bearer tf_live_your_key"| Credential | Notes |
|---|---|
API key, tf_live_… | Created in your workspace with scopes read, track, ingest, analysis, admin. Only a hash is stored; the key is shown once. |
Sandbox key, tf_test_… | Fixture data only, read-only, never charged, never calls a supplier |
| OAuth 2.1 access token | From browser sign-in, as used by chat apps and npx threefold login |
| None | Keyless library reads, capped per IP address per day (50 by default). Responses carry X-Threefold-Next: sign in for the monthly allowance. |
GET routes need the read scope. Writes need the scope named on each route. See Accounts and keys.
Discover, describe, call
Every callable endpoint is in the registry with its task, inputs, coverage, provenance, limits and cost class:
curl "https://api.threefold.eco/api/discover?q=compare+meditation+apps+in+DE+and+JP"
curl https://api.threefold.eco/api/discover/compare_markets
curl "https://api.threefold.eco/api/compare?from=de&to=jp&niche=health-fitness"/api/discover ranks endpoints for a plain-language task and lists valid market codes and niche slugs. /api/discover/<id> returns one endpoint's inputs with examples, coverage, provenance, limits and price.
Common routes
| Route | What |
|---|---|
GET /api/meta | Markets, niches, language variants, the library configuration, and when each source was last collected (freshness) |
GET /api/chart?market&niche&store | Top apps in one market and niche, with localisation signals |
GET /api/compare?from&to&niche&store | One niche in two markets: shared, not crossed over, local only |
GET /api/apps/:id?markets&store | One app across storefronts, both stores side by side when linked |
GET /api/apps/:id/brief?to&from&store | Market brief for one app into one market |
GET /api/search?q&limit&offset&store | Title and developer search over both stores |
GET /api/apps/:id/history?market&store | Listing changes over time |
GET /api/chart-history?app&market&niche&store&days | Daily chart ranks |
GET /api/apps/:id/reviews, /reviews/summary | Store reviews and their language mix |
GET /api/paid, /api/paid/summary, /api/organic | Collected ads and posts (Paid and Organic need supplier connections; see Data and freshness) |
GET /api/visuals/gallery | Screenshot gallery |
GET /api/market-glossary, POST /api/variant-lint, POST /api/listing-check, GET /api/price-points, GET /api/market-launch-checklist | Market resources |
GET /api/i18n/rules, POST /api/i18n/reports | i18n check catalogue and stored reports |
POST /api/watches, GET /api/watches | Watches |
GET /api/usage, GET /api/me | Plan, limits and usage |
Markets are gb, us, es, mx, ar, br, de, fr, jp, kr. Niches are games, education, health-fitness, finance, productivity, lifestyle. store is ios (default) or play. The full list is in the API reference.
Response headers
| Header | Meaning |
|---|---|
X-Threefold-Cost-Micro-Usd | What this call cost (1,000,000 micro-USD is one US dollar) |
X-Threefold-Balance-Micro-Usd | Workspace balance after the call, when there is one |
X-Threefold-Idempotent-Replay | true when the answer is a replay of an earlier call with the same Idempotency-Key |
X-Threefold-Next | A hint for keyless callers |
Retry-After | On 429: seconds to wait |
Send Idempotency-Key: <unique value> on a call you might retry. A settled call with the same key returns the earlier result without charging again; a call with that key still in flight gets 409.
Paging
List routes take limit and offset. /api/paid, /api/organic and /api/chart-history return page: { limit, offset, nextOffset }, where nextOffset is null on the last page. /api/search returns a plain array: a page shorter than limit (default 20, max 100) is the last one.
Intent inputs
Discovery and the heavier endpoints accept task_intent (what you are trying to do; logged hashed) and output_destination: code for compact JSON, doc for citations and links, chat for a summary sentence, or design_tool.
Async jobs and webhooks
Fresh pulls and backfills return a job id. Read it at GET /api/jobs/:id. Pass webhook_url to be called when it finishes; the body is signed with HMAC-SHA256 in X-Threefold-Signature (sha256=<hex>). Webhook URLs must be public addresses.
Asking for coverage
POST /api/coverage/request records a market, app or channel you needed and threefold did not have. It is free, and it is how missing coverage gets prioritised.
Errors
Every error has the same body: { error, code, whose_error, retryable, hint }. The codes are a closed set: see Errors.