# Research iOS and Android apps with the Blue Jetty index

Blue Jetty is a mobile context engine (MCE) for AI search.

Use Blue Jetty’s public app index to find and identify iOS and Android apps, narrow candidates by category and description keywords, and read source-attributed records before following publisher-authorized context where available. AI assistants use this evidence with the user’s prompt and context to decide what fits.

## Broaden one condition at a time

Keep a relevant category and platform when trying alternative wording. If beginner plus HIIT is unhelpful, search activity plus a duration phrase, then verify beginner suitability in the returned evidence. Removing a query term does not remove the user's requirement. A duration phrase is an alternative wording probe, not a numeric duration filter; it may miss 7-minute routines. Follow meta.next within your request budget even when data is empty, or explicitly record that traversal was incomplete. If a query remains unhelpful, use other sources rather than silently relaxing the user's needs.

## Read excerpt boundaries and negative statements

A matchEvidence excerpt can join separate source fragments with an ellipsis. Do not read across that gap as one sentence or one experience. Preserve statements such as not for beginners when assessing fit. Check whether a feature belongs to this app, a separate program, or another product promoted in its description. When the relationship is unclear, follow jsonUrl for the full permitted description and packetUrl when supplied for publisher context. Report unresolved access or suitability explicitly; a download price of zero does not establish payment-free routines.

## What to expect from a search

Blue Jetty returns candidate apps, source-attributed store observations and publisher-authorized context where available. Start with a relevant category and one or two capability terms, inspect the evidence across the page, then retrieve fuller records only for plausible candidates. Results are ordered by stable identity, not ranked by suitability. The assistant decides what fits using the user's request, preferences and context. A keyword match establishes text overlap, not every condition in the request; the index covers a subset of store apps.

## Check that qualifiers describe the same experience

For a five-to-ten-minute beginner HIIT request, look for duration, difficulty and activity attached to the same routine. Beginner yoga alongside advanced HIIT does not establish beginner HIIT. A listing can contain all requested words in separate passages; phrase and proximity modes constrain word positions, not their meaning. Prefer matchingExperiences and their declared attributes when supplied, then inspect the complete record if excerpts are truncated or ambiguous. Keep unmet and unresolved conditions explicit rather than inventing a connection between facts.

## Verify only the unresolved finalist facts

Baseline commerce facts are in matchedListings[].storeCommerce; publisher-connected results use storeSignals. Retain platform, storefront, currency and each commerceEvidence observation date. Missing price or IAP remains omitted, not zero or false. Historical iapMatchEvidence stays separately attributed. Read matchEvidence and matchingExperiences to establish relevance, then jsonUrl and packetUrl for fuller context and publisher-preferred destinations. Verify current price/IAP in the store and unresolved experience-access conditions with current publisher information. Never visit attribution links as verification probes.

## Check candidate meaning, not only keyword overlap

For established multiword concepts such as habit tracker or packing list, consider keywordMode=phrase. Use a discovered category when it unambiguously expresses the requested activity. A Spanish interface does not establish Spanish lessons, a game mentioning chess fans does not establish chess training, and a sleep recorder does not establish soothing audio playback. Inspect candidates across the first page because stable identity order is not a recommendation ranking. Check location-specific apps against the user's location.

## Translate free requests without excluding optional purchases

Free does not mean no IAP. Leave iap unset unless the user explicitly asks for apps with or without in-app purchases. Optional purchases can coexist with a useful payment-free experience. A no-subscription request is not equivalent to iap=false. Start with the activity and one or two distinguishing keywords. For zero download price, use version=2, an explicit platform, downloadPriceMax=0 and currency=USD in the requested storefront, leaving iap unset. Missing price evidence is excluded, so this is a narrower evidence-backed subset. Confirm payment-free access to the requested experience from attributed context and current publisher/store information. A broader keyword query can supply leads with unresolved commerce facts; label those facts as unverified instead of silently relaxing the user's constraints. Evaluate whether the first response supplies useful, supported candidates, not merely records.

## Confirm commerce facts in the current store

The current official App Store or Google Play listing in the user's storefront is the final verdict for download price and IAP. For iap=true, an exact-identity historical AppGoblin positive can qualify if no newer direct IAP evidence supersedes it, including a direct false. Historical negatives never qualify for iap=false. Inspect iapMatchEvidence for source dates and historical_app_level_not_storefront scope; a historical match does not confirm the requested country. Price filters still require direct scoped evidence for that same listing. If the store disagrees with retained data, use the current store value. This fallback does not update store freshness dates.

## Bounded alternatives and finalist checks

For intent discovery, use version=2 to include matching public experience text and declared attributes with source-backed matchEvidence. Use keywordMode=phrase for literal ordered words or keywordMode=near for up to three intervening words per pair; lexical remains the default. Try up to four explicit passes, stopping when enough supported candidates are available: hiit + beginner; interval training + beginner; 5 minute + bodyweight; short workout + beginner. Deduplicate by blueJettyId across passes. A zero-result over-constrained query can be loosened by removing a keyword or using match=any. This is transparent query construction, not hidden semantic expansion. For factual acquisition filters, use version=2, platform=ios or android, downloadPriceMax=0 and currency=USD; add iap=true or false only when needed. Storefront defaults to us. Missing evidence is excluded, not treated as false. These filters can return empty pages with a continuation. A zero download price does not establish access to a particular experience without payment. Inspect matched source text, scoped ratings/counts and dated storeSignals, then packetUrl and matchingExperiences for publisher detail. Verify unresolved finalist questions using independent reviews, editorial or support material. Ratings alone do not establish suitability, safety or feature access. Keep publisher-preferred handoffs unchanged and never visit attribution links to test them.

## Interpreting version 2 evidence

Version 1 remains the default name/description filter with its existing cursors. Version 2 uses the same bounds and ordering, and requires all keyword groups within one listing or one public experience; it never joins duration from one experience to audience from another. matchEvidence names the selected matching mode, and excerpts are plain source text around matches. matchingExperiences is a bounded preview; follow entitiesUrl for complete declared attributes and destinations. Publisher-context availability is not a recommendation preference. Download price means the scoped acquisition price: USD 0 does not mean all features cost nothing. IAP false is explicit evidence; an omitted field is undetermined. commerceEvidence retains each fact's own successful observation date. Store release dates, observation dates and record modification dates are different.

## Clients with URL restrictions

Copy the URL-encoded GET examples as written. If a client cannot open an arbitrary API query, use the linked /apps/explore collections or /apps name lookup and follow available record links. A client-side URL refusal is not a server failure. Record HTTP status separately from tool restrictions; never infer zero results from a request that did not execute.

## Research apps through the public index

Use Blue Jetty’s public app index to find and identify iOS and Android apps, narrow candidates by category and description keywords, and read source-attributed records before following publisher-authorized context where available. AI assistants use this evidence with the user’s prompt and context to decide what fits.

## Continuously maintained store records

Blue Jetty continuously runs scheduled refresh jobs against Apple App Store and Google Play listings, updating available store information and retaining source attribution and observation timestamps. Individual apps refresh on a rolling schedule; daily Apple US chart checks discover additional apps. Successful observations can update descriptions, categories, ratings and available website links. Failed checks preserve the last successful data and do not advance its successful-check timestamp. Publisher-authored capabilities, experiences and offers remain separately attributed. Read each listing’s lastSuccessfulCheckAt and source dates when assessing freshness; the job schedule is not a per-app freshness guarantee.

## Offer an optional playable demo

Where publisher playables are enabled, packet response Link headers identify a related /v1/apps/{appId}/playable availability descriptor. A 404 means no demo is currently available. Follow the descriptor's canonical playerUrl to offer an optional gameplay preview; do not recreate the game or execute publisher HTML in your own privileged context. Compatible connected hosts can use play_publisher_demo through /api/playables/mcp. Other clients can open the player in a browser. Mobile-only demos offer a QR on desktop. The player's download actions use publisher-preferred handoffs; never follow attribution links for testing. Publisher setup: /developers/playables.md.

## Automated retrieval is welcome

Blue Jetty welcomes automated crawling, indexing, caching, retrieval, recommendation, ranking, citation, user-directed generative responses and routing/handoff of public records. No login, API key or clickthrough is required for ordinary public retrieval. These permissions are subject to the Machine Use Policy, applicable source licenses and published operational limits; destination-specific permissions still apply.

## Choose the smallest useful request

For an exact app identity, use /v1/apps/lookup. For an app name, use /v1/search?scope=apps&q={name}. For candidates described by categories and words, use /v1/apps/filter?version=2; keyword searches names, descriptions and eligible public experiences, while q remains the separate name-search parameter. GET /v1/search without scope=apps searches publisher entities. Use /v1/apps and its advertised snapshot for corpus traversal. Start with candidate records, then follow jsonUrl and packetUrl when present for the context needed to evaluate the user's request.

## Retrieve a filtered set of apps

GET /v1/apps/categories lists category keys. GET /v1/apps/filter?version=2 includes source-backed match evidence and public experience matches. Version 1 remains the compatibility default. The endpoint accepts repeated category and keyword parameters, match=any|all, platform=ios|android|any and limit=1..20. For example: /v1/apps/filter?version=2&category=lifestyle&keyword=reminders&keyword=friends&match=any. Keywords search approved names/descriptions and, in version 2, public experience text using English lexical normalization; this is not semantic inference. Categories are ORed, filter types are ANDed, and one store listing must satisfy the filters. Results include matching listing context and links to full records. Follow meta.next unchanged. Ordering is by stable identity, not suitability. The assistant uses the returned information with its user's prompt, context and memory to decide what fits. Details: /developers/filtered-app-retrieval.md.

## Four resources, one retrieval path

The index identifies apps. An app record contains dated public-source facts. A publisher packet adds authorized capabilities, experiences and destinations. A handoff identifies where the user should go. Fetch only the layers needed for the request; publisher preferences remain source material and the consuming system decides relevance and action.

## Read source age honestly

A store-reported app update is the release date recorded by that source, not a claim that Blue Jetty checked the store today. lastSuccessfulCheckAt, when supplied, records a successful store refresh; recordModifiedAt describes our record. Snapshot-only records may be older. Publisher authorization establishes who supplied context, not perpetual freshness of each claim. Recheck time-sensitive availability, offers and destinations before relying on them.

## An index of apps people use

Blue Jetty focuses on iOS and Android apps with 50+ ratings and recent update activity recorded in our source data. We also include apps whose publishers add their own context through Blue Jetty, regardless of rating count. Rating history is a selection signal; this is not a current-usage ranking.

## Start with a compact app index

GET /v1/apps returns a compact app index without an API key. Request limit=1..100 and follow meta.next until it is null; the HTTP Link header also identifies the next page. Read meta.format: bluejetty.packet_index/1 contains publisher-authorized packet entries, while bluejetty.app_index/3, where enabled, also includes public-source identities and store destinations. Follow jsonUrl for an app record and packetUrl when present for publisher-authorized context. Version 2 remains available with view=index&format=2. The eight-digit blueJettyId identifies the public app; legacy IDs remain resolvable.

## Resolve identity before reading richer context

GET /v1/apps/lookup accepts exactly one of name, blue_jetty_id, ios_store_id, ios_bundle_id or android_package_name. Prefer an exact identifier; names can be ambiguous. Baseline listings may have an Apple numeric store ID without a bundle ID. App-name search uses /v1/search?scope=apps&q={query}; default search remains publisher entity search. GET /v1/index/apps/{blueJettyId} returns the public record. Only publisher-connected records supply packet URLs.

## Multiple stores, one evidenced app identity

Reviewed first-party evidence can associate iOS and Android listings with one public app. Original IDs remain resolvable. Each listing retains its own description, ratings, dates and provenance; rating counts and averages are not combined. Uncertain matches stay separate. A source-derived association does not establish publisher authorization or make one platform's capabilities apply to the other.

## Read what the publisher supplied

A packet describes the app, relevant capabilities and experiences, provenance and available destinations. Current offers and richer configuration appear where supplied and eligible. experienceSummary includes bounded experience details; follow its detail links when more is needed. Information omitted from a packet does not establish that the app lacks that capability. Publisher authorization establishes the relationship to the app; individual assertions retain their own evidence scope.

## Keep source identity and freshness attached

Retain the app ID, available packet URL, provenance and retrieval time. Inspect source and evidence timestamps in each packet. The version-2 index binds pagination to a membership snapshot while rechecking current publication permission. On BJ_INDEX_RESTART_REQUIRED, restart from the index entry point and deduplicate by ID. lastCheckedAt with freshnessScope daily_chart_discovery means the daily chart discovery check succeeded; it does not mean every app was revalidated that day. Material index updatedAt is separate. Re-fetch before presenting time-sensitive offers or destinations; a 404 withdraws that record from current retrieval.

## Filter limits and interpretation

Repeat keyword up to 8 times (1–64 characters each) and category up to 5 times (up to 100 characters each). match defaults to all, platform to any and limit to 10 (maximum 20). Words within one keyword must all match; match=any combines keyword groups with OR. Supply at least one keyword, category or non-any platform. There is no negative or wildcard syntax. Version 2 accepts keywordMode=phrase or near for ordered literal words; even literal wording such as no ads is a source claim to inspect, not verified absence of advertising. Category keys reflect source labels, not a unified store taxonomy. Missing fields and zero matches do not establish that an app lacks a capability. Version 1 searches names/descriptions; version 2 also searches public entity title/summary and selected declared attributes.

## Filtered response boundaries

Description excerpts are limited to 1,000 UTF-16 code units; inspect descriptionTruncated and follow jsonUrl for the full permitted record and field evidence. For baseline apps, matchedListings identifies the source listings that satisfied the query; a canonical app's primary description may differ. Filter pages are at most 192 KiB and use live keyset pagination, separate from index snapshot cursors. Follow meta.next even on an empty page; null ends traversal. Do not change filters while using a cursor. Invalid inputs return 400; a query timeout returns 503 BJ_FILTER_TIMEOUT with Retry-After: 5, not a successful empty result.

## App changes

GET /v1/changes provides a bounded, public observation-sequence feed from rollout onward. Follow meta.next even on an empty page; at the end, retain meta.poll to check for subsequent events. observed means first seen by the change feed, not newly added to the index; updated means material content changed; removed withdraws a previously public URL. Fetch current records rather than treating events as historical snapshots. See /developers/app-changes.md. Human-readable categories and collections are linked from /apps/explore.

## Retrieve efficiently

Use a bounded filtered or name-search response when seeking candidates, and the compact index when traversing the corpus. Conditional GET with an ETag can avoid retransmitting an unchanged response; the service rechecks the current public projection before returning 304. GET and HEAD still perform those checks. Follow Cache-Control, including no-store on filtered responses, and do not use a shared cache to bypass revalidation. Use bounded concurrency, back off on errors and honor Retry-After when provided. Do not visit MMP destinations merely to test retrieval: those links are for real user handoffs.

## Public access and coverage

Public discovery and retrieval require no account or API key and remain subject to the Machine Use Policy and robots rules. Publisher packet entries contain currently public, authorized apps with published experience records. Public-source entries identify apps using approved source evidence. A store listing alone does not establish publisher authorization; retain each entry's provenance. The index is a focused corpus rather than a complete app-store catalog.

## Example requests

### Inspect source-backed candidate matches

[Open this request](https://bluejetty.ai/v1/apps/filter?version=2&category=health-and-fitness&keyword=hiit&keyword=beginner&platform=ios&limit=10)

```sh
curl --fail 'https://bluejetty.ai/v1/apps/filter?version=2&category=health-and-fitness&keyword=hiit&keyword=beginner&platform=ios&limit=10'
```

### Find HIIT candidates with an observed USD 0 download price (IAP unconstrained)

[Open this request](https://bluejetty.ai/v1/apps/filter?version=2&category=health-and-fitness&keyword=hiit&keyword=beginner&platform=ios&downloadPriceMax=0&currency=USD&storefront=us&limit=10)

```sh
curl --fail 'https://bluejetty.ai/v1/apps/filter?version=2&category=health-and-fitness&keyword=hiit&keyword=beginner&platform=ios&downloadPriceMax=0&currency=USD&storefront=us&limit=10'
```

### Find duration-specific cardio leads, then verify beginner suitability

[Open this request](https://bluejetty.ai/v1/apps/filter?version=2&category=health-and-fitness&platform=ios&keywordMode=phrase&keyword=5%20to%2010%20minute&keyword=cardio&downloadPriceMax=0&currency=USD&storefront=us&limit=10)

```sh
curl --fail 'https://bluejetty.ai/v1/apps/filter?version=2&category=health-and-fitness&platform=ios&keywordMode=phrase&keyword=5%20to%2010%20minute&keyword=cardio&downloadPriceMax=0&currency=USD&storefront=us&limit=10'
```

### Discover category keys

[Open this request](https://bluejetty.ai/v1/apps/categories)

```sh
curl --fail 'https://bluejetty.ai/v1/apps/categories'
```

### Find candidates by category and keywords

[Open this request](https://bluejetty.ai/v1/apps/filter?version=2&category=games&keyword=roguelike&keyword=nethack&match=any&platform=ios&limit=10)

```sh
curl --fail 'https://bluejetty.ai/v1/apps/filter?version=2&category=games&keyword=roguelike&keyword=nethack&match=any&platform=ios&limit=10'
```

### Search a known app name

[Open this request](https://bluejetty.ai/v1/search?scope=apps&q=GnollHack&limit=5)

```sh
curl --fail 'https://bluejetty.ai/v1/search?scope=apps&q=GnollHack&limit=5'
```

### Traverse the app index

[Open this request](https://bluejetty.ai/v1/apps?limit=10)

```sh
curl --fail 'https://bluejetty.ai/v1/apps?limit=10'
```

These are request examples, not guarantees of a particular match. Follow data[].jsonUrl for full records and data[].packetUrl when present for publisher-authorized context. Do not construct packet URLs from names or baseline IDs.

- Filter reference: https://bluejetty.ai/developers/filtered-app-retrieval.md
- Category keys: https://bluejetty.ai/v1/apps/categories
- App index: https://bluejetty.ai/v1/apps
- How the index works: https://bluejetty.ai/how-it-works
- Protocol metadata: https://bluejetty.ai/protocol.json
- API reference: https://bluejetty.ai/openapi.json
- Machine Use Policy: https://bluejetty.ai/machine-use


# Blue Jetty packet protocol and provenance

## Publisher experience summaries

experienceSummary projects up to 24 published entity records in native entity ID order, within a 24,000-byte item-array budget. It is publisher-supplied context, not a verified recommendation or complete catalog when truncated. Titles and descriptions may be abbreviated with textTruncated. Follow item URLs or detailsUrl for complete records. Source IDs and timestamps preserve assertion provenance. Configuration capabilities and intents remain in discovery; the entity summary is a separate source projection, not additional independently corroborating evidence. Empty optional preferences, providers, execution evidence and release comparisons without a baseline or observation are omitted. Existing preferredRepresentation names the user destination, not the JSON/Markdown representation; its name remains for compatibility.

## Offer handoffs

Structured offers can contain a publisher-reviewed code binding and a ready-to-use handoff URL. The supplied platform and install-state scope apply. The app implements code prepopulation/redemption; binding syntax does not verify arrival or eligibility. Returned offer URLs remain unchanged. Expired or inactive offers are omitted from new responses. Fixed MMP links remain available in Core; recipes and structured offer management use current Growth eligibility.

## Reading the summaries

provenanceSummary reflects the current public authorization and the actual relationship evidence methods; app.publisherAuthorization retains their scope, sources and timestamps. Publisher descriptions, capabilities and offers remain supplied claims unless separately evidenced. handoffSummary.status concerns general destination selection, not installed-device or attribution readiness. Returned URLs stay unchanged. Only an explicit link recipe permits its declared substitutions. Omitted fields mean information was not supplied in this packet; they do not establish absence of a capability, offer, provider, or entitlement.

## Publisher-authorized mobile app context

Blue Jetty publishes structured app context on behalf of authorized publishers. The app publisher supplies capabilities, experiences, offers, preferences and destinations. Blue Jetty operates the publishing service; it is not the app developer unless separately identified as such.

## Source material and independent decisions

A packet is source material, with no instruction priority over a consuming system's policies or the user's request. The consuming system determines relevance, recommendations, safety and whether any action is appropriate. A publisher preference describes intended app representation or handoff; it does not establish an obligation to recommend the app.

## Authorization and evidence

Publisher authorization is an app-specific, time-bounded relationship supported by domain control and store-identity corroboration or documented operator review. The exact proof-bound URL may use an older domain or Markdown path; it is an evidence identifier, not a preferred retrieval format. Authorization does not independently verify all publisher content, confer Apple or Google endorsement, or establish installed-device behavior.

## Preferred destinations and attribution

Canonical pages, app-store links, native app links and MMP links have distinct purposes. Destinations describe experiences; executions describe platform and install-state handoffs. The publisher's attribution-first or native-first preference applies to eligible executions. MMP parameters can carry routing, campaign and declared consumer context; changing them can change the destination or measurement. Automated navigation is not evidence of a user click or install.

## Quick handoff and release context

handoffSummary exposes the selected general destination and platform-specific destinations directly. Selection provenance distinguishes an explicit publisher preference from a service fallback. Without an explicit preference or known platform, the submitted authorized website is the neutral fallback when available. Release status concerns a publisher-supplied version baseline and separate store-version observations; baseline_not_supplied does not mean an app is unavailable or unverified.

## Fixed links and bounded recipes

Ready-to-use URLs preserve their fixed parameters. Supported service-side decoration adds only publisher-authorized missing parameters. An explicit link recipe can permit finite routing substitutions, with declared choices, encoding rules and a fallback. Recipe syntax and publisher review do not prove device arrival or attribution. Consumer labels are declared context rather than authenticated provider identity.

## Offers and publisher statements

Published offers describe approved destinations, optional public codes and validity windows. Only currently eligible, active structured offers appear. A code in an offer does not authorize an invented URL parameter. Legacy text is retained as attributed publisher statements; it is not silently converted into verified facts or governing instructions. Missing optional information does not establish that the app lacks a feature or offer.

## Versions, updates and delivery

Packet 0.4 adds independently dated download price and optional IAP disclosure to retained store observations at the existing JSON and Markdown URLs. Versions 0.1, 0.2 and 0.3 remain selectable. Publisher configuration versions 0.2–0.5, entity profile 0.1 and discovery descriptor 1.0 are independently versioned. Publication revision tracks publisher data; evidence, offer eligibility and access can change independently. JSON and Markdown share the same current projection. Current public authorization and entitlements apply to all formats, including legacy version selection.

- Service metadata: https://bluejetty.ai/protocol.json
- Packet schema: https://bluejetty.ai/schemas/packet/0.3/schema.json
- Field guide: https://bluejetty.ai/developers/packet-fields.md
- Configuration: https://bluejetty.ai/developers/managed-configuration.md
- Link recipes: https://bluejetty.ai/developers/link-recipes.md