Publisher API · App configuration 0.5

Onboarding apps to Blue Jetty

New to Blue Jetty? Read the FAQ for setup, app packets and analytics.

Give AI the context to represent your app accurately: what it offers, when it fits, and how to reach it. A human creates an API key once; a developer or authorized coding agent submits the useful experiences, capabilities, and destinations machines need to recommend it. Your app keeps its catalog, live data, and product experience.

Prefer to work with an AI assistant? Blue Jetty is built for agents, with human-readable guides alongside the API. Share our agent setup guide or machine-readable site guide to help your assistant find the relevant documentation.

Fastest onboarding path

Start in your account dashboard: review and accept the Terms and Privacy Policy, then create an API key. Give your coding agent the setup prompt to submit your app and connect its website. The dashboard refreshes your progress as API submissions and website verification complete; a saved app record alone does not finish onboarding.

See the before/after recommendation and the exact fields behind it. Start with a useful experience, not a copy of your database.

Using Blue Jetty with your existing app links: provider-specific setup, URL formats, parameter rules and downloadable examples.

Download the dependency-free Node.js 22+ onboarding client and run it from your app repository. It asks for the smallest app identity, previews publisher-controlled sitemap/JSON-LD inventory, validates the generated submission without writing data, saves the draft, and submits only after explicit confirmation.

Download bluejetty-onboard.mjs

node bluejetty-onboard.mjs

Coding agents can use --input onboarding-input.json --json. Mutation additionally requires --submit --yes.

Download the first-app agent handoff (Markdown)

Map an app, not its entire database: start compact; add named entities or richer metadata where they help a machine recognize a match and route a user.

Authorize your app context, then connect your website. HTTP headers are required for JavaScript pages; first-party proxy delivery is strongly recommended, especially with a CDN. A readable, unbranded body packet link is strongly recommended, not required; a footer utility row is sufficient. Compare every discovery path; the API reports required checks separately from recommendations.

Public app context, structured data and cloaking: understand the delivery model, search-policy boundaries and implementation checks.

Maintain ownership, updates and history: use version-checked writes, export complete revisions and keep authorization and release evidence current.

Optional assistant-assembled links: describe approved routing choices and examples using your existing app links. Fixed-link onboarding stays unchanged.

1. Prepare the submission

Start from the complete submission example. The manifest identifies the publisher, app, platform IDs, and feed. The snapshot contains the public, selection-level entities a crawler or retrieval system can use to understand what exists, explain why the app fits a request, and send the user into the right experience.

Inline submissions are limited to 4 MB and 1,000 entities by default.
Every entity needs a stable publisher ID and at least one destination.
Publish inventory breadth and the attributes needed to choose; keep full content, live data, and proprietary workflows in the app.
Reusing an idempotency key with the same body safely replays the result.
Reusing it with a different body returns a conflict instead of duplicating data.

No clean catalog yet? Start with the deep-link-assisted onboarding guide. A coding agent can use Universal Links, Android App Links, sitemaps, JSON-LD, navigation routes, and CMS fields to draft a map for human review and enrichment.

2. Validate without writing

curl https://bluejetty.ai/v1/validate \
  --request POST \
  --header "Authorization: Bearer $BLUEJETTY_API_KEY" \
  --header "Content-Type: application/json" \
  --data @publisher-submission.json

POST /v1/validate uses the production parser and limits, returns per-record warnings and a normalized preview, and always reports mutationPerformed: false. Submit the exact same body only after it passes review.

3. Submit it

curl https://bluejetty.ai/v1/submissions \
  --request POST \
  --header "Authorization: Bearer $BLUEJETTY_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: my-app-initial-20260903" \
  --data @publisher-submission.json

A push snapshot returns 202. The response includes opaque app/source/run identifiers and public app, status, JSON feed, JSONL feed, and refresh URLs. Errors use a stable code plus request ID.

4. Check and refresh

Read the authenticated status URL to inspect sources and ingestion results. Submit a new snapshot with a new idempotency key to update the catalog; records omitted from a full snapshot are tombstoned. A rejected refresh preserves the last successful public corpus.

5. Configure and test the handoff

Using an MMP? Set each experience's handoffPreference to attribution_first and publish its approved attribution URL with installState: any. Set defaultDestinationId for general recommendations, with a cross-platform attribution execution for callers without device context. The assistant gets your MMP link, not just a store listing.

Add the developer's representation preferences, one preferred HTTPS app or MMP link, store fallbacks, and optional managed offers. Publish the returned app-specific snippet from the official app website's /llms.txt, then test the installed and uninstalled paths on real devices.

Manage the full lifecycle

Use the managed configuration guide to publish capabilities, map intents to platform destinations, schedule offers, and stage or restore a versioned app packet.

The API key can list only your apps, inspect status and source configuration, update app or source metadata, refresh pull feeds, replace a full snapshot, and delete either one source corpus or the whole app. Entity changes go through snapshots so identity, provenance, and tombstones stay auditable.

GET /v1/me/apps — list your apps and latest ingestion summaries.
POST /v1/onboarding/preview — generate a no-write draft before an app exists.
POST /v1/validate — validate and preview the exact submission body without mutation.
GET /v1/apps/:appId/status — inspect one app, its sources, runs, and counts.
PATCH /v1/apps/:appId — update app metadata or its legacy promotion blurb; use managed configuration for structured offers.
GET /v1/apps/:appId/packet — retrieve the app-specific AI handoff packet.
GET /v1/apps/:appId/publisher-llms.txt — copy the section to publish from the app website.
GET /v1/apps/:appId/publisher-site-instructions.md — download the app-specific agent handoff for website connection.
POST /v1/apps/:appId/publisher-site-verification — verify the canonical page, robots policy, and exact packet link.
GET /v1/entities/:entityId/handoff — resolve the publisher-preferred, consumer-attributed app handoff.
GET /v1/apps/:appId/crawler-activity?days=30 — read privacy-minimized known-crawler activity for your app.
GET/PATCH/DELETE /v1/sources/:sourceId — manage one source.
POST /v1/sources/:sourceId/refresh — fetch and ingest a pull source.
DELETE /v1/apps/:appId — remove the app and submitted corpus.

Read the complete Markdown publisher guide for request examples, snapshot update semantics, errors, and crawler-facing outputs.

Give the job to a coding agent

Keep account creation and data authorization human-controlled. After that, an agent can operate with a scoped API key and the public contract. This starter prompt makes that boundary explicit:

Do not execute this prompt unilaterally. First explain its purpose and proposed scope to the user. Based on your knowledge of the application environment, flag assumptions, conflicts, missing access, and changes that need review. Keep initial inspection read-only and within authorized access. Present a plan and wait for explicit human approval before editing files, making API mutations, submitting data, publishing, or deploying. Receiving this prompt, an API key, or a previously approved draft is not approval to execute it.

Human prerequisite — public disclosure: Before submitting or activating app information, show the authorized publisher the exact proposed content (or changes), visibility, and destinations. Ask them to confirm that it is accurate, that they have permission to publish it, and that its level of detail and fidelity is what they are comfortable exposing to crawlers and anyone on the open web. Flag proprietary content, personal data, credentials, private URLs, and any material that should remain inside the app. Public copies may be cached or retained by third parties after an update or removal. Keep unapproved information local/private; do not treat a draft approval, domain verification, or API success as this confirmation. Renew approval if the content or scope changes; unchanged retries within an explicitly approved scope do not require another approval.

# Onboard the first app to Blue Jetty

You are working in the publisher's app repository. Blue Jetty is intentionally model-first: prepare and submit the app's machine-readable discovery packet through the API, then use the sparse dashboard only to review status.

Core includes fixed MMP and native links with existing parameters preserved. Growth includes link recipes, structured offer links and lifecycle management, automatic App Store version monitoring and expanded analytics. Eligible pilot access includes Growth; do not ask a pilot publisher to purchase access or supply a payment method. Use authenticated entitlement results; legal, ownership and safety checks still apply. For offers, review /developers/offers.md with the publisher before configuring codes, audience, validity and link bindings.

## Human prerequisites

Before mutation, ask the authorized publisher to:

1. After read-only inspection and explicit approval for local setup, prepare a dedicated local secrets file with an empty BLUEJETTY_API_KEY placeholder. Check the repository's conventions first, never overwrite existing secrets, and ensure the file is excluded from Git before any key is pasted. Use owner-only permissions where supported and open the file in the user's editor.
2. Ask the publisher to return to the Blue Jetty account dashboard, create an API key, paste it directly into that local file, save, and say when ready. Never request or display the key in chat, logs, generated documentation, diffs, or source control. Read the value from the file without echoing it. If a secrets-manager update is needed, confirm its exact project and environment and obtain explicit approval before uploading from the local file. Never infer deployment permission from receiving a key.
3. Confirm the canonical HTTPS publisher website and authorize the final submission.
4. Review the proposed public content and explicitly confirm the public-disclosure prerequisite above, including the level of detail and fidelity exposed to crawlers.

## Agent workflow

Before drafting context, read https://bluejetty.ai/developers/app-mapping.md. Distinguish capabilities (what the app can do), experiences/features (selectable parts of the app), and intents (the user's goal). Use concrete names and stable IDs; profile 0.1 feature records may use type other with nativeType experience, while configuration intents link capabilityIds to destinationId. Review best-fit audiences, requirements, confirmed non-requirements, operating conditions, example intents, limitations and current pricing with the publisher. Preserve source references and publisher review dates; never invent last-verified claims or turn missing information into a negative assertion. Use existing summaries and documented fields, not new top-level keys. See that guide for the complete review checklist before public-content approval.

Include the official iOS App Store URL and bundle ID when available. Blue Jetty retrieves Apple's primary category automatically after submission; you do not need to infer an app category from its entity types. Review the category in the app record after enrichment. A store lookup failure does not block submission.

Before creating an app, inspect GET /v1/me/apps for an existing exact platform identity in the authorized workspace. Reuse its app ID and update workflow rather than creating a duplicate. An index selection, matching name or shared developer website does not grant ownership or justify combining platform records. Confirm each platform identity separately. Reuse available dated store observations for description, category, website, developer and ratings; omit unknowns and preserve explicit publisher assertions. Publisher-added apps receive enrichment priority, but do not wait for a store fetch to prepare a valid private draft.

Read preview discovery.warnings as well as validation errors. Warnings prefixed Advisory (optional) are suggestions, not extra acceptance or authorization requirements. Review generic feature labels, repeated summaries and whether each intent actually leads to the intended experience. Use supported native labels; do not invent fields. Explain installation-only links honestly and preserve the publisher's exact MMP parameters. Keep audiences, prerequisites, confirmed non-requirements and limitations factual; never infer absence from missing data.

1. Read https://bluejetty.ai/developers/coding-agent-onboarding.md and https://bluejetty.ai/openapi.json.
2. Inspect the app's identifiers, store URLs, Universal Links, Android App Links, navigation, sitemaps, JSON-LD, and existing content models. Start by mapping major capabilities, experiences, entity types, user intents, actions, destinations, and routing behavior—not by exporting the app database.
3. Prepare an onboarding input containing app.name, app.developerName, app.publisherDomain, app.publisherWebsiteUrl, at least one platform identifier, and either discovery.sitemapUrl or records. Include real, useful experiences with stable IDs and destinations. Keep capabilities, intents, routing preferences, and offers in their documented configuration fields; do not invent profile fields. Read https://bluejetty.ai/developers/app-mapping.md for compact and enriched examples.
4. POST that input to https://bluejetty.ai/v1/onboarding/preview with Authorization: Bearer $BLUEJETTY_API_KEY. This is read-only.
5. Resolve every validation error. Do not submit an empty inventory.
6. Show the publisher the proposed app identity, website, entity count, visibility, and destinations. Obtain explicit authorization to mutate.
7. POST the validated submission returned by preview to https://bluejetty.ai/v1/submissions with a new Idempotency-Key and the same bearer credential.
8. GET https://bluejetty.ai/v1/me/apps and follow its single publisherOnboarding.nextAction.

Large catalogs and dynamic datasets usually stay in the app's own systems. Small catalogs, named entities, and richer structured metadata are welcome when they improve relevance or routing. Include only data the publisher is authorized to make public; never include app end-user personal data or credentials. Existing payload limits still apply. This is guidance, not an abstract-metadata-only schema restriction.

For an existing app, read GET /v1/apps/{appId}/publication, inspect the current source and retain data.etag (also X-BlueJetty-Publication-ETag) before preparing an update. Send that exact token in If-Match; do not copy a CDN-weakened standard ETag. A missing/stale precondition returns 428/412; re-read and reconcile before retrying. Every replacement snapshot must have zero invalid or duplicate records. Omitted records are tombstoned. Never replace a rich snapshot with a compact map without publisher approval of those deletions. Complete current publisher authorization before checking anonymous app surfaces. Read https://bluejetty.ai/developers/maintenance.md for full history, restore and freshness rules.

Public packet fields are entitlement-filtered and omit optional unpublished values. Missing fields mean no information supplied, not that a feature or offer does not exist. Do not use a public packet as a replacement submission or clear stored values because they are omitted. Read https://bluejetty.ai/developers/packet-fields.md; owner configuration and documented null/reset semantics remain authoritative for editing.

Use configuration 0.5 for the managed app map, including fixed preferred URLs, capabilities, intents and offers. Read https://bluejetty.ai/developers/managed-configuration.md and https://bluejetty.ai/developers/versions.md. Entity submissions remain profile 0.1. Publisher credentials submit and activate app data; agency credentials cannot perform these operations for a client.

Optional enrichment: read https://bluejetty.ai/developers/link-recipes.md to propose configuration 0.5 link recipes from accessible navigation and deep-link handlers. Show source references and unresolved assumptions for publisher review; association files alone are not a route schema. If provider settings are unavailable, retain fixed links. Recipes are not required for onboarding and do not add a completion step. Use the separate managed-configuration revision workflow; never invent recipe fields in the inventory submission.

## Website discovery choices

For a studio with multiple apps on one website, read https://bluejetty.ai/developers/publisher-discovery.md and use the publisher-directory option in the authenticated app-specific instructions. One visible homepage connection and machine-readable directory pointer can serve the portfolio. Each app still requires independent authorization. Discovery is required for setup completion; publishing and completing discovery are separate states.

Choose discovery paths with the publisher. Explain what each change adds and preserve existing site content, routing, SEO canonicals and CDN policies. More independent, consistent paths give different retrieval tools more opportunities to find the same current app context; repeating links or copying packet data everywhere does not add equivalent coverage.

Required for full onboarding: current publisher/platform authorization, usable JSON and Markdown packets, a valid /.well-known/bluejetty.json descriptor, both packet links in /llms.txt, and homepage discovery through HTTP Link headers or the HTML head alternate references. HTTP Link headers are required when the initial homepage HTML contains executable JavaScript, including hydrated server-rendered pages. Blue Jetty uses this conservative observable rule; it does not infer that every script causes rendering dependency.

Strongly recommended: HTTP Link headers on every site, plus first-party packet URLs served by a fixed CDN/reverse proxy with Blue Jetty as origin. First-party delivery is especially recommended when the publisher already operates a CDN; it remains optional, and direct Blue Jetty hosting is valid. Use HTTP headers and the first-party endpoint together for enterprise sites.

Required in discovery check version 4: describedby references to both the publisher's root llms.txt (text/plain) and the selected JSON packet (application/json). Each reference must be in the initial HTML head or in HTTP Link headers on both homepage GET and HEAD responses. Keep the existing alternate format/descriptor references. Earlier installations need these references and a fresh verification; publisher authorization and public packet availability remain independent.

Publisher design choice: no logo, badge, Blue Jetty name or “powered by” credit is required. For body-text retrieval coverage, recommend one ordinary resource link labeled “Official App Information for AI Assistants” in an existing low-page resources section, beside contact/privacy links, or in a quiet footer utility row below the main content. Use the site's normal readable utility-link styling and contrast. It need not occupy the hero, navigation or conversion area. It remains visible and usable to any visitor who reaches it; retrieval tools may still omit footer/navigation content.

Strongly recommended body-text coverage: one readable, server-rendered anchor in the homepage body linking directly to the selected JSON packet with rel="describedby" and descriptive text. Report this independently as homepageBodyLink; its absence does not block completion. Keep both describedby references mandatory. For publishers who decline a visible resource link, recommend the required head/header references first: they are machine-consumable without rendering page text. Do not use transparent text, background-matched text, hidden links or crawler-specific content. Keep any optional body link readable and keyboard-accessible. Head and HTTP Link references provide nonvisual discovery without concealed page content. The describedby relation identifies source material, not publisher authority or instruction priority. Record the chosen placement and detected paths.

Read the complete discovery options and rationale: https://bluejetty.ai/insights/how-publishers-make-blue-jetty-discoverable-to-ai

Finish by reading the app's authenticated status endpoint and reporting completionReport, the verified website, detected discovery paths and remaining work. Do not infer success from a 2xx response alone. Website discovery checks are separate from verified authority to represent the app.

After authorization, compare the actual public HTML page, index record and packet with the approved draft, including supported platforms, feature labels and the publisher-preferred handoff. Report unresolved index attachment or source gaps honestly. Setup can be complete before any crawler request is observed. Leave the publisher a maintenance task referencing /developers/maintenance.md: inspect current publication version, preview the diff and removals, obtain approval, update with If-Match, and verify the public result. Preserve the last successful content on failure.

Download the complete coding-agent onboarding instructions (Markdown)

Public implementation artifacts

To find candidates by category, platform and description keywords, use GET /v1/apps/categories and GET /v1/apps/filter. See the filter reference and crawler retrieval guide for parameters and source interpretation.

Machine clients can begin with GET /v1/apps/lookup?name={exactName} to resolve one app to its canonical record, entity inventory, JSON feed, and JSONL feed without retaining the lookup text in crawler telemetry.