Parlane

Make your app Parlane-ready

No SDK is required. Your backend serves a manifest and JSON documents; Parlane renders them natively. The fastest way in is to hand the whole contract to the coding agent you already use. Everything on this page exists so that an agent, pointed here, can finish the job without you copying anything else around.

Existing notification integrations can keep standard previews. Developers preparing the optional encrypted mode can use theprivate-preview integration guide. It also explains the backend deduplication required for reliable retries.

Required migration: data-sharing consent

The next iOS release requires a dataProcessing declaration naming your operator and every processor receiving user content. Existing connections also require explicit acceptance. Implement the Parlane-Data-Policy header check before processing content. Follow the migration guide for REST, MCP, OAuth, server voice and native capture. Builds through 78 do not send this header; coordinate strict enforcement with the client update.

The prompt

Paste this into Claude Code, Cursor, or any coding agent with access to your backend's repo. It is the frozen contract in prompt form. The identifiers in it (/.well-known/parlane.json, parlane://) are protocol-locked and won't change under you.

paste into your coding agent
Make my app Parlane-ready.

Parlane is a universal native mobile client. It renders my backend natively — chat,
voice, dashboards, push — from plain JSON I serve. There is no SDK. I implement a tiny
contract; any of the following it can already do (MCP) it reuses.

Implement chat unless I explicitly tell you not to. Chat is the core surface: voice rides
on it with no extra server work (speech runs on-device), and a connected app without chat
feels broken on first open. Wire /chat to whatever conversational or agent capability my
backend has; if it truly has none, ask me before omitting it, and then leave the chat
surface undeclared in the manifest so the client hides those tabs.

Do this:
1. Serve an app manifest at /.well-known/parlane.json (or an MCP resource
   "parlane://manifest"). Declare only the surfaces I actually support. All fields are
   optional. Validate it against spec/manifest.schema.json.
   Ask me about the look: accent, colors, dark/light — declare a theme in the manifest to
   skin my app's screens.

2. If I don't already speak MCP, add the REST fallback:
   - POST /chat {conversation_id, message, attachments?} -> Server-Sent Events with these
     event types: `delta` {text}, `tool` {tool,status,label?}, `done` {conversation_id,
     message_id?}, `error` {code,message}. End with exactly one `done` or `error`.
   - GET /ui/{dashboard_id} -> a UI document (spec/ui-document.schema.json): a tree from the
     17-type catalog {stack, card, text, metric, chart, table, list, image, button, input,
     toggle, slider, select, progress, badge, divider, map}. version:1, single root, max
     depth 12, max 500 nodes. Full-replace only — no patch format.
   - POST /action {action_id, tool, params, dashboard_id?} -> {ui} (a full replacement UI
     document) or {ack:true}. Interactive components carry an action envelope
     {tool, params?, confirm?, refresh:"self"|"none"|<dashboardId>}; inputs bind values by a
     `bind` name that I merge into params.

3. Require Authorization: Bearer <token> on every request. Optionally print a connect QR
   encoding parlane://connect?url=...&token=...
   (Advanced, MCP transport only — skip unless I ask: to require OAuth 2.1 instead of a
   static token, gate the MCP endpoint so an unauthenticated request returns 401 with a
   WWW-Authenticate protected-resource pointer; the client then runs the full OAuth login
   itself — discovery, dynamic client registration, PKCE, and refresh. See §6a.)

4. For push (optional, but this is exactly how to turn it on): to enable push notifications you MUST
   declare surfaces.push { relay: true } in the manifest. Without that flag there is no push. That
   one flag wires the app to the Parlane-operated hosted relay automatically; do NOT set
   relayUrl, the hosted relay is the default (only set it to override the host, which is rare).
   Preferred pairing: pre-mint a pairing token (POST /pair/prepare) and put it plus the relay in the
   connect QR (parlane://connect?...&relay=...&pair=...) so a single scan connects AND pairs
   the relay with zero extra user steps; if my server does not pair at connect, the app offers a
   manual pairing fallback. CRITICAL for one-scan: after the app redeems the QR token my server never
   saw the phone's public key, so poll GET /pair/prepare/status?pairToken=... until it returns
   { state:"REDEEMED", appPubKey } and derive the session key from that appPubKey before sending any
   encrypted envelope. Trigger notifications with POST /notify carrying an encrypted payload
   plus a visible apnsHint matching spec/push.schema.json; no persistent WebSocket is needed
   for push. The relay and Apple can read apnsHint, and the current iOS app does not decrypt
   the sealed payload into a private preview. Use generic hints for sensitive events.
   I never supply Apple credentials; Parlane owns the only APNs key
   for its app and a self-hosted relay cannot deliver push. Test push against a TestFlight build
   (production APNs), not a dev build.

5. For the share sheet (optional): declare surfaces.share { accepts: [kinds I handle], tool }.
   The app only offers my app for the kinds I list — include "image"/"file" if I ingest
   screenshots or documents, or I am never offered for them. My share.tool receives
   params.attachments[] (images/files as base64 data, per spec/attachment.schema.json) plus flat
   note/url/text. Raise the tool endpoint's body limit to >=20 MB (nginx client_max_body_size,
   framework JSON limits) — base64 adds ~33% over the 10 MB cap, so a default 1 MB limit 413s on a
   screenshot — and enforce the 10 MB decoded cap server-side.
   If I only handle some file types, add surfaces.share.acceptsMimes (e.g. ["image/*","application/pdf"])
   so the app pre-filters unsupported types before upload; and reject bad shares with the standard codes
   {error:{code,message,details?}} — unsupported_kind / unsupported_mime {mime,accepted?} / attachment_too_large {maxBytes} — so failures tell the user what to fix.

Constraints: dashboards are declarative data, never code. Keep all user-visible copy in the
JSON I serve. Follow the schemas in spec/ exactly and test against spec/examples/.

The prompt references spec/ files by repo-relative path. If your agent is working in your own repo, give it the hosted copies below, or point it at /llms-full.txt, which inlines the entire integration kit in one fetch.

With Claude Code, or any MCP client

The demo agent also hosts a developer-tools MCP server: the integration guide, this prompt, every schema, and a validator for each document type, exposed as callable tools (get_schema, validate_manifest, validate_ui_document, …). Add it and your coding agent can pull the contract and check its own work as it goes, instead of you ferrying files:

claude mcp add --transport http parlane-dev https://mcp.parlane.ai/mcp

Any MCP client works the same way: streamable HTTP, no auth, read-only. This is tooling for while you build; in production your backend talks to Parlane over its own MCP server (the manifest becomes the resource parlane://manifest, actions become tool calls) or the REST fallback from the prompt above.

The schemas

The JSON Schemas (draft 2020-12) are the authoritative contract: when any prose and a schema disagree, the schema wins. They are hosted here at stable URLs, so an agent in any repo can fetch and validate against them:

Readable companions: the manifest reference and the REST contract. Agent-facing index: /llms.txt.

Test against the live demo agent

A hosted reference server implements the REST contract end-to-end: chat over SSE, three dashboards, and the action loop. Use it to see valid documents before you write your own, or to diff your server's output against a known-good implementation:

fetch a known-good manifest
curl https://mcp.parlane.ai/.well-known/parlane.json

After reviewing the manifest's disclosure, include Parlane-Data-Policywith its current version when fetching /ui/bridge. You can also open https://mcp.parlane.ai/ in a browser for a connect QR you can scan with the app. Point the app at it to feel the full flow before you build your own.

Next