Get App
const url = 'https://agents.lumalabs.ai/v1/apps/example';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url https://agents.lumalabs.ai/v1/apps/example \ --header 'Authorization: Bearer <token>'One app with its experience contract. slug@version reads only the
release that serves: any other pin is APP.VERSION_NOT_ACTIVE, naming
the version that does. APP.RELEASE_LOADING (503) while this process
has not yet loaded the release that serves.
Authorizations
Section titled “Authorizations”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters”Responses
Section titled “ Responses ”Successful Response
One entitled app with its experience contract.
object
Which release of an app a partner's next session would run. With no release active, an app may serve the package shipped in Luma's code instead; this then describes that package.
What a host needs to run an app's experience: the document it renders, the typed commands it may send, the host services it must supply and the surfaces the app is placed on. Describes the release's capability, not the caller's permission to mutate: the server rechecks every input.
object
JSON Schema of the app's plan artifact.
object
Whether a session accepts these commands now; a host renders no command control while closed.
object
Why the session would refuse every user.command right now.
Empty when the app takes no direct commands.
One typed operation the app accepts and the body it takes.
object
The operation discriminator its body carries.
JSON Schema of the command body.
object
Revisions the body carries; a stale one refuses the command without changing anything.
How a repeated user.command is answered.
object
Whether a blind retry after an ambiguous network failure cannot repeat work. Without a key, never retry a command whose outcome is unknown.
The per-event idempotency_key: the same key and request replay the recorded outcome; the same key with a different request is a conflict.
Keys are scoped to the addressed session.
Which release serves, and which contract it serves with. A session
runs the release named by package_digest. contract_digest names
what a host acts on: every contract field outside compatibility. Two
releases with identical behavior share it, and a deploy or a flag that
moves commands, surfaces or the command lane changes it without a new release.
object
Digest of every contract field outside compatibility. A host caches the contract's behavior by it; release identity is package_digest.
What fixes the contract's behavior.
exact_release_digest: a declared app, whose document and commands are
the sealed release's, verified against this process before answering.
runtime_registration: a code-tier app, whose document and commands are
its deployed code; the release digest does not pin them, contract_digest does.
What runs a session's work: planner (an agent turn reads each message) or deterministic (the app's own code runs each command or typed input).
The free-form inputs a session of this app takes: message (user.message, a brief) and command (user.command). Gate verdicts, tool results and consent are always answered when pending.
Declares the item types and roles this app consumes and produces. Luma's host uses these to decide which items may feed an input; matching rules are not yet exposed to partner hosts, so treat this as descriptive. Empty when the app declares none.
object
An input. roles are the roles it accepts; roles_any: ["*"] says it accepts every item.
object
Where a port's items live in the app's artifact. document_path is a
JSON Pointer to the list; the others are pointers within one item ("" is
the item itself).
The closed type vocabulary. Adding a member, or a new @N, needs both owners.
An output. Its items carry roles statically, or take them from the
input item each was made from (roles_from).
object
Where a port's items live in the app's artifact. document_path is a
JSON Pointer to the list; the others are pointers within one item ("" is
the item itself).
The closed type vocabulary. Adding a member, or a new @N, needs both owners.
Kit registry key; defaults to artifact_schema_ref.
What this app needs beyond the baseline every host supplies (transport, uploads, media, locale). A host lacking any of these must refuse before starting a session. Empty when the app needs nothing beyond the baseline.
Placements the app's release declares.
Kit registry key for this app's plan artifact. Defaults to schema_ref; select registry[renderer_key] ?? registry['default'] so an app sharing another's document schema can still ship its own surface.
The plan-artifact schema this app's sessions produce.
Example
{ "experience": { "command_lane": { "reason": "not_accepted_here", "state": "open" }, "commands": [ { "preconditions": [ "expected_revision" ], "replay": { "is_retry_safe": false, "keyed_by": "idempotency_key", "scope": "session" } } ], "compatibility": { "kind": "exact_release_digest" }, "contract_version": 1, "driver": "planner", "lanes": [ "message" ], "ports": { "inputs": [], "outputs": [] }, "required_host_capabilities": [ "transport" ], "surfaces": [ "solutions" ] }}Validation Error
object
object
object
Examplegenerated
{ "detail": [ { "ctx": {}, "input": "example", "loc": [ "example" ], "msg": "example", "type": "example" } ]}