{"openapi":"3.1.0","info":{"title":"Apple App Store API (Bowmark)","version":"e833508f87ff","description":"Search every iPhone, iPad and Mac app Apple lists, read one app's price, rating, reviews, in-app purchases and privacy labels, and see what is charting right now — off Apple's own keyless public API and its server-rendered store pages.\n\nEvery function Bowmark has for Apple App Store (apps.apple.com) as one HTTP call. Each runs on Bowmark's infrastructure with the same billing, rules and response envelope as `POST /v1/run`. The whole API: https://api.bowmark.ai/openapi.json. Guide: https://bowmark.ai/docs/api.","contact":{"email":"support@bowmark.ai","url":"https://bowmark.ai/docs/api"}},"servers":[{"url":"https://api.bowmark.ai"}],"security":[{"bearer":[]},{"apiKeyHeader":[]}],"paths":{"/v1/sites/app_store/searchApps":{"post":{"operationId":"searchApps","summary":"Search the App Store for what a person would actually type — \"budget tracker\", \"slack\", \"photo editor\" — and get back the apps Apple's own store search ranks, narrowable by platform (iPhone/iPad/Mac),","description":"Search the App Store for what a person would actually type — \"budget tracker\", \"slack\", \"photo editor\" — and get back the apps Apple's own store search ranks, narrowable by platform (iPhone/iPad/Mac), category and store country. THE door: every id-taking function in this provider is fed by an id this returns.\n\nCalls `bowmark.providers.app_store.searchApps`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<AppStoreSearchResult>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"args":{"$ref":"#/components/schemas/SearchAppsArgs","description":"TypeScript: `SearchAppsArgs`"}},"required":["args"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/app_store/getApp":{"post":{"operationId":"getApp","summary":"Read one app the way its store listing reads: name, developer and seller, price, average rating and rating count (overall and for the current version), category and genres, the full description, what'","description":"Read one app the way its store listing reads: name, developer and seller, price, average rating and rating count (overall and for the current version), category and genres, the full description, what's new in this version, version, size, minimum iOS, languages, age rating, release and last-update dates, the icon, and every iPhone, iPad and Apple TV screenshot URL — from a numeric app id, its bundle id, or an apps.apple.com URL a person pasted, whose country picks the storefront. The core read of the provider, and the cheapest call in it: one request.\n\nCalls `bowmark.providers.app_store.getApp`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<AppStoreApp>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"args":{"$ref":"#/components/schemas/GetAppArgs","description":"TypeScript: `GetAppArgs`"}},"required":["args"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/app_store/getApps":{"post":{"operationId":"getApps","summary":"Read up to fifty apps in ONE request, for when an agent already holds a list of ids — the ranks past the top of a chart, the ids in a \"you might also like\" shelf, a comparison a person asked for.","description":"Read up to fifty apps in ONE request, for when an agent already holds a list of ids — the ranks past the top of a chart, the ids in a \"you might also like\" shelf, a comparison a person asked for. Same record as getApp, one round trip instead of fifty; an id that does not resolve is named in warnings rather than silently dropped.\n\nCalls `bowmark.providers.app_store.getApps`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<GetAppsResult>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"args":{"$ref":"#/components/schemas/GetAppsArgs","description":"TypeScript: `GetAppsArgs`"}},"required":["args"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/app_store/getAppDetails":{"post":{"operationId":"getAppDetails","summary":"Everything the store page shows that the API does not: the five-star rating histogram, the app's live chart position, every in-app purchase by name and price, Apple's privacy nutrition labels, the Edi","description":"Everything the store page shows that the API does not: the five-star rating histogram, the app's live chart position, every in-app purchase by name and price, Apple's privacy nutrition labels, the Editors' Choice citation, the latest version's notes, size, seller, compatibility, languages, copyright, accessibility features, developer-website and privacy-policy links, and the editorial stories it has been featured in. Every field is optional — a missing shelf on the app's own page is an absent field here, never a throw.\n\nCalls `bowmark.providers.app_store.getAppDetails`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<AppStoreAppDetails>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"args":{"$ref":"#/components/schemas/GetAppDetailsArgs","description":"TypeScript: `GetAppDetailsArgs`"}},"required":["args"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/app_store/listSimilarApps":{"post":{"operationId":"listSimilarApps","summary":"Answer \"what else is like this one\" with the App Store's own You Might Also Like shelf — the apps Apple itself puts next to this one, each with its name, tagline, developer, age rating, price and the ","description":"Answer \"what else is like this one\" with the App Store's own You Might Also Like shelf — the apps Apple itself puts next to this one, each with its name, tagline, developer, age rating, price and the id every function here takes. What an agent reaches for when the app a person named is wrong, too expensive, or not on their device. Shares getAppDetails' page cache, so calling both for one app costs one fetch.\n\nCalls `bowmark.providers.app_store.listSimilarApps`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<AppStoreSimilarAppsResult>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"args":{"$ref":"#/components/schemas/ListSimilarAppsArgs","description":"TypeScript: `ListSimilarAppsArgs`"}},"required":["args"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/app_store/listDeveloperApps":{"post":{"operationId":"listDeveloperApps","summary":"List every app one developer has on the store — from the developer's numeric artist id, their apps.apple.com developer URL, or just one of their apps (resolved to its developer first).","description":"List every app one developer has on the store — from the developer's numeric artist id, their apps.apple.com developer URL, or just one of their apps (resolved to its developer first). The read behind \"what else did the people who made this write\" and behind checking whether an app is from who it claims to be.\n\nCalls `bowmark.providers.app_store.listDeveloperApps`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<ListDeveloperAppsResult>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"args":{"$ref":"#/components/schemas/ListDeveloperAppsArgs","description":"TypeScript: `ListDeveloperAppsArgs`"}},"required":["args"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/app_store/listCategories":{"post":{"operationId":"listCategories","summary":"List every category and subcategory the App Store sorts apps into — Business, Education, Games and its nineteen sub-genres, and the rest — each with the numeric id that narrows searchApps and listTopC","description":"List every category and subcategory the App Store sorts apps into — Business, Education, Games and its nineteen sub-genres, and the rest — each with the numeric id that narrows searchApps and listTopCharts. The finder that lets an agent holding the word \"puzzle\" reach a real listing without being told an id.\n\nCalls `bowmark.providers.app_store.listCategories`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<ListCategoriesResult>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/app_store/listCollections":{"post":{"operationId":"listCollections","summary":"List the named collections on the App Store's Games tab or Apps tab — Apple's own shelves such as \"Must-Play Games\", \"New Games We Love\" and \"Editors' Choice\" — each with its title and the apps on it,","description":"List the named collections on the App Store's Games tab or Apps tab — Apple's own shelves such as \"Must-Play Games\", \"New Games We Love\" and \"Editors' Choice\" — each with its title and the apps on it, every app carrying the id getApps and getApp take. The door to what Apple is pushing in games or apps right now, which the Today tab and the charts do not carry. Takes tab \"games\" or \"apps\"; device is iPhone (default) or iPad.\n\nCalls `bowmark.providers.app_store.listCollections`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<ListCollectionsResult>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"args":{"$ref":"#/components/schemas/ListCollectionsArgs","description":"TypeScript: `ListCollectionsArgs`"}},"required":["args"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/app_store/listTopCharts":{"post":{"operationId":"listTopCharts","summary":"What is charting on the App Store right now — top free or top paid, on iPhone, iPad, Mac, Apple Watch or Apple TV, for the whole store or narrowed to any genre id listCategories returns — in rank orde","description":"What is charting on the App Store right now — top free or top paid, on iPhone, iPad, Mac, Apple Watch or Apple TV, for the whole store or narrowed to any genre id listCategories returns — in rank order, each entry with its position, name, tagline, developer, age rating, price and the id every other function here takes. The question this provider exists to answer that no search engine answers, because the answer changes every day.\n\nCalls `bowmark.providers.app_store.listTopCharts`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<ListTopChartsResult>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"args":{"$ref":"#/components/schemas/ListTopChartsArgs","description":"TypeScript: `ListTopChartsArgs`"}},"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/app_store/getStory":{"post":{"operationId":"getStory","summary":"Read an App Store editorial story — the Today-tab piece Apple's editors wrote (\"Master Your Major\", \"About In-App Purchases\") — its heading, title, body and the apps it recommends, each with the id ev","description":"Read an App Store editorial story — the Today-tab piece Apple's editors wrote (\"Master Your Major\", \"About In-App Purchases\") — its heading, title, body and the apps it recommends, each with the id every other function here takes. Takes the story URL getAppDetails().featuredIn[].url returns, or a bare story id plus the platform it was featured under. How an agent answers \"what does Apple say about this\" and finds apps nobody searches for by name.\n\nCalls `bowmark.providers.app_store.getStory`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<AppStoreStory>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"args":{"$ref":"#/components/schemas/GetStoryArgs","description":"TypeScript: `GetStoryArgs`"}},"required":["args"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/app_store/listReviews":{"post":{"operationId":"listReviews","summary":"Read what people actually wrote about an app — the review body, its title, the star rating, the reviewer's name, which app version they were on, and how many others found it helpful — up to 500 in one","description":"Read what people actually wrote about an app — the review body, its title, the star rating, the reviewer's name, which app version they were on, and how many others found it helpful — up to 500 in one call (fifty by default), newest first or most helpful first, for one storefront. Takes a numeric app id, a bundle id or an apps.apple.com URL. The one read that turns \"4.1 stars\" into a reason.\n\nCalls `bowmark.providers.app_store.listReviews`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<ListReviewsResult>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"args":{"$ref":"#/components/schemas/ListReviewsArgs","description":"TypeScript: `ListReviewsArgs`"}},"required":["args"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/app_store/listTodayStories":{"post":{"operationId":"listTodayStories","summary":"List the editorial stories Apple is featuring on the Today tab right now — the page a person actually sees when they open the App Store — each with the id and URL getStory takes.","description":"List the editorial stories Apple is featuring on the Today tab right now — the page a person actually sees when they open the App Store — each with the id and URL getStory takes. The door into getStory for an agent that holds no app yet, rather than one that already does.\n\nCalls `bowmark.providers.app_store.listTodayStories`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<ListTodayStoriesResult>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"args":{"$ref":"#/components/schemas/ListTodayStoriesArgs","description":"TypeScript: `ListTodayStoriesArgs`"}},"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/app_store/listVersionHistory":{"post":{"operationId":"listVersionHistory","summary":"Read an app's update history the way its store page shows it — every recent release (about 25), newest first, each with its version number, release date and what the developer said changed.","description":"Read an app's update history the way its store page shows it — every recent release (about 25), newest first, each with its version number, release date and what the developer said changed. The read behind \"did the last update break this\" and \"when did they add X\". Shares getAppDetails' page cache, so calling both costs one fetch.\n\nCalls `bowmark.providers.app_store.listVersionHistory`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<ListVersionHistoryResult>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"args":{"$ref":"#/components/schemas/ListVersionHistoryArgs","description":"TypeScript: `ListVersionHistoryArgs`"}},"required":["args"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/app_store/listAppEvents":{"post":{"operationId":"listAppEvents","summary":"List the in-app events an app is running or about to run — a game's weekend event, a challenge, a premiere — each with its title, description, Apple's label for it, start and end time and link.","description":"List the in-app events an app is running or about to run — a game's weekend event, a challenge, a premiere — each with its title, description, Apple's label for it, start and end time and link. Answers \"is anything on in this game this week\". An app running no events returns an empty list.\n\nCalls `bowmark.providers.app_store.listAppEvents`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<ListAppEventsResult>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"args":{"$ref":"#/components/schemas/ListAppEventsArgs","description":"TypeScript: `ListAppEventsArgs`"}},"required":["args"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/app_store/listArcadeGames":{"post":{"operationId":"listArcadeGames","summary":"List the games Apple is showing on its Apple Arcade page — what a subscription gets you, including games marked coming soon — each with its name, developer, tagline, age rating, star rating, the shelf","description":"List the games Apple is showing on its Apple Arcade page — what a subscription gets you, including games marked coming soon — each with its name, developer, tagline, age rating, star rating, the shelf it sits on, and the id getApp and getApps take. For iPhone, iPad or Mac, in any storefront.\n\nCalls `bowmark.providers.app_store.listArcadeGames`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<ListArcadeGamesResult>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"args":{"$ref":"#/components/schemas/ListArcadeGamesArgs","description":"TypeScript: `ListArcadeGamesArgs`"}},"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/app_store/listPurchasedApps":{"post":{"operationId":"listPurchasedApps","summary":"List the apps the caller's own Apple Account has bought or downloaded, with what was paid and when — Apple's own purchase history, the list behind reportaproblem.apple.com.","description":"List the apps the caller's own Apple Account has bought or downloaded, with what was paid and when — Apple's own purchase history, the list behind reportaproblem.apple.com. NEEDS THE CALLER SIGNED IN to their Apple Account; the run pauses for that sign-in. Returns Apple's JSON as raw (its signed-in field shape is not yet measured) plus a nextBatchId to page back through older purchases.\n\nCalls `bowmark.providers.app_store.listPurchasedApps`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<ListPurchasedAppsResult>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"args":{"$ref":"#/components/schemas/ListPurchasedAppsArgs","description":"TypeScript: `ListPurchasedAppsArgs`"},"opts":{"type":"object","properties":{"connection":{"type":"string"}},"required":["connection"],"additionalProperties":true,"description":"TypeScript: `ConnectionOption`"}},"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/app_store/listSubscriptions":{"post":{"operationId":"listSubscriptions","summary":"List the App Store subscriptions the caller's own Apple Account is paying for — Apple's own subscriptions page.","description":"List the App Store subscriptions the caller's own Apple Account is paying for — Apple's own subscriptions page. NEEDS THE CALLER SIGNED IN to their Apple Account; the run pauses for that sign-in. Returns the page as raw (its signed-in shape is not yet measured). Read only: never cancels or starts a subscription.\n\nCalls `bowmark.providers.app_store.listSubscriptions`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<ListSubscriptionsResult>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"opts":{"type":"object","properties":{"connection":{"type":"string"}},"required":["connection"],"additionalProperties":true,"description":"TypeScript: `ConnectionOption`"}},"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Your Bowmark API key."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-Bowmark-Key"}},"responses":{"NotFound":{"description":"No such site or function.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}},"schemas":{"RunEnvelope":{"type":"object","description":"What a run returns. `status` says whether the SCRIPT succeeded. A script that threw or paused for a login is still HTTP 200. Branch on `status`, not on the HTTP code.","required":["ok","status","result","logs","error","ms"],"properties":{"runId":{"type":"string","description":"Stable id for this run. Quote it in a support or `report` message."},"ok":{"type":"boolean","description":"False only when the run produced nothing usable."},"status":{"type":"string","enum":["ok","error","partial","needs_user"],"description":"`partial`: the result is real but some calls failed (see `incomplete`); `ok` stays true. `needs_user`: a person must sign in to a site first. Relay `meta.handoff.url` to them, then run again."},"egress":{"type":"string","enum":["default","link"],"description":"The egress the run was given, present only when the request asked for one. `link`: every request went through the caller's own Chrome (Bowmark Buddy)."},"result":{"description":"Whatever the script `return`ed. Any JSON value."},"logs":{"type":"array","items":{"type":"string"},"description":"Lines the script wrote with `log(...)`."},"error":{"type":["string","null"],"description":"Why the run failed, in plain words. Null on success."},"ms":{"type":"integer","description":"How long the script itself ran, in milliseconds."},"queuedMs":{"type":"integer","description":"How long the run waited for a worker before starting. Present only when it was a second or more."},"needs":{"type":"array","description":"The sign-ins this script is waiting on. Present when `status` is `needs_user`.","items":{"type":"object","required":["capability","provider","providerTitle","kind"],"properties":{"capability":{"type":"string"},"provider":{"type":"string"},"providerTitle":{"type":"string","description":"The site's name, to show a person."},"kind":{"type":"string"}}}},"incomplete":{"type":"object","description":"Present only when `status` is `partial`: which calls did not answer.","properties":{"summary":{"type":"string"},"totalCalls":{"type":"integer"}},"additionalProperties":true},"emptyHanded":{"type":"object","description":"Present when the script returned nothing while its calls returned rows, usually a filter that matched none of the site's own labels. Lists the label values the calls actually returned.","additionalProperties":true},"notes":{"type":"array","description":"Caveats a call attached to a complete answer. Never changes `status`.","items":{"type":"object","properties":{"path":{"type":"string"},"notes":{"type":"array","items":{"type":"string"}}}}},"meta":{"type":"object","properties":{"handoff":{"type":"object","description":"A single-use sign-in link for a person to open. Expires at `expiresAt`.","properties":{"ref":{"type":"string"},"url":{"type":"string","format":"uri"},"expiresAt":{"type":"string","format":"date-time"}}},"concurrency":{"type":"object","description":"On a 429: how many runs are in flight and when to retry.","properties":{"limit":{"type":"integer"},"inFlight":{"type":"integer"},"retryAfterSeconds":{"type":"integer"}}}},"additionalProperties":true},"notice":{"type":"object","description":"Set when the account owner has not accepted the current Terms. Relay it to them.","additionalProperties":true}}},"AppStoreChartDevice":{"anyOf":[{"$ref":"#/components/schemas/AppStoreDevice"},{"const":"watch"},{"const":"tv"}]},"AppStoreChartKind":{"anyOf":[{"const":"free"},{"const":"paid"}]},"AppStoreCollectionDevice":{"anyOf":[{"const":"iphone"},{"const":"ipad"}]},"AppStoreCollectionTab":{"anyOf":[{"const":"games"},{"const":"apps"}]},"AppStoreDevice":{"anyOf":[{"const":"iphone"},{"const":"ipad"},{"const":"mac"}]},"AppStorePlatform":{"anyOf":[{"const":"iphone"},{"const":"ipad"},{"const":"mac"}]},"AppStoreReviewSort":{"anyOf":[{"const":"mostRecent"},{"const":"mostHelpful"}]},"GetAppArgs":{"type":"object","properties":{"app":{"anyOf":[{"type":"string"},{"type":"number"}]},"country":{"type":"string"}},"required":["app"],"additionalProperties":true},"GetAppDetailsArgs":{"type":"object","properties":{"app":{"anyOf":[{"type":"string"},{"type":"number"}]},"country":{"type":"string"}},"required":["app"],"additionalProperties":true},"GetAppsArgs":{"type":"object","properties":{"apps":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"country":{"type":"string"}},"required":["apps"],"additionalProperties":true},"GetStoryArgs":{"type":"object","properties":{"story":{"anyOf":[{"type":"string"},{"type":"number"}]},"platform":{"$ref":"#/components/schemas/AppStoreDevice"},"country":{"type":"string"}},"required":["story"],"additionalProperties":true},"ListAppEventsArgs":{"type":"object","properties":{"app":{"anyOf":[{"type":"string"},{"type":"number"}]},"country":{"type":"string"}},"required":["app"],"additionalProperties":true},"ListArcadeGamesArgs":{"type":"object","properties":{"device":{"$ref":"#/components/schemas/AppStoreDevice"},"country":{"type":"string"}},"additionalProperties":true},"ListCollectionsArgs":{"type":"object","properties":{"tab":{"$ref":"#/components/schemas/AppStoreCollectionTab"},"device":{"$ref":"#/components/schemas/AppStoreCollectionDevice"},"country":{"type":"string"}},"required":["tab"],"additionalProperties":true},"ListDeveloperAppsArgs":{"type":"object","properties":{"developer":{"anyOf":[{"type":"string"},{"type":"number"}]},"app":{"anyOf":[{"type":"string"},{"type":"number"}]},"country":{"type":"string"},"limit":{"type":"number"}},"additionalProperties":true},"ListPurchasedAppsArgs":{"type":"object","properties":{"batchId":{"type":"string"}},"additionalProperties":true},"ListReviewsArgs":{"type":"object","properties":{"app":{"anyOf":[{"type":"string"},{"type":"number"}]},"limit":{"type":"number"},"page":{"type":"number"},"sortBy":{"$ref":"#/components/schemas/AppStoreReviewSort"},"country":{"type":"string"}},"required":["app"],"additionalProperties":true},"ListSimilarAppsArgs":{"type":"object","properties":{"app":{"anyOf":[{"type":"string"},{"type":"number"}]},"country":{"type":"string"}},"required":["app"],"additionalProperties":true},"ListTodayStoriesArgs":{"type":"object","properties":{"device":{"$ref":"#/components/schemas/AppStoreDevice"},"country":{"type":"string"}},"additionalProperties":true},"ListTopChartsArgs":{"type":"object","properties":{"device":{"$ref":"#/components/schemas/AppStoreChartDevice"},"chart":{"$ref":"#/components/schemas/AppStoreChartKind"},"genreId":{"anyOf":[{"type":"string"},{"type":"number"}]},"country":{"type":"string"},"limit":{"type":"number"}},"additionalProperties":true},"ListVersionHistoryArgs":{"type":"object","properties":{"app":{"anyOf":[{"type":"string"},{"type":"number"}]},"country":{"type":"string"}},"required":["app"],"additionalProperties":true},"SearchAppsArgs":{"type":"object","properties":{"term":{"type":"string"},"platform":{"$ref":"#/components/schemas/AppStorePlatform"},"genreId":{"anyOf":[{"type":"string"},{"type":"number"}]},"country":{"type":"string"},"limit":{"type":"number"}},"required":["term"],"additionalProperties":true}}}}