{ "openapi": "3.1.0", "info": { "title": "threefold API", "version": "0.2.0", "description": "Market-entry intelligence for apps across storefronts, languages, and channels." }, "servers": [ { "url": "https://api.threefold.eco", "description": "Production API" } ], "paths": { "/api/meta": { "get": { "operationId": "library_meta", "summary": "Library Metadata", "description": "Library overview - configured markets, niches, the first-cut profile and data counts", "tags": [ "account" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "generatedAt", "markets", "niches", "libraryCut", "counts", "stores" ], "properties": { "generatedAt": { "type": "string", "description": "When the newest data was collected, across all sources (ISO 8601). Per source in freshness." }, "freshness": { "type": "object", "description": "Latest real collection time per source. snapshotAt is the seed snapshot's date.", "properties": { "latestAt": { "type": [ "string", "null" ] }, "snapshotAt": { "type": [ "string", "null" ] }, "sources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "pillar": { "type": "string" }, "store": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "collectedAt": { "type": [ "string", "null" ] } } } } } }, "source": { "type": "string" }, "storage": { "type": "string" }, "markets": { "type": "array", "items": { "type": "object" } }, "niches": { "type": "array", "items": { "type": "object" } }, "appsPerNiche": { "type": "integer" }, "firstCut": { "type": "array", "items": { "type": "string" } }, "counts": { "type": "object" }, "stores": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/search": { "get": { "operationId": "search_apps", "summary": "Search Apps", "description": "Search apps already in the library by name or developer, with where each one charts", "tags": [ "search" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "App name or developer", "schema": { "description": "App name or developer", "example": "duolingo", "type": "string" } }, { "name": "store", "in": "query", "required": false, "description": "ios (default) or play", "schema": { "description": "ios (default) or play", "type": "string", "enum": [ "ios", "play" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Page size", "schema": { "description": "Page size", "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "description": "Skip this many results", "schema": { "description": "Skip this many results", "type": "integer" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "id", "title", "developer", "store" ], "properties": { "id": { "type": [ "string", "integer" ] }, "title": { "type": "string" }, "developer": { "type": "string" }, "icon": { "type": [ "string", "null" ] }, "rating": { "type": [ "number", "null" ] }, "ratingCount": { "type": [ "integer", "null" ] }, "market": { "type": [ "string", "null" ] }, "signals": { "type": "object" }, "charts": { "type": "array" }, "store": { "type": "string" }, "stores": { "type": "array" } } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/store-search": { "get": { "operationId": "search_store", "summary": "Search App Store", "description": "Live App Store search for any app, not only charting ones, to get its id", "tags": [ "search" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search term", "schema": { "description": "Search term", "example": "headspace", "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "id", "title", "developer", "inDataset" ], "properties": { "id": { "type": [ "string", "integer" ] }, "title": { "type": "string" }, "developer": { "type": "string" }, "icon": { "type": [ "string", "null" ] }, "inDataset": { "type": "boolean" } } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/chart": { "get": { "operationId": "top_apps", "summary": "Top Apps", "description": "Top free, paid or grossing apps in one market and niche or genre, with localisation signals and the market profile", "tags": [ "chart" ], "parameters": [ { "name": "market", "in": "query", "required": true, "schema": { "example": "jp", "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] } }, { "name": "niche", "in": "query", "required": true, "description": "Niche or any collected genre slug (GET /api/meta genres)", "schema": { "description": "Niche or any collected genre slug (GET /api/meta genres)", "example": "health-fitness", "type": "string", "enum": [ "games", "education", "health-fitness", "finance", "productivity", "lifestyle", "business", "weather", "utilities", "travel", "sports", "social-networking", "reference", "photo-video", "news", "navigation", "music", "entertainment", "books", "medical", "magazines-newspapers", "catalogs", "food-drink", "shopping", "stickers", "developer-tools", "graphics-design", "games-action", "games-adventure", "games-casual", "games-board", "games-card", "games-casino", "games-dice", "games-educational", "games-family", "games-music", "games-puzzle", "games-racing", "games-role-playing", "games-simulation", "games-sports", "games-strategy", "games-trivia", "games-word", "games-arcade", "communication", "dating", "video-players", "personalization", "auto-vehicles", "beauty", "comics", "events", "house-home", "parenting" ] } }, { "name": "store", "in": "query", "required": false, "description": "ios (default) or play", "schema": { "description": "ios (default) or play", "type": "string", "enum": [ "ios", "play" ] } }, { "name": "chart", "in": "query", "required": false, "description": "Chart type: top free (default), top paid or top grossing", "schema": { "description": "Chart type: top free (default), top paid or top grossing", "type": "string", "enum": [ "free", "paid", "grossing" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "market", "niche", "apps", "store" ], "properties": { "market": { "type": [ "string", "object" ] }, "niche": { "type": [ "string", "object" ] }, "library": { "type": "object" }, "apps": { "type": "array", "items": { "type": "object" } }, "store": { "type": "string" } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/compare": { "get": { "operationId": "compare_markets", "summary": "Compare Markets", "description": "Compare one niche in two markets - shared winners, apps that have not crossed over, local-only winners", "tags": [ "compare" ], "parameters": [ { "name": "from", "in": "query", "required": true, "description": "Home market", "schema": { "description": "Home market", "example": "us", "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] } }, { "name": "to", "in": "query", "required": true, "description": "Target market", "schema": { "description": "Target market", "example": "de", "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] } }, { "name": "niche", "in": "query", "required": true, "description": "Niche or any collected genre slug (GET /api/meta genres)", "schema": { "description": "Niche or any collected genre slug (GET /api/meta genres)", "example": "health-fitness", "type": "string", "enum": [ "games", "education", "health-fitness", "finance", "productivity", "lifestyle", "business", "weather", "utilities", "travel", "sports", "social-networking", "reference", "photo-video", "news", "navigation", "music", "entertainment", "books", "medical", "magazines-newspapers", "catalogs", "food-drink", "shopping", "stickers", "developer-tools", "graphics-design", "games-action", "games-adventure", "games-casual", "games-board", "games-card", "games-casino", "games-dice", "games-educational", "games-family", "games-music", "games-puzzle", "games-racing", "games-role-playing", "games-simulation", "games-sports", "games-strategy", "games-trivia", "games-word", "games-arcade", "communication", "dating", "video-players", "personalization", "auto-vehicles", "beauty", "comics", "events", "house-home", "parenting" ] } }, { "name": "store", "in": "query", "required": false, "description": "ios (default) or play", "schema": { "description": "ios (default) or play", "type": "string", "enum": [ "ios", "play" ] } }, { "name": "chart", "in": "query", "required": false, "description": "Chart type: top free (default), top paid or top grossing", "schema": { "description": "Chart type: top free (default), top paid or top grossing", "type": "string", "enum": [ "free", "paid", "grossing" ] } }, { "name": "include_images", "in": "query", "required": false, "description": "Fetch and return low-res preview images (default false)", "schema": { "description": "Fetch and return low-res preview images (default false)", "type": "boolean" } }, { "name": "image_format", "in": "query", "required": false, "description": "Preview image format (webp default, or jpg)", "schema": { "description": "Preview image format (webp default, or jpg)", "type": "string", "enum": [ "webp", "jpg" ] } }, { "name": "task_intent", "in": "query", "required": false, "description": "Caller task intent or context, used to shape output and logged (hashed)", "schema": { "description": "Caller task intent or context, used to shape output and logged (hashed)", "type": "string" } }, { "name": "output_destination", "in": "query", "required": false, "description": "Target environment: code (compact JSON), doc (citations and links), chat (summary sentence), design_tool (visual assets and layout)", "schema": { "description": "Target environment: code (compact JSON), doc (citations and links), chat (summary sentence), design_tool (visual assets and layout)", "type": "string", "enum": [ "code", "doc", "chat", "design_tool" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "from", "to", "shared", "notCrossed", "localOnly", "store" ], "properties": { "from": { "type": [ "string", "object", "array" ] }, "to": { "type": [ "string", "object", "array" ] }, "niche": { "type": [ "string", "null" ] }, "shared": { "type": "array", "items": { "type": "object" } }, "notCrossed": { "type": "array", "items": { "type": "object" } }, "localOnly": { "type": "array", "items": { "type": "object" } }, "library": { "type": "object" }, "store": { "type": "string" }, "summary": { "type": "string" }, "citations": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/apps/{id}": { "get": { "operationId": "get_app", "summary": "Get App", "description": "One app across storefronts - localised title, copy language, screenshots, ratings and signals per market", "tags": [ "app" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "App Store id, or play: for Play-only apps", "schema": { "description": "App Store id, or play: for Play-only apps", "example": "529479190", "type": "string" } }, { "name": "markets", "in": "query", "required": false, "description": "Comma-separated market codes. Defaults to every market.", "schema": { "description": "Comma-separated market codes. Defaults to every market.", "type": "array", "items": { "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] } } }, { "name": "store", "in": "query", "required": false, "description": "ios (default) or play", "schema": { "description": "ios (default) or play", "type": "string", "enum": [ "ios", "play" ] } }, { "name": "include_images", "in": "query", "required": false, "description": "Fetch and return low-res preview images (default false)", "schema": { "description": "Fetch and return low-res preview images (default false)", "type": "boolean" } }, { "name": "image_format", "in": "query", "required": false, "description": "Preview image format (webp default, or jpg)", "schema": { "description": "Preview image format (webp default, or jpg)", "type": "string", "enum": [ "webp", "jpg" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "title", "developer", "storefronts" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "developer": { "type": "string" }, "genre": { "type": [ "string", "null" ] }, "icon": { "type": [ "string", "null" ] }, "charts": { "type": "array" }, "tracking": { "type": [ "object", "null" ] }, "storefronts": { "type": [ "object", "array" ] }, "store": { "type": "string" }, "stores": { "type": "array" }, "play": { "type": [ "object", "null" ] }, "backfill": { "type": "object" } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/apps/{id}/brief": { "get": { "operationId": "market_brief", "summary": "Market Brief", "description": "Rules-based market-entry brief for moving one app into one market across Brand, Paid and Organic", "tags": [ "brief" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Path parameter id", "schema": { "example": "529479190", "type": "string" } }, { "name": "to", "in": "query", "required": true, "description": "Target market", "schema": { "description": "Target market", "example": "de", "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] } }, { "name": "from", "in": "query", "required": false, "description": "Home market", "schema": { "description": "Home market", "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] } }, { "name": "store", "in": "query", "required": false, "description": "ios (default) or play", "schema": { "description": "ios (default) or play", "type": "string", "enum": [ "ios", "play" ] } }, { "name": "task_intent", "in": "query", "required": false, "description": "Caller task intent or context, used to shape output and logged (hashed)", "schema": { "description": "Caller task intent or context, used to shape output and logged (hashed)", "type": "string" } }, { "name": "output_destination", "in": "query", "required": false, "description": "Target environment: code (compact JSON), doc (citations and links), chat (summary sentence), design_tool (visual assets and layout)", "schema": { "description": "Target environment: code (compact JSON), doc (citations and links), chat (summary sentence), design_tool (visual assets and layout)", "type": "string", "enum": [ "code", "doc", "chat", "design_tool" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "app", "to", "pillars" ], "properties": { "app": { "type": "object" }, "from": { "type": [ "string", "object", "null" ] }, "to": { "type": [ "string", "object" ] }, "niche": { "type": [ "string", "object", "null" ] }, "pillars": { "type": "object" }, "competitors": { "type": "array" }, "benchmarks": { "type": [ "array", "object" ] }, "library": { "type": "object" }, "store": { "type": "string" }, "summary": { "type": "string" }, "citations": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/apps/{id}/history": { "get": { "operationId": "listing_history", "summary": "Listing History", "description": "History of an app's store listing - title, description, screenshots and price changes over time", "tags": [ "history" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Path parameter id", "schema": { "example": "529479190", "type": "string" } }, { "name": "market", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] } }, { "name": "store", "in": "query", "required": false, "description": "ios (default) or play", "schema": { "description": "ios (default) or play", "type": "string", "enum": [ "ios", "play" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "storage": { "type": "string" }, "note": { "type": "string" }, "items": { "type": "array", "items": { "type": "object" } }, "backfill": { "type": "object" } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/chart-history": { "get": { "operationId": "chart_history", "summary": "Chart History", "description": "Daily chart rank history for an app or a market and niche", "tags": [ "history" ], "parameters": [ { "name": "app", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "market", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] } }, { "name": "niche", "in": "query", "required": false, "description": "Niche or any collected genre slug (GET /api/meta genres)", "schema": { "description": "Niche or any collected genre slug (GET /api/meta genres)", "type": "string", "enum": [ "games", "education", "health-fitness", "finance", "productivity", "lifestyle", "business", "weather", "utilities", "travel", "sports", "social-networking", "reference", "photo-video", "news", "navigation", "music", "entertainment", "books", "medical", "magazines-newspapers", "catalogs", "food-drink", "shopping", "stickers", "developer-tools", "graphics-design", "games-action", "games-adventure", "games-casual", "games-board", "games-card", "games-casino", "games-dice", "games-educational", "games-family", "games-music", "games-puzzle", "games-racing", "games-role-playing", "games-simulation", "games-sports", "games-strategy", "games-trivia", "games-word", "games-arcade", "communication", "dating", "video-players", "personalization", "auto-vehicles", "beauty", "comics", "events", "house-home", "parenting" ] } }, { "name": "store", "in": "query", "required": false, "description": "ios (default) or play", "schema": { "description": "ios (default) or play", "type": "string", "enum": [ "ios", "play" ] } }, { "name": "chart", "in": "query", "required": false, "description": "Chart type: top free (default), top paid or top grossing", "schema": { "description": "Chart type: top free (default), top paid or top grossing", "type": "string", "enum": [ "free", "paid", "grossing" ] } }, { "name": "days", "in": "query", "required": false, "description": "Look-back window in days", "schema": { "description": "Look-back window in days", "default": 90, "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "storage": { "type": "string" }, "note": { "type": "string" }, "items": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/apps/{id}/reviews": { "get": { "operationId": "app_reviews", "summary": "App Reviews", "description": "Store reviews for an app in one market, with dates, ratings, version and language", "tags": [ "reviews" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Path parameter id", "schema": { "example": "529479190", "type": "string" } }, { "name": "market", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] } }, { "name": "store", "in": "query", "required": false, "description": "ios (default) or play", "schema": { "description": "ios (default) or play", "type": "string", "enum": [ "ios", "play" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Paging cursor from the previous response", "schema": { "description": "Paging cursor from the previous response", "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "storage": { "type": "string" }, "note": { "type": "string" }, "items": { "type": "array", "items": { "type": "object" } }, "nextCursor": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/apps/{id}/reviews/summary": { "get": { "operationId": "review_summary", "summary": "Review Summary", "description": "Summary of an app's reviews in one market - rating mix, languages and recent themes", "tags": [ "reviews" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Path parameter id", "schema": { "example": "529479190", "type": "string" } }, { "name": "market", "in": "query", "required": true, "schema": { "example": "mx", "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "appId", "market", "count" ], "properties": { "appId": { "type": "string" }, "market": { "type": "string" }, "marketLanguage": { "type": [ "string", "null" ] }, "count": { "type": "integer" }, "avgRating": { "type": [ "number", "null" ] }, "ratingDistribution": { "type": "object" }, "languageShare": { "type": "object" }, "languages": { "type": "object" }, "byStore": { "type": "array" }, "replyRate": { "type": [ "number", "null" ] }, "window": { "type": "object" }, "reference": { "type": "object" }, "storage": { "type": "string" }, "note": { "type": "string" } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/paid": { "get": { "operationId": "paid_ads", "summary": "Paid Ads", "description": "Ads running in a market, for an app or a niche, with start and stop dates and how long they ran", "tags": [ "paid" ], "parameters": [ { "name": "market", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] } }, { "name": "app", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "niche", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "games", "education", "health-fitness", "finance", "productivity", "lifestyle" ] } }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "meta_ad_library", "tiktok_creative_center", "tiktok_commercial_content", "google_ads_transparency", "linkedin_ad_library" ] } }, { "name": "active", "in": "query", "required": false, "description": "Only ads still running", "schema": { "description": "Only ads still running", "type": "boolean" } }, { "name": "minDays", "in": "query", "required": false, "description": "Ran at least this many days", "schema": { "description": "Ran at least this many days", "type": "integer" } }, { "name": "lang", "in": "query", "required": false, "description": "Language (es) or variant (es-MX)", "schema": { "description": "Language (es) or variant (es-MX)", "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "longest (default) or recent", "schema": { "description": "longest (default) or recent", "type": "string", "enum": [ "longest", "recent" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "storage": { "type": "string" }, "note": { "type": "string" }, "items": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/paid/summary": { "get": { "operationId": "paid_summary", "summary": "Paid Summary", "description": "Summary of ads in a market - advertisers, counts and longest running ads", "tags": [ "paid" ], "parameters": [ { "name": "market", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] } }, { "name": "app", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "niche", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "games", "education", "health-fitness", "finance", "productivity", "lifestyle" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "market": { "type": "string" }, "appId": { "type": "string" }, "niche": { "type": "string" }, "ads": { "type": "integer" }, "active": { "type": "integer" }, "longestRunningDays": { "type": "integer" }, "running60Plus": { "type": "integer" }, "videoShare": { "type": [ "integer", "null" ] }, "languages": { "type": "object" }, "sources": { "type": "object" }, "topAdvertisers": { "type": "array" } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/apps/{id}/paid-compare": { "get": { "operationId": "compare_paid", "summary": "Compare Paid", "description": "Compare one app's ads at home against a target market", "tags": [ "compare" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Path parameter id", "schema": { "example": "529479190", "type": "string" } }, { "name": "to", "in": "query", "required": true, "schema": { "example": "de", "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] } }, { "name": "from", "in": "query", "required": false, "description": "Home market", "schema": { "description": "Home market", "default": "us", "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "storage": { "type": "string" }, "note": { "type": "string" }, "from": { "type": "object" }, "to": { "type": "object" }, "observations": { "type": "array" } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/organic": { "get": { "operationId": "organic_posts", "summary": "Organic Posts", "description": "Creator and social posts about an app or niche in a market, with publish dates and views", "tags": [ "organic" ], "parameters": [ { "name": "market", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] } }, { "name": "app", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "niche", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "games", "education", "health-fitness", "finance", "productivity", "lifestyle" ] } }, { "name": "source", "in": "query", "required": false, "description": "Channel: youtube, tiktok, instagram or x", "schema": { "description": "Channel: youtube, tiktok, instagram or x", "type": "string" } }, { "name": "since", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "sort", "in": "query", "required": false, "description": "views (default) or recent", "schema": { "description": "views (default) or recent", "type": "string", "enum": [ "views", "recent" ] } }, { "name": "brand_account", "in": "query", "required": false, "description": "true: posts from the app's own account (Instagram Business Discovery); false: creator and hashtag posts. Omit for both.", "schema": { "description": "true: posts from the app's own account (Instagram Business Discovery); false: creator and hashtag posts. Omit for both.", "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "storage": { "type": "string" }, "note": { "type": "string" }, "items": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/b2b": { "get": { "operationId": "b2b_checklist_api_b2b", "summary": "B2B Market Checklist", "description": "B2B market-entry checklist - procurement, compliance and channels for selling software into a market", "tags": [ "brief" ], "parameters": [ { "name": "market", "in": "query", "required": false, "description": "Omit for the index of covered markets", "schema": { "description": "Omit for the index of covered markets", "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "market", "name", "checklist" ], "properties": { "market": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": "string" }, "profile": { "type": "object" }, "checklist": { "type": "array", "items": { "type": "object" } }, "gaps": { "type": "array" }, "depth": { "type": "string" }, "researchNote": { "type": "string" }, "disclaimer": { "type": "string" } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/b2b/{market}": { "get": { "operationId": "b2b_checklist_api_b2b_market", "summary": "B2B Market Checklist", "description": "B2B market-entry checklist - procurement, compliance and channels for selling software into a market", "tags": [ "brief" ], "parameters": [ { "name": "market", "in": "path", "required": true, "description": "Omit for the index of covered markets", "schema": { "description": "Omit for the index of covered markets", "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "market", "name", "checklist" ], "properties": { "market": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": "string" }, "profile": { "type": "object" }, "checklist": { "type": "array", "items": { "type": "object" } }, "gaps": { "type": "array" }, "depth": { "type": "string" }, "researchNote": { "type": "string" }, "disclaimer": { "type": "string" } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/reports/market-entry": { "get": { "operationId": "market_entry_report", "summary": "Market Entry Report", "description": "Printable market-entry report for one app moving into one market (HTML, PDF or JSON)", "tags": [ "brief" ], "parameters": [ { "name": "app", "in": "query", "required": true, "schema": { "example": "529479190", "type": "string" } }, { "name": "to", "in": "query", "required": true, "schema": { "example": "de", "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] } }, { "name": "format", "in": "query", "required": false, "description": "html (default)", "schema": { "description": "html (default)", "type": "string", "enum": [ "html", "pdf", "json" ] } }, { "name": "task_intent", "in": "query", "required": false, "description": "Caller task intent or context, used to shape output and logged (hashed)", "schema": { "description": "Caller task intent or context, used to shape output and logged (hashed)", "type": "string" } }, { "name": "output_destination", "in": "query", "required": false, "description": "Target environment: code (compact JSON), doc (citations and links), chat (summary sentence), design_tool (visual assets and layout)", "schema": { "description": "Target environment: code (compact JSON), doc (citations and links), chat (summary sentence), design_tool (visual assets and layout)", "type": "string", "enum": [ "code", "doc", "chat", "design_tool" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "params" ], "properties": { "params": { "type": "object" }, "data": { "type": "object" }, "analysis": { "type": [ "object", "null" ] }, "htmlUrl": { "type": "string" }, "brand": { "type": "array" }, "paid": { "type": "object" }, "organic": { "type": "object" }, "reviews": { "type": "object" }, "competitors": { "type": "array" }, "evidence": { "type": "array" }, "summary": { "type": "string" } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/analysis/listing": { "post": { "operationId": "explain_listing", "summary": "Explain Listing Differences", "description": "AI explanation of why an app's listing differs between two markets", "tags": [ "analysis" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "kind", "output" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "cached": { "type": "boolean" }, "output": { "type": "object" }, "input": { "type": "object" }, "durationMs": { "type": "number" }, "usage": { "type": "object" }, "summary": { "type": "string" } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "app": { "example": "329218549", "type": "string" }, "to": { "example": "jp", "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] }, "from": { "default": "us", "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] }, "refresh": { "description": "Ignore the cached result", "type": "boolean" }, "task_intent": { "description": "Caller task intent or context, used to shape output and logged (hashed)", "type": "string" }, "output_destination": { "description": "Target environment: code (compact JSON), doc (citations and links), chat (summary sentence), design_tool (visual assets and layout)", "type": "string", "enum": [ "code", "doc", "chat", "design_tool" ] } }, "required": [ "app", "to" ] } } } } } }, "/api/analysis/paid": { "post": { "operationId": "explain_paid", "summary": "Explain Paid", "description": "AI explanation of the ad strategy in a market for an app or niche", "tags": [ "analysis" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "kind", "output" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "cached": { "type": "boolean" }, "output": { "type": "object" }, "input": { "type": "object" }, "durationMs": { "type": "number" }, "usage": { "type": "object" }, "summary": { "type": "string" } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "market": { "example": "de", "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] }, "app": { "type": "string" }, "niche": { "type": "string", "enum": [ "games", "education", "health-fitness", "finance", "productivity", "lifestyle" ] }, "from": { "default": "us", "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] }, "refresh": { "type": "boolean" }, "task_intent": { "description": "Caller task intent or context, used to shape output and logged (hashed)", "type": "string" }, "output_destination": { "description": "Target environment: code (compact JSON), doc (citations and links), chat (summary sentence), design_tool (visual assets and layout)", "type": "string", "enum": [ "code", "doc", "chat", "design_tool" ] } }, "required": [ "market" ] } } } } } }, "/api/analysis/brief": { "post": { "operationId": "market_entry_narrative", "summary": "Market Entry Narrative", "description": "AI-written market-entry brief citing listings, ads and posts as evidence", "tags": [ "brief" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "kind", "output" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "cached": { "type": "boolean" }, "output": { "type": "object" }, "input": { "type": "object" }, "durationMs": { "type": "number" }, "usage": { "type": "object" }, "summary": { "type": "string" } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "app": { "example": "529479190", "type": "string" }, "to": { "example": "jp", "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] }, "from": { "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] }, "refresh": { "type": "boolean" }, "task_intent": { "description": "Caller task intent or context, used to shape output and logged (hashed)", "type": "string" }, "output_destination": { "description": "Target environment: code (compact JSON), doc (citations and links), chat (summary sentence), design_tool (visual assets and layout)", "type": "string", "enum": [ "code", "doc", "chat", "design_tool" ] } }, "required": [ "app", "to" ] } } } } } }, "/api/analysis/brand-name": { "post": { "operationId": "brand_name_check", "summary": "Brand Name Check", "description": "AI check of an app name and tagline for meaning or connotation problems in other markets", "tags": [ "analysis" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "kind", "output" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "cached": { "type": "boolean" }, "output": { "type": "object" }, "input": { "type": "object" }, "durationMs": { "type": "number" }, "usage": { "type": "object" }, "summary": { "type": "string" } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "example": "Zing", "type": "string" }, "tagline": { "type": "string" }, "markets": { "type": "array", "items": { "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] } }, "refresh": { "type": "boolean" }, "task_intent": { "description": "Caller task intent or context, used to shape output and logged (hashed)", "type": "string" }, "output_destination": { "description": "Target environment: code (compact JSON), doc (citations and links), chat (summary sentence), design_tool (visual assets and layout)", "type": "string", "enum": [ "code", "doc", "chat", "design_tool" ] } }, "required": [ "name" ] } } } } } }, "/api/analysis/translate": { "post": { "operationId": "translate", "summary": "Translate", "description": "Translate short texts such as ad copy or reviews into one target language", "tags": [ "analysis" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "target", "items" ], "properties": { "target": { "type": "string" }, "variant": { "type": [ "string", "null" ] }, "model": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "required": [ "text", "translation" ], "properties": { "text": { "type": "string" }, "translation": { "type": [ "string", "null" ] }, "sourceLang": { "type": [ "string", "null" ] }, "variant": { "type": [ "string", "null" ] }, "variantCues": { "type": "array", "items": { "type": "string" } }, "notes": { "type": [ "string", "null" ] }, "cached": { "type": "boolean" }, "validPlaceholders": { "type": "boolean" }, "placeholderMismatch": { "type": "boolean" }, "placeholderErrors": { "type": "array", "items": { "type": "string" } }, "error": { "type": "string" } } } }, "requests": { "type": "number" }, "costUsd": { "type": "number" } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "texts": { "example": [ "Hola", "Gracias" ], "type": "array", "items": { "type": "string" } }, "target": { "description": "Target language code", "default": "en", "type": "string" }, "variant": { "description": "Regional language variant", "type": "string" }, "formality": { "description": "Formality register (e.g. for German)", "type": "string", "enum": [ "formal", "informal" ] }, "niche": { "description": "App Store niche", "type": "string", "enum": [ "games", "education", "health-fitness", "finance", "productivity", "lifestyle" ] }, "market": { "description": "Target market code", "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] } }, "required": [ "texts" ] } } } } } }, "/api/analysis/video": { "post": { "operationId": "describe_video", "summary": "Describe Video", "description": "AI description of a video ad or post - hook, format, on-screen text, cultural cues", "tags": [ "analysis" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "kind", "output" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "cached": { "type": "boolean" }, "output": { "type": "object" }, "input": { "type": "object" }, "durationMs": { "type": "number" }, "usage": { "type": "object" } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "description": "Public http(s) video URL", "example": "https://video.example/a.mp4", "type": "string" }, "thumbnail": { "description": "Public http(s) thumbnail URL", "type": "string" }, "market": { "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] }, "refresh": { "type": "boolean" } }, "required": [ "url" ] } } } } } }, "/api/track": { "post": { "operationId": "track_app", "summary": "Track App", "description": "Track an app across markets - ingest it now and keep it on your workspace with a home and target markets", "tags": [ "account" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "tracking" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "developer": { "type": "string" }, "tracking": { "type": "object" }, "schedules": { "type": [ "array", "null" ] }, "job_id": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "example": "529479190", "type": "string" }, "home": { "default": "us", "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] }, "targets": { "description": "Defaults to the first library cut minus home", "type": "array", "items": { "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] } }, "pillars": { "description": "brand, organic, paid", "type": "array", "items": { "type": "string" } } }, "required": [ "id" ] } } } } } }, "/api/usage": { "get": { "operationId": "usage", "summary": "Account Usage", "description": "Your workspace's plan, tracked apps and spend this month", "tags": [ "account" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "plan", "planName", "limits" ], "properties": { "workspace": { "type": [ "object", "null" ] }, "plan": { "type": "string" }, "planName": { "type": "string" }, "limits": { "type": "object" }, "trackedApps": { "type": "object" }, "schedules": { "type": "object" }, "spend": { "type": "object" }, "analyses": { "type": "object" }, "note": { "type": "string" } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/apps/{id}/backfill": { "post": { "operationId": "backfill_app", "summary": "Backfill App", "description": "Trigger or check historical backfill for an app across approved sources", "tags": [ "history" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Path parameter id", "schema": { "example": "529479190", "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "backfill" ], "properties": { "backfill": { "type": "object", "required": [ "status", "sources" ], "properties": { "status": { "type": "string" }, "sources": { "type": "array" }, "job_id": { "type": [ "string", "null" ] } } }, "job_id": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } } } }, "/api/export/history": { "get": { "operationId": "export_history", "summary": "Export History", "description": "Export full history of listing snapshots, ads and posts as streaming JSONL with evidence fields", "tags": [ "history" ], "parameters": [ { "name": "app", "in": "query", "required": true, "schema": { "example": "529479190", "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/coverage/request": { "post": { "operationId": "request_coverage", "summary": "Request Coverage", "description": "Record a market, app or channel you need that is not yet covered by Threefold", "tags": [ "account" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "id", "message" ], "properties": { "ok": { "type": "boolean" }, "id": { "type": "string" }, "message": { "type": "string" } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "market": { "description": "Market code or country name needed, e.g. br, pl, kr", "type": "string" }, "app_id": { "description": "App id or package name needed", "type": "string" }, "channel": { "description": "Channel or source needed, e.g. line, kakao, reddit", "type": "string" }, "note": { "description": "Context on why this coverage is needed", "type": "string" } } } } } } } }, "/api/visuals/gallery": { "get": { "operationId": "screenshot_gallery", "summary": "Screenshot Gallery", "description": "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", "tags": [ "app" ], "parameters": [ { "name": "app", "in": "query", "required": false, "description": "App Store id (or play: for Play-only apps)", "schema": { "description": "App Store id (or play: for Play-only apps)", "example": "529479190", "type": "string" } }, { "name": "markets", "in": "query", "required": false, "description": "Comma-separated target market codes", "schema": { "description": "Comma-separated target market codes", "example": "es,mx,ar", "type": "array", "items": { "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] } } }, { "name": "market", "in": "query", "required": false, "description": "Market for niche mode", "schema": { "description": "Market for niche mode", "example": "jp", "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] } }, { "name": "niche", "in": "query", "required": false, "description": "Niche for top apps mode", "schema": { "description": "Niche for top apps mode", "example": "health-fitness", "type": "string", "enum": [ "games", "education", "health-fitness", "finance", "productivity", "lifestyle", "business", "weather", "utilities", "travel", "sports", "social-networking", "reference", "photo-video", "news", "navigation", "music", "entertainment", "books", "medical", "magazines-newspapers", "catalogs", "food-drink", "shopping", "stickers", "developer-tools", "graphics-design", "games-action", "games-adventure", "games-casual", "games-board", "games-card", "games-casino", "games-dice", "games-educational", "games-family", "games-music", "games-puzzle", "games-racing", "games-role-playing", "games-simulation", "games-sports", "games-strategy", "games-trivia", "games-word", "games-arcade", "communication", "dating", "video-players", "personalization", "auto-vehicles", "beauty", "comics", "events", "house-home", "parenting" ] } }, { "name": "store", "in": "query", "required": false, "description": "ios (default) or play", "schema": { "description": "ios (default) or play", "type": "string", "enum": [ "ios", "play" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum screenshots or apps (1-20, default 5)", "schema": { "description": "Maximum screenshots or apps (1-20, default 5)", "type": "integer" } }, { "name": "image_format", "in": "query", "required": false, "description": "Preview image format (webp default, or jpg)", "schema": { "description": "Preview image format (webp default, or jpg)", "type": "string", "enum": [ "webp", "jpg" ] } }, { "name": "task_intent", "in": "query", "required": false, "description": "Caller task intent or context, used to shape output and logged (hashed)", "schema": { "description": "Caller task intent or context, used to shape output and logged (hashed)", "type": "string" } }, { "name": "output_destination", "in": "query", "required": false, "description": "Target environment: code (compact JSON), doc (citations and links), chat (summary sentence), design_tool (visual assets and layout)", "schema": { "description": "Target environment: code (compact JSON), doc (citations and links), chat (summary sentence), design_tool (visual assets and layout)", "type": "string", "enum": [ "code", "doc", "chat", "design_tool" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "mode", "items", "total" ], "properties": { "mode": { "type": "string" }, "app": { "type": [ "string", "null" ] }, "market": { "type": [ "string", "null" ] }, "niche": { "type": [ "string", "null" ] }, "store": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "required": [ "app_id", "app_title", "market", "position", "image_url", "store_url", "expiring" ], "properties": { "app_id": { "type": "string" }, "app_title": { "type": "string" }, "market": { "type": "string" }, "market_name": { "type": "string" }, "rank": { "type": "integer" }, "position": { "type": "integer" }, "image_url": { "type": "string" }, "store_url": { "type": "string" }, "expiring": { "type": "boolean" }, "preview_format": { "type": [ "string", "null" ] }, "preview_width": { "type": [ "integer", "null" ] }, "preview_height": { "type": [ "integer", "null" ] }, "preview_error": { "type": "string" } } } }, "total": { "type": "integer" }, "citation_instruction": { "type": "string" } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/collections/save": { "post": { "operationId": "save_item", "summary": "Save Item", "description": "Save research items (apps, screens, galleries, comparisons) to a collection or workspace", "tags": [ "account" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "item" ], "properties": { "ok": { "type": "boolean" }, "item": { "type": "object" } }, "additionalProperties": true } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "item_id": { "description": "Item identifier to save", "type": "string" }, "kind": { "description": "Kind of saved item", "type": "string", "enum": [ "app", "screen", "gallery", "comparison" ] }, "collection_id": { "description": "Collection UUID or 'all-saved'", "type": "string" }, "collection_name": { "description": "Name of collection to create or add into", "type": "string" }, "market_code": { "description": "Market code if applicable", "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] }, "title": { "description": "Item title", "type": "string" }, "note": { "description": "Optional research note", "type": "string" } }, "required": [ "item_id" ] } } } } } }, "/api/collections": { "get": { "operationId": "list_collections", "summary": "List Collections", "description": "List saved research collections for the current workspace with item counts", "tags": [ "account" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Max collections to return", "schema": { "description": "Max collections to return", "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "description": "Paging offset", "schema": { "description": "Paging offset", "type": "integer" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "collections", "total_items_saved" ], "properties": { "collections": { "type": "array", "items": { "type": "object" } }, "total_items_saved": { "type": "integer" } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/collections/{id}": { "get": { "operationId": "get_collection", "summary": "Get Collection", "description": "Retrieve items and notes in a saved research collection", "tags": [ "account" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Collection UUID or 'all-saved'", "schema": { "description": "Collection UUID or 'all-saved'", "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Max items to return", "schema": { "description": "Max items to return", "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "description": "Paging offset", "schema": { "description": "Paging offset", "type": "integer" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "collection", "items" ], "properties": { "collection": { "type": "object" }, "items": { "type": "array", "items": { "type": "object" } }, "notes": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/collections/notes": { "post": { "operationId": "add_collection_note", "summary": "Add Collection Note", "description": "Attach a team note or research comment to a collection or saved item", "tags": [ "account" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "note" ], "properties": { "ok": { "type": "boolean" }, "note": { "type": "object" } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "description": "Note content", "type": "string" }, "collection_id": { "description": "Collection UUID", "type": "string" }, "item_id": { "description": "Item identifier", "type": "string" } }, "required": [ "note" ] } } } } } }, "/api/analysis/visual-brief": { "post": { "operationId": "visual_brief", "summary": "Visual Brief", "description": "Vision analysis evaluating screenshot compositions, cultural adaptations, and visual framing", "tags": [ "analysis" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "kind", "output" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "cached": { "type": "boolean" }, "output": { "type": "object", "required": [ "summary", "themes", "findings", "recommendations" ], "properties": { "summary": { "type": "string" }, "themes": { "type": "array", "items": { "type": "string" } }, "findings": { "type": "array", "items": { "type": "object" } }, "recommendations": { "type": "array", "items": { "type": "string" } } } }, "input": { "type": "object" }, "costUsd": { "type": "number" }, "durationMs": { "type": "integer" }, "createdAt": { "type": "string" } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "market": { "description": "Target market", "example": "jp", "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] }, "niche": { "description": "App Store niche", "example": "health-fitness", "type": "string", "enum": [ "games", "education", "health-fitness", "finance", "productivity", "lifestyle", "business", "weather", "utilities", "travel", "sports", "social-networking", "reference", "photo-video", "news", "navigation", "music", "entertainment", "books", "medical", "magazines-newspapers", "catalogs", "food-drink", "shopping", "stickers", "developer-tools", "graphics-design", "games-action", "games-adventure", "games-casual", "games-board", "games-card", "games-casino", "games-dice", "games-educational", "games-family", "games-music", "games-puzzle", "games-racing", "games-role-playing", "games-simulation", "games-sports", "games-strategy", "games-trivia", "games-word", "games-arcade", "communication", "dating", "video-players", "personalization", "auto-vehicles", "beauty", "comics", "events", "house-home", "parenting" ] }, "app": { "description": "App id", "example": "529479190", "type": "string" }, "query": { "description": "Research query", "type": "string" }, "position": { "description": "Screenshot position (1-based, default 1)", "type": "integer" }, "refresh": { "description": "Ignore cached analysis", "type": "boolean" }, "task_intent": { "description": "Caller task intent or context, used to shape output and logged (hashed)", "type": "string" }, "output_destination": { "description": "Target environment: code (compact JSON), doc (citations and links), chat (summary sentence), design_tool (visual assets and layout)", "type": "string", "enum": [ "code", "doc", "chat", "design_tool" ] } }, "required": [ "market" ] } } } } } }, "/api/i18n/rules": { "get": { "operationId": "i18n_check_rules", "summary": "i18n Readiness Rules Catalogue", "description": "Catalogue of automated internationalization and localization readiness rules across platforms and markets", "tags": [ "analysis" ], "parameters": [ { "name": "platform", "in": "query", "required": false, "description": "Filter by platform: core, ios, android, web, flutter, react-native, store, legal", "schema": { "description": "Filter by platform: core, ios, android, web, flutter, react-native, store, legal", "type": "string" } }, { "name": "market", "in": "query", "required": false, "description": "Filter by market code (e.g. de-DE, es-MX, ja-JP)", "schema": { "description": "Filter by market code (e.g. de-DE, es-MX, ja-JP)", "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer" }, "rules": { "type": "array" } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/i18n/reports/{param}": { "get": { "operationId": "i18n_report_api_i18n_reports_param", "summary": "Store and Retrieve i18n Reports", "description": "Store an uploaded i18n readiness report or retrieve a previously stored report by ID", "tags": [ "analysis" ], "parameters": [ { "name": "param", "in": "path", "required": true, "description": "Report UUID for retrieval", "schema": { "description": "Report UUID for retrieval", "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "verdict": { "type": "string" }, "verified_coverage": { "type": "number" }, "summary": { "type": "object" } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/i18n/reports": { "post": { "operationId": "i18n_report_api_i18n_reports", "summary": "Store and Retrieve i18n Reports", "description": "Store an uploaded i18n readiness report or retrieve a previously stored report by ID", "tags": [ "analysis" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "verdict": { "type": "string" }, "verified_coverage": { "type": "number" }, "summary": { "type": "object" } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "param": { "description": "Report UUID for retrieval", "type": "string" } } } } } } } }, "/api/watches": { "post": { "operationId": "create_watch", "summary": "Create Watch", "description": "Create an alert watch on an app or niche in markets", "tags": [ "account" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "target_type", "target_id" ], "properties": { "id": { "type": "string" }, "target_type": { "type": "string" }, "target_id": { "type": "string" }, "markets": { "type": "array", "items": { "type": "string" } }, "events": { "type": "array", "items": { "type": "string" } }, "threshold": { "type": "integer" }, "webhook_url": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "active": { "type": "boolean" }, "created_at": { "type": "string" } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target_type": { "example": "app", "type": "string", "enum": [ "app", "niche" ] }, "target_id": { "example": "529479190", "type": "string" }, "markets": { "example": [ "es", "de" ], "type": "array", "items": { "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] } }, "events": { "example": [ "listing", "rank", "ad" ], "type": "array", "items": { "type": "string" } }, "threshold": { "example": 5, "type": "integer" }, "webhook_url": { "example": "https://example.com/webhook", "type": "string" }, "webhook_secret": { "example": "whsec_sample", "type": "string" }, "email": { "example": "alerts@example.com", "type": "string" } }, "required": [ "target_type", "target_id" ] } } } } }, "get": { "operationId": "list_watches", "summary": "List Watches", "description": "List active alert watches for the current workspace", "tags": [ "account" ], "parameters": [ { "name": "target_id", "in": "query", "required": false, "schema": { "example": "529479190", "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "target_type", "target_id" ], "properties": { "id": { "type": "string" }, "target_type": { "type": "string" }, "target_id": { "type": "string" }, "markets": { "type": "array", "items": { "type": "string" } }, "events": { "type": "array", "items": { "type": "string" } }, "threshold": { "type": "integer" }, "webhook_url": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "active": { "type": "boolean" }, "created_at": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/watches/{id}/delete": { "post": { "operationId": "delete_watch", "summary": "Delete Watch", "description": "Delete or deactivate an alert watch", "tags": [ "account" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Path parameter id", "schema": { "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "id" ], "properties": { "ok": { "type": "boolean" }, "id": { "type": "string" } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } } } }, "/api/watches/{id}/events": { "get": { "operationId": "watch_events", "summary": "Watch Events", "description": "Get recent detected events and delivery logs for a watch", "tags": [ "account" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Path parameter id", "schema": { "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "example": 50, "type": "integer" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "watch_id", "event_type" ], "properties": { "id": { "type": "string" }, "watch_id": { "type": "string" }, "event_type": { "type": "string" }, "target_type": { "type": "string" }, "target_id": { "type": "string" }, "market_code": { "type": "string" }, "payload": { "type": "object" }, "created_at": { "type": "string" }, "deliveries": { "type": "array" } } } } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/market-glossary": { "get": { "operationId": "market_glossary_api_market_glossary", "summary": "Market Glossary", "description": "Extract domain terms and CTAs used by top-ranked storefront listings in a niche", "tags": [ "analysis" ], "parameters": [ { "name": "niche", "in": "query", "required": true, "description": "Niche or any collected genre slug (GET /api/meta genres)", "schema": { "description": "Niche or any collected genre slug (GET /api/meta genres)", "example": "health-fitness", "type": "string", "enum": [ "games", "education", "health-fitness", "finance", "productivity", "lifestyle", "business", "weather", "utilities", "travel", "sports", "social-networking", "reference", "photo-video", "news", "navigation", "music", "entertainment", "books", "medical", "magazines-newspapers", "catalogs", "food-drink", "shopping", "stickers", "developer-tools", "graphics-design", "games-action", "games-adventure", "games-casual", "games-board", "games-card", "games-casino", "games-dice", "games-educational", "games-family", "games-music", "games-puzzle", "games-racing", "games-role-playing", "games-simulation", "games-sports", "games-strategy", "games-trivia", "games-word", "games-arcade", "communication", "dating", "video-players", "personalization", "auto-vehicles", "beauty", "comics", "events", "house-home", "parenting" ] } }, { "name": "market", "in": "query", "required": true, "schema": { "example": "de", "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] } }, { "name": "variant", "in": "query", "required": false, "description": "Optional regional variant", "schema": { "description": "Optional regional variant", "type": "string" } }, { "name": "store", "in": "query", "required": false, "description": "ios (default) or play", "schema": { "description": "ios (default) or play", "type": "string", "enum": [ "ios", "play" ] } }, { "name": "format", "in": "query", "required": false, "description": "Export format", "schema": { "description": "Export format", "type": "string", "enum": [ "json", "csv", "tsv", "tbx" ] } }, { "name": "include_foreign", "in": "query", "required": false, "description": "Keep terms naming another market (flagged foreign_market_reference) in terms and CTAs; default false", "schema": { "description": "Keep terms naming another market (flagged foreign_market_reference) in terms and CTAs; default false", "type": "boolean" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "market", "variant", "niche", "terms", "ctas" ], "properties": { "market": { "type": "string" }, "variant": { "type": "string" }, "niche": { "type": "string" }, "store": { "type": "string" }, "total_apps": { "type": "number" }, "excluded_non_matching_listings": { "type": "number" }, "excluded_foreign_terms": { "type": "number" }, "terms": { "type": "array", "items": { "type": "object", "required": [ "term", "type", "doc_frequency", "score", "app_ids" ], "properties": { "term": { "type": "string" }, "type": { "type": "string" }, "doc_frequency": { "type": "number" }, "score": { "type": "number" }, "app_count": { "type": "number" }, "app_ids": { "type": "array", "items": { "type": "string" } }, "niche_spread": { "type": "number" }, "foreign_market_reference": { "type": "boolean" }, "foreign_market": { "type": "string" } } } }, "ctas": { "type": "array", "items": { "type": "object", "required": [ "term", "type", "doc_frequency", "score", "app_ids" ], "properties": { "term": { "type": "string" }, "type": { "type": "string" }, "doc_frequency": { "type": "number" }, "score": { "type": "number" }, "app_count": { "type": "number" }, "app_ids": { "type": "array", "items": { "type": "string" } }, "niche_spread": { "type": "number" }, "foreign_market_reference": { "type": "boolean" }, "foreign_market": { "type": "string" } } } }, "foreign_market_references": { "type": "array", "items": { "type": "object", "required": [ "term", "type", "doc_frequency", "score", "app_ids", "foreign_market_reference", "foreign_market" ], "properties": { "term": { "type": "string" }, "type": { "type": "string" }, "doc_frequency": { "type": "number" }, "score": { "type": "number" }, "app_count": { "type": "number" }, "app_ids": { "type": "array", "items": { "type": "string" } }, "niche_spread": { "type": "number" }, "foreign_market_reference": { "type": "boolean" }, "foreign_market": { "type": "string" } } } }, "format": { "type": "string" }, "export": { "type": "string" } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "market_glossary_api_market_glossary", "summary": "Market Glossary", "description": "Extract domain terms and CTAs used by top-ranked storefront listings in a niche", "tags": [ "analysis" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "market", "variant", "niche", "terms", "ctas" ], "properties": { "market": { "type": "string" }, "variant": { "type": "string" }, "niche": { "type": "string" }, "store": { "type": "string" }, "total_apps": { "type": "number" }, "excluded_non_matching_listings": { "type": "number" }, "excluded_foreign_terms": { "type": "number" }, "terms": { "type": "array", "items": { "type": "object", "required": [ "term", "type", "doc_frequency", "score", "app_ids" ], "properties": { "term": { "type": "string" }, "type": { "type": "string" }, "doc_frequency": { "type": "number" }, "score": { "type": "number" }, "app_count": { "type": "number" }, "app_ids": { "type": "array", "items": { "type": "string" } }, "niche_spread": { "type": "number" }, "foreign_market_reference": { "type": "boolean" }, "foreign_market": { "type": "string" } } } }, "ctas": { "type": "array", "items": { "type": "object", "required": [ "term", "type", "doc_frequency", "score", "app_ids" ], "properties": { "term": { "type": "string" }, "type": { "type": "string" }, "doc_frequency": { "type": "number" }, "score": { "type": "number" }, "app_count": { "type": "number" }, "app_ids": { "type": "array", "items": { "type": "string" } }, "niche_spread": { "type": "number" }, "foreign_market_reference": { "type": "boolean" }, "foreign_market": { "type": "string" } } } }, "foreign_market_references": { "type": "array", "items": { "type": "object", "required": [ "term", "type", "doc_frequency", "score", "app_ids", "foreign_market_reference", "foreign_market" ], "properties": { "term": { "type": "string" }, "type": { "type": "string" }, "doc_frequency": { "type": "number" }, "score": { "type": "number" }, "app_count": { "type": "number" }, "app_ids": { "type": "array", "items": { "type": "string" } }, "niche_spread": { "type": "number" }, "foreign_market_reference": { "type": "boolean" }, "foreign_market": { "type": "string" } } } }, "format": { "type": "string" }, "export": { "type": "string" } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "niche": { "description": "Niche or any collected genre slug (GET /api/meta genres)", "example": "health-fitness", "type": "string", "enum": [ "games", "education", "health-fitness", "finance", "productivity", "lifestyle", "business", "weather", "utilities", "travel", "sports", "social-networking", "reference", "photo-video", "news", "navigation", "music", "entertainment", "books", "medical", "magazines-newspapers", "catalogs", "food-drink", "shopping", "stickers", "developer-tools", "graphics-design", "games-action", "games-adventure", "games-casual", "games-board", "games-card", "games-casino", "games-dice", "games-educational", "games-family", "games-music", "games-puzzle", "games-racing", "games-role-playing", "games-simulation", "games-sports", "games-strategy", "games-trivia", "games-word", "games-arcade", "communication", "dating", "video-players", "personalization", "auto-vehicles", "beauty", "comics", "events", "house-home", "parenting" ] }, "market": { "example": "de", "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] }, "variant": { "description": "Optional regional variant", "type": "string" }, "store": { "description": "ios (default) or play", "type": "string", "enum": [ "ios", "play" ] }, "format": { "description": "Export format", "type": "string", "enum": [ "json", "csv", "tsv", "tbx" ] }, "include_foreign": { "description": "Keep terms naming another market (flagged foreign_market_reference) in terms and CTAs; default false", "type": "boolean" } }, "required": [ "niche", "market" ] } } } } } }, "/api/variant-lint": { "post": { "operationId": "variant_lint_api_variant_lint", "summary": "Variant Lint", "description": "Lint arbitrary copy against regional language dialect rules", "tags": [ "analysis" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "valid", "variant", "issues" ], "properties": { "valid": { "type": "boolean" }, "variant": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "required": [ "ruleId", "name", "matchedText", "index", "message", "severity", "suggestion", "source" ], "properties": { "ruleId": { "type": "string" }, "name": { "type": "string" }, "matchedText": { "type": "string" }, "index": { "type": "number" }, "message": { "type": "string" }, "severity": { "type": "string" }, "suggestion": { "type": "string" }, "source": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "example": "Descarga la app en tu celular", "type": "string" }, "variant": { "example": "es-MX", "type": "string" } }, "required": [ "text", "variant" ] } } } } }, "get": { "operationId": "variant_lint_api_variant_lint", "summary": "Variant Lint", "description": "Lint arbitrary copy against regional language dialect rules", "tags": [ "analysis" ], "parameters": [ { "name": "text", "in": "query", "required": true, "schema": { "example": "Descarga la app en tu celular", "type": "string" } }, { "name": "variant", "in": "query", "required": true, "schema": { "example": "es-MX", "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "valid", "variant", "issues" ], "properties": { "valid": { "type": "boolean" }, "variant": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "required": [ "ruleId", "name", "matchedText", "index", "message", "severity", "suggestion", "source" ], "properties": { "ruleId": { "type": "string" }, "name": { "type": "string" }, "matchedText": { "type": "string" }, "index": { "type": "number" }, "message": { "type": "string" }, "severity": { "type": "string" }, "suggestion": { "type": "string" }, "source": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/listing-check": { "post": { "operationId": "listing_check", "summary": "Listing Check", "description": "Validate proposed localized store copy against store limits and competitive benchmark", "tags": [ "analysis" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "valid", "store", "market", "niche", "limits", "competitive_benchmark" ], "properties": { "valid": { "type": "boolean" }, "store": { "type": "string" }, "market": { "type": "string" }, "variant": { "type": "string" }, "niche": { "type": "string" }, "limits": { "type": "object", "required": [ "valid", "errors", "warnings" ], "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "object" } }, "warnings": { "type": "array", "items": { "type": "object" } } } }, "competitive_benchmark": { "type": "object", "required": [ "title_length", "subtitle_length", "screenshot_count", "competitor_localization", "glossary_keyword_overlap" ], "properties": { "title_length": { "type": "object" }, "subtitle_length": { "type": "object" }, "screenshot_count": { "type": "object" }, "competitor_localization": { "type": "object" }, "glossary_keyword_overlap": { "type": "object" } } } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "niche": { "description": "Niche or any collected genre slug (GET /api/meta genres)", "example": "health-fitness", "type": "string", "enum": [ "games", "education", "health-fitness", "finance", "productivity", "lifestyle", "business", "weather", "utilities", "travel", "sports", "social-networking", "reference", "photo-video", "news", "navigation", "music", "entertainment", "books", "medical", "magazines-newspapers", "catalogs", "food-drink", "shopping", "stickers", "developer-tools", "graphics-design", "games-action", "games-adventure", "games-casual", "games-board", "games-card", "games-casino", "games-dice", "games-educational", "games-family", "games-music", "games-puzzle", "games-racing", "games-role-playing", "games-simulation", "games-sports", "games-strategy", "games-trivia", "games-word", "games-arcade", "communication", "dating", "video-players", "personalization", "auto-vehicles", "beauty", "comics", "events", "house-home", "parenting" ] }, "market": { "example": "de", "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] }, "title": { "example": "SuperFit: Kalorienzähler", "type": "string" }, "store": { "description": "ios (default) or play", "type": "string", "enum": [ "ios", "play" ] } }, "required": [ "niche", "market" ] } } } } } }, "/api/price-points": { "get": { "operationId": "price_points", "summary": "Price Points", "description": "Analyze what top apps in a niche charge per storefront from stored listing prices", "tags": [ "analysis" ], "parameters": [ { "name": "niche", "in": "query", "required": true, "description": "Niche or any collected genre slug (GET /api/meta genres)", "schema": { "description": "Niche or any collected genre slug (GET /api/meta genres)", "example": "health-fitness", "type": "string", "enum": [ "games", "education", "health-fitness", "finance", "productivity", "lifestyle", "business", "weather", "utilities", "travel", "sports", "social-networking", "reference", "photo-video", "news", "navigation", "music", "entertainment", "books", "medical", "magazines-newspapers", "catalogs", "food-drink", "shopping", "stickers", "developer-tools", "graphics-design", "games-action", "games-adventure", "games-casual", "games-board", "games-card", "games-casino", "games-dice", "games-educational", "games-family", "games-music", "games-puzzle", "games-racing", "games-role-playing", "games-simulation", "games-sports", "games-strategy", "games-trivia", "games-word", "games-arcade", "communication", "dating", "video-players", "personalization", "auto-vehicles", "beauty", "comics", "events", "house-home", "parenting" ] } }, { "name": "market", "in": "query", "required": true, "schema": { "example": "de", "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] } }, { "name": "store", "in": "query", "required": false, "description": "ios (default) or play", "schema": { "description": "ios (default) or play", "type": "string", "enum": [ "ios", "play" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "market", "niche", "store", "total_listings", "priced_count", "currency", "shares", "counts", "price_distribution", "rounding_conventions", "free_apps", "paid_apps", "unpriced_apps" ], "properties": { "market": { "type": "string" }, "niche": { "type": "string" }, "store": { "type": "string" }, "total_listings": { "type": "number" }, "priced_count": { "type": "number" }, "currency": { "type": "string" }, "shares": { "type": "object", "properties": { "free": { "type": "number" }, "paid": { "type": "number" }, "unpriced": { "type": "number" } } }, "counts": { "type": "object", "properties": { "free": { "type": "number" }, "paid": { "type": "number" }, "unpriced": { "type": "number" } } }, "price_distribution": { "type": "object", "properties": { "currency": { "type": "string" }, "min": { "type": "number" }, "p25": { "type": "number" }, "median": { "type": "number" }, "p75": { "type": "number" }, "max": { "type": "number" } } }, "rounding_conventions": { "type": "object", "properties": { "convention": { "type": "string" }, "description": { "type": "string" } } }, "free_apps": { "type": "array", "items": { "type": "object" } }, "paid_apps": { "type": "array", "items": { "type": "object" } }, "unpriced_apps": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/market-launch-checklist": { "get": { "operationId": "market_launch_checklist", "summary": "Market Launch Checklist", "description": "Consolidated per-market launch checklist merging B2B, profile, and statutory legal checks", "tags": [ "analysis" ], "parameters": [ { "name": "market", "in": "query", "required": true, "schema": { "example": "de", "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] } }, { "name": "report_id", "in": "query", "required": false, "description": "Optional stored i18n report UUID", "schema": { "description": "Optional stored i18n report UUID", "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "market", "locale", "variant_name", "profile", "total_items", "checklist" ], "properties": { "market": { "type": "string" }, "locale": { "type": "string" }, "variant_name": { "type": "string" }, "profile": { "type": "object", "properties": { "cut": { "type": "string" }, "monetisation": { "type": "object" }, "channels": { "type": "array", "items": { "type": "object" } }, "playPriority": { "type": "string" }, "note": { "type": [ "string", "null" ] } } }, "total_items": { "type": "number" }, "checklist": { "type": "array", "items": { "type": "object", "required": [ "id", "category", "title", "description", "status" ], "properties": { "id": { "type": "string" }, "category": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string" }, "stat": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "confidence": { "type": "string" }, "notice": { "type": "string" }, "severity": { "type": "string" }, "verify": { "type": "string" }, "finding": { "type": "object" } } } }, "i18n_report": { "type": [ "object", "null" ] } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/labels/profile": { "get": { "operationId": "label_profile", "summary": "Label Profile", "description": "Label shares for one market - how its listings, screenshots, ads or posts are labelled (subscription mentions, screenshot type, hook, post format), with item ids", "tags": [ "analysis" ], "parameters": [ { "name": "item_type", "in": "query", "required": true, "description": "What was labelled", "schema": { "description": "What was labelled", "example": "ad", "type": "string", "enum": [ "listing", "screenshot", "ad", "post" ] } }, { "name": "market", "in": "query", "required": true, "schema": { "example": "es", "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] } }, { "name": "niche", "in": "query", "required": false, "description": "Listings and screenshots: niche or genre (the top of its chart). Ads and posts: niche only. Omit for the whole market.", "schema": { "description": "Listings and screenshots: niche or genre (the top of its chart). Ads and posts: niche only. Omit for the whole market.", "type": "string", "enum": [ "games", "education", "health-fitness", "finance", "productivity", "lifestyle", "business", "weather", "utilities", "travel", "sports", "social-networking", "reference", "photo-video", "news", "navigation", "music", "entertainment", "books", "medical", "magazines-newspapers", "catalogs", "food-drink", "shopping", "stickers", "developer-tools", "graphics-design", "games-action", "games-adventure", "games-casual", "games-board", "games-card", "games-casino", "games-dice", "games-educational", "games-family", "games-music", "games-puzzle", "games-racing", "games-role-playing", "games-simulation", "games-sports", "games-strategy", "games-trivia", "games-word", "games-arcade", "communication", "dating", "video-players", "personalization", "auto-vehicles", "beauty", "comics", "events", "house-home", "parenting" ] } }, { "name": "store", "in": "query", "required": false, "description": "Listings and screenshots: ios (default) or play", "schema": { "description": "Listings and screenshots: ios (default) or play", "type": "string", "enum": [ "ios", "play" ] } }, { "name": "chart", "in": "query", "required": false, "description": "Listings and screenshots with a niche: chart type (default free)", "schema": { "description": "Listings and screenshots with a niche: chart type (default free)", "type": "string", "enum": [ "free", "paid", "grossing" ] } }, { "name": "top", "in": "query", "required": false, "description": "Listings and screenshots with a niche: the top N of the chart (1-100, default 100)", "schema": { "description": "Listings and screenshots with a niche: the top N of the chart (1-100, default 100)", "type": "integer" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "item_type", "scope", "items", "label_set_version", "labels" ], "properties": { "item_type": { "type": "string" }, "scope": { "type": "object" }, "items": { "type": "number", "description": "Labelled items in scope" }, "label_set_version": { "type": "string" }, "label_set_versions_read": { "type": "array", "items": { "type": "string" } }, "labels": { "type": "array", "items": { "type": "object", "required": [ "label", "kind", "n", "options" ], "properties": { "label": { "type": "string" }, "kind": { "type": "string", "description": "choice, score or yesno" }, "question": { "type": "string" }, "n": { "type": "number", "description": "Items with an answer to this label" }, "mean": { "type": [ "number", "null" ], "description": "Scores: mean of the probability-weighted score" }, "options": { "type": "array", "items": { "type": "object", "required": [ "value", "count", "share", "ids" ], "properties": { "value": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "count": { "type": "number" }, "share": { "type": [ "number", "null" ] }, "ids": { "type": "array", "items": { "type": "string" }, "description": "Item keys behind the share" } } } } } } }, "summary": { "type": "string" } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/labels/compare": { "get": { "operationId": "label_compare", "summary": "Label Compare", "description": "Label differences between two markets - share of each answer per label for listings, screenshots, ads or posts, largest differences first, with item ids", "tags": [ "compare" ], "parameters": [ { "name": "item_type", "in": "query", "required": true, "description": "What was labelled", "schema": { "description": "What was labelled", "example": "ad", "type": "string", "enum": [ "listing", "screenshot", "ad", "post" ] } }, { "name": "from", "in": "query", "required": true, "description": "Reference market", "schema": { "description": "Reference market", "example": "us", "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] } }, { "name": "to", "in": "query", "required": true, "description": "Market compared with it", "schema": { "description": "Market compared with it", "example": "es", "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] } }, { "name": "niche", "in": "query", "required": false, "description": "Listings and screenshots: niche or genre (the top of its chart). Ads and posts: niche only. Omit for the whole market.", "schema": { "description": "Listings and screenshots: niche or genre (the top of its chart). Ads and posts: niche only. Omit for the whole market.", "type": "string", "enum": [ "games", "education", "health-fitness", "finance", "productivity", "lifestyle", "business", "weather", "utilities", "travel", "sports", "social-networking", "reference", "photo-video", "news", "navigation", "music", "entertainment", "books", "medical", "magazines-newspapers", "catalogs", "food-drink", "shopping", "stickers", "developer-tools", "graphics-design", "games-action", "games-adventure", "games-casual", "games-board", "games-card", "games-casino", "games-dice", "games-educational", "games-family", "games-music", "games-puzzle", "games-racing", "games-role-playing", "games-simulation", "games-sports", "games-strategy", "games-trivia", "games-word", "games-arcade", "communication", "dating", "video-players", "personalization", "auto-vehicles", "beauty", "comics", "events", "house-home", "parenting" ] } }, { "name": "store", "in": "query", "required": false, "description": "Listings and screenshots: ios (default) or play", "schema": { "description": "Listings and screenshots: ios (default) or play", "type": "string", "enum": [ "ios", "play" ] } }, { "name": "chart", "in": "query", "required": false, "description": "Listings and screenshots with a niche: chart type (default free)", "schema": { "description": "Listings and screenshots with a niche: chart type (default free)", "type": "string", "enum": [ "free", "paid", "grossing" ] } }, { "name": "top", "in": "query", "required": false, "description": "Listings and screenshots with a niche: the top N of the chart (1-100, default 100)", "schema": { "description": "Listings and screenshots with a niche: the top N of the chart (1-100, default 100)", "type": "integer" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "item_type", "from", "to", "scope", "min_sample", "labels" ], "properties": { "item_type": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "scope": { "type": "object" }, "items_from": { "type": "number" }, "items_to": { "type": "number" }, "min_sample": { "type": "number", "description": "Labelled items needed on each side before a label makes a claim" }, "label_set_version": { "type": "string" }, "label_set_versions_read": { "type": "array", "items": { "type": "string" } }, "labels": { "type": "array", "items": { "type": "object", "required": [ "label", "kind", "n_from", "n_to", "enough", "differences" ], "properties": { "label": { "type": "string" }, "kind": { "type": "string" }, "question": { "type": "string" }, "n_from": { "type": "number" }, "n_to": { "type": "number" }, "enough": { "type": "boolean" }, "note": { "type": "string", "description": "\"not enough labelled items\" when either side is under min_sample" }, "largest_difference": { "type": [ "number", "null" ] }, "mean_from": { "type": [ "number", "null" ] }, "mean_to": { "type": [ "number", "null" ] }, "mean_difference": { "type": [ "number", "null" ] }, "differences": { "type": "array", "items": { "type": "object", "required": [ "value", "from", "to", "difference" ], "properties": { "value": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "from": { "type": "object", "description": "{ count, share, ids }" }, "to": { "type": "object", "description": "{ count, share, ids }" }, "difference": { "type": "number", "description": "Share in to minus share in from" } } } } } } }, "summary": { "type": "string" } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/labels/language-fit": { "get": { "operationId": "language_fit", "summary": "Language Fit", "description": "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", "tags": [ "analysis" ], "parameters": [ { "name": "market", "in": "query", "required": true, "schema": { "example": "mx", "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] } }, { "name": "niche", "in": "query", "required": false, "description": "Listings and screenshots: niche or genre (the top of its chart). Ads: niche only. Omit for the whole market.", "schema": { "description": "Listings and screenshots: niche or genre (the top of its chart). Ads: niche only. Omit for the whole market.", "type": "string", "enum": [ "games", "education", "health-fitness", "finance", "productivity", "lifestyle", "business", "weather", "utilities", "travel", "sports", "social-networking", "reference", "photo-video", "news", "navigation", "music", "entertainment", "books", "medical", "magazines-newspapers", "catalogs", "food-drink", "shopping", "stickers", "developer-tools", "graphics-design", "games-action", "games-adventure", "games-casual", "games-board", "games-card", "games-casino", "games-dice", "games-educational", "games-family", "games-music", "games-puzzle", "games-racing", "games-role-playing", "games-simulation", "games-sports", "games-strategy", "games-trivia", "games-word", "games-arcade", "communication", "dating", "video-players", "personalization", "auto-vehicles", "beauty", "comics", "events", "house-home", "parenting" ] } }, { "name": "store", "in": "query", "required": false, "description": "Listings and screenshots: ios (default) or play", "schema": { "description": "Listings and screenshots: ios (default) or play", "type": "string", "enum": [ "ios", "play" ] } }, { "name": "chart", "in": "query", "required": false, "description": "Listings and screenshots with a niche: chart type (default free)", "schema": { "description": "Listings and screenshots with a niche: chart type (default free)", "type": "string", "enum": [ "free", "paid", "grossing" ] } }, { "name": "top", "in": "query", "required": false, "description": "Listings and screenshots with a niche: the top N of the chart (1-100, default 100)", "schema": { "description": "Listings and screenshots with a niche: the top N of the chart (1-100, default 100)", "type": "integer" } }, { "name": "item_types", "in": "query", "required": false, "description": "listing, screenshot, ad (default all three)", "schema": { "description": "listing, screenshot, ad (default all three)", "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "market", "locale", "language", "min_sample", "types" ], "properties": { "market": { "type": "string" }, "locale": { "type": "string" }, "language": { "type": "string" }, "min_sample": { "type": "number" }, "types": { "type": "array", "items": { "type": "object", "required": [ "item_type", "n", "enough" ], "properties": { "item_type": { "type": "string" }, "n": { "type": "number" }, "enough": { "type": "boolean" }, "note": { "type": "string" }, "scope": { "type": "object" }, "match": { "type": "object", "description": "{ count, share, ids }: the market's language and variant" }, "variant_mismatch": { "type": "object", "description": "The market's language, another market's variant" }, "neutral": { "type": "object", "description": "Ads with no variant markers" }, "mixed": { "type": "object", "description": "Listings whose copy mixes languages" }, "foreign": { "type": "object", "description": "Not the market's language" }, "no_text": { "type": "object", "description": "Screenshots without text: not in n" } } } }, "summary": { "type": "string" } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/market-take": { "get": { "operationId": "market_take", "summary": "Market Take", "description": "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", "tags": [ "brief" ], "parameters": [ { "name": "market", "in": "query", "required": true, "description": "Any market except the reference (us)", "schema": { "description": "Any market except the reference (us)", "example": "es", "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] } }, { "name": "niche", "in": "query", "required": true, "schema": { "example": "finance", "type": "string", "enum": [ "games", "education", "health-fitness", "finance", "productivity", "lifestyle" ] } }, { "name": "week", "in": "query", "required": false, "description": "ISO week YYYY-WW (default: the latest take)", "schema": { "description": "ISO week YYYY-WW (default: the latest take)", "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "market", "niche", "week", "reference_market", "headline", "points", "caveats", "model" ], "properties": { "market": { "type": "string" }, "niche": { "type": "string" }, "week": { "type": "string", "description": "ISO week, YYYY-WW" }, "reference_market": { "type": "string" }, "label_set_version": { "type": "string" }, "headline": { "type": "string" }, "points": { "type": "array", "items": { "type": "object", "required": [ "claim", "evidence_ids", "labels" ], "properties": { "claim": { "type": "string" }, "evidence_ids": { "type": "array", "items": { "type": "string" } }, "labels": { "type": "array", "items": { "type": "string" } } } } }, "caveats": { "type": "array", "items": { "type": "string" } }, "dropped_points": { "type": "number", "description": "Points the model wrote without evidence, dropped before storing" }, "provider": { "type": "string" }, "model": { "type": "string" }, "created_at": { "type": "string" }, "summary": { "type": "string" } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/agent/app": { "get": { "operationId": "agent_app", "summary": "App", "description": "One app across stores, Brand, Paid and Organic, and markets, as a digest with links and next steps", "tags": [ "app" ], "parameters": [ { "name": "app", "in": "query", "required": true, "description": "App name, App Store id, play: or store URL", "schema": { "description": "App name, App Store id, play: or store URL", "example": "Duolingo", "type": "string" } }, { "name": "markets", "in": "query", "required": false, "description": "Markets to cover (default: where the app charts, up to 5)", "schema": { "description": "Markets to cover (default: where the app charts, up to 5)", "example": [ "de", "mx" ], "type": "array", "items": { "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] } } }, { "name": "store", "in": "query", "required": false, "description": "ios or play (default: both where linked)", "schema": { "description": "ios or play (default: both where linked)", "type": "string", "enum": [ "ios", "play" ] } }, { "name": "focus", "in": "query", "required": false, "description": "overview (default) or one part in depth", "schema": { "description": "overview (default) or one part in depth", "type": "string", "enum": [ "overview", "brand", "paid", "organic", "reviews", "changes" ] } }, { "name": "platform", "in": "query", "required": false, "description": "Paid/Organic platform filter", "schema": { "description": "Paid/Organic platform filter", "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "Creative format filter", "schema": { "description": "Creative format filter", "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "Only items observed on or after this date", "schema": { "description": "Only items observed on or after this date", "type": "string", "format": "date" } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor from a previous answer", "schema": { "description": "Cursor from a previous answer", "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "summary", "links", "next", "coverage" ], "properties": { "summary": { "type": "string" }, "links": { "type": "object" }, "next": { "type": "array", "items": { "type": "string" } }, "coverage": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/agent/market": { "get": { "operationId": "agent_market", "summary": "Market", "description": "One market and genre - what wins there, optionally next to a reference app or a home market, as a digest", "tags": [ "compare" ], "parameters": [ { "name": "market", "in": "query", "required": true, "schema": { "example": "mx", "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] } }, { "name": "genre", "in": "query", "required": true, "description": "Genre in plain words or a slug", "schema": { "description": "Genre in plain words or a slug", "example": "language learning", "type": "string" } }, { "name": "like", "in": "query", "required": false, "description": "Reference app: name, id or store URL", "schema": { "description": "Reference app: name, id or store URL", "example": "Duolingo", "type": "string" } }, { "name": "vs", "in": "query", "required": false, "description": "Home market to compare against", "schema": { "description": "Home market to compare against", "example": "us", "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] } }, { "name": "store", "in": "query", "required": false, "description": "ios or play", "schema": { "description": "ios or play", "type": "string", "enum": [ "ios", "play" ] } }, { "name": "focus", "in": "query", "required": false, "description": "overview (default) or one part in depth", "schema": { "description": "overview (default) or one part in depth", "type": "string", "enum": [ "overview", "brand", "paid", "organic", "pricing", "language", "launch" ] } }, { "name": "platform", "in": "query", "required": false, "description": "Paid/Organic platform filter", "schema": { "description": "Paid/Organic platform filter", "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "Creative format filter", "schema": { "description": "Creative format filter", "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor from a previous answer", "schema": { "description": "Cursor from a previous answer", "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "summary", "links", "next", "coverage" ], "properties": { "summary": { "type": "string" }, "links": { "type": "object" }, "next": { "type": "array", "items": { "type": "string" } }, "coverage": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/agent/check": { "post": { "operationId": "agent_check", "summary": "Check", "description": "Grade the user's listing, screenshots, ad, name, repository or live app for a target market - rule checks, criteria and reference examples", "tags": [ "brief" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "summary", "links", "next", "coverage" ], "properties": { "summary": { "type": "string" }, "links": { "type": "object" }, "next": { "type": "array", "items": { "type": "string" } }, "coverage": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "market": { "example": "mx", "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] }, "what": { "example": "app", "type": "string", "enum": [ "listing", "screenshots", "ad", "name", "repo", "website", "app" ] }, "url": { "description": "For what: website: the page to check (home or pricing page)", "type": "string" }, "genre": { "description": "Genre in plain words or a slug", "type": "string" }, "from": { "description": "The user's home market", "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] }, "app": { "description": "App name, id or store URL", "example": "570060128", "type": "string" }, "name": { "description": "For what: name", "type": "string" }, "listing": { "description": "For what: listing. JSON object: title, subtitle, keywords, promotional_text, description, screenshot_count", "type": "string" }, "store": { "description": "ios or play", "type": "string", "enum": [ "ios", "play" ] } }, "required": [ "market", "what" ] } } } } } }, "/api/agent/workspace": { "post": { "operationId": "agent_workspace", "summary": "Workspace", "description": "The workspace's apps, competitors per market, target markets, watches and changes, saved items and usage", "tags": [ "account" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "summary", "links", "next", "coverage" ], "properties": { "summary": { "type": "string" }, "links": { "type": "object" }, "next": { "type": "array", "items": { "type": "string" } }, "coverage": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Invalid request parameters or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient balance or plan quota limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - missing required scope or permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal threefold server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "description": "get (default)", "example": "get", "type": "string", "enum": [ "get", "set_apps", "set_competitors", "set_markets", "watch", "unwatch", "changes", "save", "saved" ] }, "apps": { "description": "Names, ids or store URLs", "type": "array", "items": { "type": "string" } }, "market": { "description": "set_competitors: the market", "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] }, "markets": { "description": "set_markets, watch", "type": "array", "items": { "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] } }, "home": { "description": "set_markets: home market", "type": "string", "enum": [ "gb", "us", "es", "mx", "ar", "br", "de", "fr", "jp", "kr", "ca", "au", "tw", "it", "nl", "tr", "sa", "in", "ca-fr", "hk", "th", "id", "ch", "pl", "se", "ae", "vn", "ph", "pt", "at", "co", "cl" ] }, "item": { "description": "save: JSON object with title, tool, args, note", "type": "string" }, "since": { "description": "changes: since this date", "type": "string", "format": "date" } } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key (tf_live_... / tf_test_...)" } }, "schemas": { "Error": { "type": "object", "required": [ "error", "code", "whose_error", "retryable", "hint" ], "properties": { "error": { "type": "string", "description": "Human-readable error description" }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "sign_in_required", "forbidden", "not_found", "conflict", "rate_limited", "insufficient_balance", "spend_cap_exceeded", "fresh_pull_unpriced", "plan_limit", "upstream_error", "internal_error", "not_implemented" ] }, "whose_error": { "type": "string", "enum": [ "caller", "upstream", "threefold" ] }, "retryable": { "type": "boolean" }, "hint": { "type": "string", "description": "Actionable suggestion to resolve error" }, "balance_micro_usd": { "type": "integer" }, "required_micro_usd": { "type": "integer" }, "cap_micro_usd": { "type": "integer" }, "spent_micro_usd": { "type": "integer" }, "endpoint_id": { "type": "string" } } } } } }