# threefold

> threefold is a market-entry library for agents: it answers "what's different there vs here" for an app across storefronts, language variants (es-ES, es-MX, es-AR, de-DE, ja-JP) and channels, over Brand (store listings), Organic (posts) and Paid (ads).
> Search by task, read the endpoint's inputs, coverage, limits and price class, then call it over HTTP, MCP (POST /mcp) or the threefold CLI.

## API Specification & Documentation

- OpenAPI 3.1 Specification: GET /openapi.json
- Documentation: https://threefold.eco/docs
- Errors: docs/errors.md

## Authentication

Send `Authorization: Bearer <api key>`. Discovery, /openapi.json, /api/meta and this file are public.

## Discovery

- GET /api/discover?q=<task>: endpoints ranked for a plain-language task, e.g. ?q=compare+meditation+apps+in+DE+and+JP
- GET /api/discover/<id>: inputs, examples, coverage, provenance, limits, cost class and price

## Endpoints

- library_meta: Library overview - configured markets, niches, the first-cut profile and data counts. GET /api/meta. cost_class=free, price_micro_usd=0, price_status=free, limits=0
- search_apps: Search apps already in the library by name or developer, with where each one charts. GET /api/search. cost_class=library_read, price_micro_usd=200, price_status=placeholder, limits=2
- search_store: Live App Store search for any app, not only charting ones, to get its id. GET /api/store-search. cost_class=fresh_pull, price_micro_usd=null, price_status=unpriced, limits=2
- top_apps: Top free, paid or grossing apps in one market and niche or genre, with localisation signals and the market profile. GET /api/chart. cost_class=library_read, price_micro_usd=200, price_status=placeholder, limits=3
- compare_markets: Compare one niche in two markets - shared winners, apps that have not crossed over, local-only winners. GET /api/compare. cost_class=library_read, price_micro_usd=200, price_status=placeholder, limits=4
- get_app: One app across storefronts - localised title, copy language, screenshots, ratings and signals per market. GET /api/apps/:id. cost_class=library_read, price_micro_usd=200, price_status=placeholder, limits=1
- market_brief: Rules-based market-entry brief for moving one app into one market across Brand, Paid and Organic. GET /api/apps/:id/brief. cost_class=library_read, price_micro_usd=200, price_status=placeholder, limits=2
- listing_history: History of an app's store listing - title, description, screenshots and price changes over time. GET /api/apps/:id/history. cost_class=library_read, price_micro_usd=200, price_status=placeholder, limits=5
- chart_history: Daily chart rank history for an app or a market and niche. GET /api/chart-history. cost_class=library_read, price_micro_usd=200, price_status=placeholder, limits=2
- app_reviews: Store reviews for an app in one market, with dates, ratings, version and language. GET /api/apps/:id/reviews. cost_class=library_read, price_micro_usd=200, price_status=placeholder, limits=2
- review_summary: Summary of an app's reviews in one market - rating mix, languages and recent themes. GET /api/apps/:id/reviews/summary. cost_class=library_read, price_micro_usd=200, price_status=placeholder, limits=2
- paid_ads: Ads running in a market, for an app or a niche, with start and stop dates and how long they ran. GET /api/paid. cost_class=library_read, price_micro_usd=200, price_status=placeholder, limits=8
- paid_summary: Summary of ads in a market - advertisers, counts and longest running ads. GET /api/paid/summary. cost_class=library_read, price_micro_usd=200, price_status=placeholder, limits=1
- compare_paid: Compare one app's ads at home against a target market. GET /api/apps/:id/paid-compare. cost_class=library_read, price_micro_usd=200, price_status=placeholder, limits=2
- organic_posts: Creator and social posts about an app or niche in a market, with publish dates and views. GET /api/organic. cost_class=library_read, price_micro_usd=200, price_status=placeholder, limits=8
- b2b_checklist: B2B market-entry checklist - procurement, compliance and channels for selling software into a market. GET /api/b2b, GET /api/b2b/:market. cost_class=library_read, price_micro_usd=200, price_status=placeholder, limits=1
- market_entry_report: Printable market-entry report for one app moving into one market (HTML, PDF or JSON). GET /api/reports/market-entry. cost_class=library_read, price_micro_usd=200, price_status=placeholder, limits=1
- explain_listing: AI explanation of why an app's listing differs between two markets. POST /api/analysis/listing. cost_class=ai_brief, price_micro_usd=null, price_status=unpriced, limits=1
- explain_paid: AI explanation of the ad strategy in a market for an app or niche. POST /api/analysis/paid. cost_class=ai_brief, price_micro_usd=null, price_status=unpriced, limits=1
- market_entry_narrative: AI-written market-entry brief citing listings, ads and posts as evidence. POST /api/analysis/brief. cost_class=ai_brief, price_micro_usd=null, price_status=unpriced, limits=1
- brand_name_check: AI check of an app name and tagline for meaning or connotation problems in other markets. POST /api/analysis/brand-name. cost_class=ai_brief, price_micro_usd=null, price_status=unpriced, limits=1
- translate: Translate short texts such as ad copy or reviews into one target language. POST /api/analysis/translate. cost_class=ai_brief, price_micro_usd=null, price_status=unpriced, limits=1
- describe_video: AI description of a video ad or post - hook, format, on-screen text, cultural cues. POST /api/analysis/video. cost_class=ai_brief, price_micro_usd=null, price_status=unpriced, limits=2
- track_app: Track an app across markets - ingest it now and keep it on your workspace with a home and target markets. POST /api/track. cost_class=fresh_pull, price_micro_usd=null, price_status=unpriced, limits=1
- usage: Your workspace's plan, tracked apps and spend this month. GET /api/usage. cost_class=free, price_micro_usd=0, price_status=free, limits=1
- backfill_app: Trigger or check historical backfill for an app across approved sources. POST /api/apps/:id/backfill. cost_class=fresh_pull, price_micro_usd=null, price_status=unpriced, limits=4
- export_history: Export full history of listing snapshots, ads and posts as streaming JSONL with evidence fields. GET /api/export/history. cost_class=library_read, price_micro_usd=200, price_status=placeholder, limits=2
- request_coverage: Record a market, app or channel you need that is not yet covered by Threefold. POST /api/coverage/request. cost_class=free, price_micro_usd=0, price_status=free, limits=0
- screenshot_gallery: Side-by-side screenshot gallery across markets for one app or top apps in a niche with inline low-res previews and high-res export links. GET /api/visuals/gallery. cost_class=library_read, price_micro_usd=200, price_status=placeholder, limits=2
- save_item: Save research items (apps, screens, galleries, comparisons) to a collection or workspace. POST /api/collections/save. cost_class=free, price_micro_usd=0, price_status=free, limits=0
- list_collections: List saved research collections for the current workspace with item counts. GET /api/collections. cost_class=free, price_micro_usd=0, price_status=free, limits=0
- get_collection: Retrieve items and notes in a saved research collection. GET /api/collections/:id. cost_class=free, price_micro_usd=0, price_status=free, limits=0
- add_collection_note: Attach a team note or research comment to a collection or saved item. POST /api/collections/notes. cost_class=free, price_micro_usd=0, price_status=free, limits=0
- visual_brief: Vision analysis evaluating screenshot compositions, cultural adaptations, and visual framing. POST /api/analysis/visual-brief. cost_class=ai_brief, price_micro_usd=null, price_status=unpriced, limits=1
- i18n_check_rules: Catalogue of automated internationalization and localization readiness rules across platforms and markets. GET /api/i18n/rules. cost_class=free, price_micro_usd=0, price_status=free, limits=0
- i18n_report: Store an uploaded i18n readiness report or retrieve a previously stored report by ID. GET /api/i18n/reports/:param, POST /api/i18n/reports. cost_class=library_read, price_micro_usd=200, price_status=placeholder, limits=1
- create_watch: Create an alert watch on an app or niche in markets. POST /api/watches. cost_class=free, price_micro_usd=0, price_status=free, limits=1
- list_watches: List active alert watches for the current workspace. GET /api/watches. cost_class=free, price_micro_usd=0, price_status=free, limits=1
- delete_watch: Delete or deactivate an alert watch. POST /api/watches/:id/delete. cost_class=free, price_micro_usd=0, price_status=free, limits=1
- watch_events: Get recent detected events and delivery logs for a watch. GET /api/watches/:id/events. cost_class=free, price_micro_usd=0, price_status=free, limits=1
- market_glossary: Extract domain terms and CTAs used by top-ranked storefront listings in a niche. GET /api/market-glossary, POST /api/market-glossary. cost_class=library_read, price_micro_usd=200, price_status=placeholder, limits=2
- variant_lint: Lint arbitrary copy against regional language dialect rules. POST /api/variant-lint, GET /api/variant-lint. cost_class=free, price_micro_usd=0, price_status=free, limits=1
- listing_check: Validate proposed localized store copy against store limits and competitive benchmark. POST /api/listing-check. cost_class=library_read, price_micro_usd=200, price_status=placeholder, limits=1
- price_points: Analyze what top apps in a niche charge per storefront from stored listing prices. GET /api/price-points. cost_class=library_read, price_micro_usd=200, price_status=placeholder, limits=1
- market_launch_checklist: Consolidated per-market launch checklist merging B2B, profile, and statutory legal checks. GET /api/market-launch-checklist. cost_class=library_read, price_micro_usd=200, price_status=placeholder, limits=1
- label_profile: Label shares for one market - how its listings, screenshots, ads or posts are labelled (subscription mentions, screenshot type, hook, post format), with item ids. GET /api/labels/profile. cost_class=library_read, price_micro_usd=200, price_status=placeholder, limits=4
- label_compare: Label differences between two markets - share of each answer per label for listings, screenshots, ads or posts, largest differences first, with item ids. GET /api/labels/compare. cost_class=library_read, price_micro_usd=200, price_status=placeholder, limits=4
- language_fit: Share of a market's listings, screenshots and ads written in its own language and variant (es-MX in Mexico, not es-ES), with item ids. GET /api/labels/language-fit. cost_class=library_read, price_micro_usd=200, price_status=placeholder, limits=3
- market_take: The weekly threefold take on one market and niche - a headline and evidenced points on how its listings, screenshots, ads and posts differ from the US. GET /api/market-take. cost_class=library_read, price_micro_usd=200, price_status=placeholder, limits=3
- agent_app: One app across stores, Brand, Paid and Organic, and markets, as a digest with links and next steps. GET /api/agent/app. cost_class=library_read, price_micro_usd=200, price_status=placeholder, limits=1
- agent_market: One market and genre - what wins there, optionally next to a reference app or a home market, as a digest. GET /api/agent/market. cost_class=library_read, price_micro_usd=200, price_status=placeholder, limits=1
- agent_check: Grade the user's listing, screenshots, ad, name, repository or live app for a target market - rule checks, criteria and reference examples. POST /api/agent/check. cost_class=library_read, price_micro_usd=200, price_status=placeholder, limits=2
- agent_workspace: The workspace's apps, competitors per market, target markets, watches and changes, saved items and usage. POST /api/agent/workspace. cost_class=free, price_micro_usd=0, price_status=free, limits=1