API v1 · App configuration 0.5

Configuration 0.5 link recipes optionally describe assistant-side assembly. The handoff API returns the recipe and a fixed URL; it does not accept user routing selections.

Using Blue Jetty with native links and MMP links: provider-specific guides, Markdown and complete JSON examples. Packets and owner configuration expose revision-bound execution evidence separately from publisher claims.

Every supported endpoint.

Crawler retrieval guide · Filter semantics, examples, limits and pagination. Public retrieval is anonymous. Filtering supplies candidates in stable identity order; the consuming assistant evaluates suitability.

Ownership, updates and history: existing-app publisher writes require the current publication ETag from data.etag or X-BlueJetty-Publication-ETag in If-Match. Missing or stale preconditions return 428 or 412. Anonymous publisher records require current authorization; drafts stay owner-readable.

This page is the human index. The OpenAPI 3.1 document is the complete machine contract, including authentication, parameters, schemas, response media types, limits, and errors.

Request limits and key lifetime

New publisher API keys expire after 90 days by default. Key creation accepts expiresInDays from 1–365; each user may have up to 20 active publisher keys. Existing keys retain their configured expiry.

Destination verification checks up to 25 destinations per call and returns remaining when more work is available. Discovery and verification share per-app and workspace work limits. Wait for an active check after a 409 response; honor Retry-After on 429 responses. Search accepts queries up to 500 characters and limits from 1–50.

Recommended publisher workflow

POST/v1/onboarding/previewGenerate a complete no-write draft before an app record exists.
POST/v1/validateValidate and normalized-preview the exact submission body without mutation.
POST/v1/submissionsRegister or update a manifest and optionally ingest a full snapshot.
POST/v1/appsCreate an app through the lower-level legacy workflow.
GET/v1/me/appsList owned apps, onboarding state, updates, and 30-day known-crawler summaries.
GET/v1/apps/{appId}/statusInspect owned app sources, runs, counts, onboarding criteria, and last success.
GET/v1/apps/{appId}/publicationRead the owner preview, publication ETag, current authority and 20 revision summaries.
GET/v1/apps/{appId}/publication/revisions/{revisionId}Read full publisher assertions and diff; add ?export=jsonl for source-record export.
POST/v1/apps/{appId}/publication/revisions/{revisionId}/restoreRestore retained app assertions and source contents as a new revision; requires If-Match.
PATCH/v1/apps/{appId}Update app metadata or set/remove its legacy promotion blurb; use managed configuration for offers.
GET/v1/apps/{appId}/publisher-site-instructions.mdDownload the app-specific coding-agent website handoff.
POST/v1/apps/{appId}/publisher-site-verificationCheck website discovery paths and both packet formats. Reuse Onboarding-Run-Id for one confirmation per onboarding run.
GET/v1/apps/{appId}/crawler-activity?days={1-90}&view={aggregate|detailed|history}Read authorized aggregate, provider detail, or daily history with complete-week trends. Aggregate-only access supports up to 30 days.
GET/v1/apps/{appId}/index-activity?days={1-90}&view={aggregate|detailed|history}Read owned-app HTML/JSON crawls, API record retrievals and Blue Jetty API search appearances separately, with coverage dates. Aggregate-only access supports up to 30 days.
GET/v1/apps/{appId}/configurationExport active managed configuration and recent execution observations.
POST/v1/apps/{appId}/configuration/previewPreview a draft intent handoff without publishing or fetching provider links.
GET / POST/v1/apps/{appId}/revisionsList revision metadata or validate and stage an immutable configuration.
GET / POST/v1/apps/{appId}/revisions/{revisionId}Inspect a revision/diff, activate it, or restore it as a new revision.
POST/v1/apps/{appId}/configuration/monitorObserve one configured execution with a bounded HTTP check.
GET/v1/apps/{appId}/handoff?intent={intentId}&platform={platform}Resolve a user intent to its publisher-approved platform execution.
POST/v1/apps/{appId}/release-statusRecord publisher-supplied production-store version observations.
DELETE/v1/apps/{appId}Delete an owned app and its submitted corpus.

Source and ingestion management

GET/v1/apps/{appId}/sourcesList private sources for an owned app.
POST/v1/apps/{appId}/sourcesCreate a lower-level source; submissions are preferred.
GET/v1/sources/{sourceId}Read one owned source.
PATCH/v1/sources/{sourceId}Update an owned source URL, cadence, mapping, or provenance.
DELETE/v1/sources/{sourceId}Delete one source and its entity corpus.
POST/v1/sources/{sourceId}/refreshFetch and ingest an owned pull source.
POST/v1/apps/{appId}/entities?source_id={sourceId}Submit a lower-level full snapshot.
POST/v1/apps/{appId}/discoverPreview bounded sitemap/JSON-LD discovery.
POST/v1/apps/{appId}/verify-destinationsRun bounded destination verification.

Public discovery

GET/v1/appsList public apps.
GET / HEAD/v1/apps/categoriesDiscover source category keys; follow meta.next.
GET / HEAD/v1/apps/filter?category={key}&keyword={word}&match=all&platform=ios&limit=10Filter public names/descriptions. Repeat keyword up to 8 times and category up to 5; match=all|any, platform=any|ios|android, limit=1..20. Follow the returned cursor URL unchanged.
GET/v1/search?scope=apps&q={name}Search app names; optional view=compact reduces the response. Use /v1/apps/filter for description keywords.
GET/v1/index/apps/{blueJettyId}Read a canonical app record with attributed source context and a publisher packet link when available.
GET/v1/apps/lookup?name={exactName}Resolve one exact app identity to its canonical app, entity, and feed URLs.
GET/v1/apps/{appId}Read public app metadata.
GET/v1/apps/{appId}/packetRead the app-specific preferred-representation and handoff packet as JSON.
GET/v1/apps/{appId}/packet.mdRead the app-specific handoff packet as Markdown.
GET/v1/apps/{appId}/publisher-llms.txtCopy the section publishers can add to their website llms.txt.
GET/v1/apps/{appId}/release-statusCompare indexed app versions with current store observations.
GET/v1/apps/{appId}/entitiesPage through public entities for an app.
GET/v1/entities/{entityId}Read one public entity.
GET/v1/entities/{entityId}/handoffResolve the publisher-preferred destination, deep link, stores, and declared consumer attribution.
GET/v1/apps/{appId}/feed.jsonRead one app JSON feed.
GET/v1/apps/{appId}/feed.jsonlStream one app JSON Lines feed.
GET/v1/search?q={query}Search published selection metadata.
GET/v1/export.jsonlRead the bounded legacy publisher-entity export. Full app-index snapshots are advertised separately in /protocol.json.
GET/v1/directory/appsList eligible unclaimed discovery profiles.
GET/v1/directory/apps/{candidateId}Read one eligible discovery profile.
GET/healthCheck application and database readiness.

Contract boundaries

The OpenAPI contract covers every supported /v1 method and /health. Browser-session account routes, Auth.js callbacks, the signed Resend webhook, and the secret cron route are operational interfaces—not publisher APIs—and are intentionally excluded.

Start with the publisher quickstart, the Markdown lifecycle guide, or the coding-agent runbook. The Swell Atlas case study follows one synthetic catalog through submission, retrieval, routing, and an owner-only sample hold.