--- title: Get App | Luma Agents --- GET /v1/apps/{app\_slug} Select code samplecURL (shell:curl) ```js const url = 'https://agents.lumalabs.ai/v1/apps/example'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request GET \ --url https://agents.lumalabs.ai/v1/apps/example \ --header 'Authorization: Bearer ' ``` - Productionagents.lumalabs.ai/v1/apps/{app\_slug} 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 - **[BearerAuth](/api/agents/index.md#bearerauth)** ## Parameters ### Path Parameters **app\_slug** required *App Slug* string ## Responses ### 200 Successful Response Media typeapplication/json *AppDetailsResponse* One entitled app with its experience contract. object **current\_release** required *AppCurrentRelease* 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. object **activated\_at** Any of: - [string](#tab-panel-0-0) - [null](#tab-panel-0-1) string format: date-time null **package\_digest** required *Package Digest* The release's sealed digest — the identity a session freezes. With no release active, the digest of the package shipped in Luma's code that the session runs. string **version** required *Version* string **display\_name** required *Display Name* string **experience** required *AppExperienceContract* 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 **artifact\_json\_schema** required *Artifact Json Schema* JSON Schema of the app's plan artifact. object ***key*** additional properties any **artifact\_schema\_ref** required *Artifact Schema Ref* string **command\_lane** required *AppCommandLane* Whether a session accepts these commands now; a host renders no command control while closed. object **reason** Any of: - [AppCommandLaneClosedReason](#tab-panel-1-0) - [null](#tab-panel-1-1) *AppCommandLaneClosedReason* Why the session would refuse every `user.command` right now. string Allowed values: not\_accepted\_here app\_commands\_disabled null **state** required *AppCommandLaneState* string Allowed values: open closed **commands** required *Commands* Empty when the app takes no direct commands. Array\ *AppCommandContract* One typed operation the app accepts and the body it takes. object **operation** required *Operation* The operation discriminator its body carries. string **payload\_schema** required *Payload Schema* JSON Schema of the command body. object ***key*** additional properties any **preconditions** required *Preconditions* Revisions the body carries; a stale one refuses the command without changing anything. Array\ Allowed values: expected\_revision **replay** required *AppCommandReplay* How a repeated `user.command` is answered. object **is\_retry\_safe** *Is Retry Safe* Whether a blind retry after an ambiguous network failure cannot repeat work. Without a key, never retry a command whose outcome is unknown. boolean **keyed\_by** *Keyed By* The per-event idempotency\_key: the same key and request replay the recorded outcome; the same key with a different request is a conflict. string default: idempotency\_key Allowed value: idempotency\_key **scope** *Scope* Keys are scoped to the addressed session. string default: session Allowed value: session **compatibility** required *AppContractCompatibility* 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 **contract\_digest** required *Contract Digest* Digest of every contract field outside compatibility. A host caches the contract's behavior by it; release identity is package\_digest. string **kind** required *AppContractKind* 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. string Allowed values: exact\_release\_digest runtime\_registration **package\_digest** required *Package Digest* string **version** required *Version* string **contract\_version** *Contract Version* integer default: 1 **driver** required *AppDriver* 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). string Allowed values: planner deterministic **lanes** required *Lanes* 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. Array\ Allowed values: message command **ports** required *AppPorts* 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 **inputs** *Inputs* Array\ default: *InputPort* An input. `roles` are the roles it accepts; `roles_any: ["*"]` says it accepts every item. object **layout** required *ItemLayout* 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). object **document\_path** required *Document Path* string **id** required *Id* string **ref** Any of: - [string](#tab-panel-2-0) - [null](#tab-panel-2-1) string null **roles** Any of: - [string](#tab-panel-3-0) - [null](#tab-panel-3-1) string null **value** Any of: - [string](#tab-panel-4-0) - [null](#tab-panel-4-1) string null **max\_items** Any of: - [integer](#tab-panel-5-0) - [null](#tab-panel-5-1) integer \>= 1 null **min\_items** *Min Items* integer 0 **name** required *Name* string \>= 1 characters **roles** *Roles* Array\ default: Allowed values: product product.front product.front\_full product.front\_close product.front\_three\_quarter product.front\_three\_quarter\_full product.front\_three\_quarter\_close product.profile product.profile\_full product.profile\_close product.rear product.rear\_full product.rear\_close scene ad ad.master ad.variant brief **roles\_any** *Roles Any* Array\ default: **type** required *PortType* The closed type vocabulary. Adding a member, or a new `@N`, needs both owners. string Allowed values: image\@1 video\@1 text\@1 market\@1 copy\@1 translations\@1 placement\_spec\@1 placement\_renders\@1 layers\@1 brand\_kit\@1 **outputs** *Outputs* Array\ default: *OutputPort* An output. Its items carry `roles` statically, or take them from the input item each was made from (`roles_from`). object **layout** required *ItemLayout* 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). object **document\_path** required *Document Path* string **id** required *Id* string **ref** Any of: - [string](#tab-panel-6-0) - [null](#tab-panel-6-1) string null **roles** Any of: - [string](#tab-panel-7-0) - [null](#tab-panel-7-1) string null **value** Any of: - [string](#tab-panel-8-0) - [null](#tab-panel-8-1) string null **max\_items** Any of: - [integer](#tab-panel-9-0) - [null](#tab-panel-9-1) integer \>= 1 null **min\_items** *Min Items* integer 0 **name** required *Name* string \>= 1 characters **roles** *Roles* Array\ default: Allowed values: product product.front product.front\_full product.front\_close product.front\_three\_quarter product.front\_three\_quarter\_full product.front\_three\_quarter\_close product.profile product.profile\_full product.profile\_close product.rear product.rear\_full product.rear\_close scene ad ad.master ad.variant brief **roles\_from** Any of: - [string](#tab-panel-10-0) - [null](#tab-panel-10-1) string null **type** required *PortType* The closed type vocabulary. Adding a member, or a new `@N`, needs both owners. string Allowed values: image\@1 video\@1 text\@1 market\@1 copy\@1 translations\@1 placement\_spec\@1 placement\_renders\@1 layers\@1 brand\_kit\@1 **renderer\_key** required *Renderer Key* Kit registry key; defaults to artifact\_schema\_ref. string **required\_host\_capabilities** required *Required Host Capabilities* 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. Array\ Allowed values: transport uploads media locale telemetry navigation boardExport downloads connectivity **surfaces** required *Surfaces* Placements the app's release declares. Array\ Allowed values: solutions sidebar picker canvas api **renderer\_key** required *Renderer Key* 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. string **schema\_ref** required *Schema Ref* The plan-artifact schema this app's sessions produce. string **slug** required *Slug* string ##### Example ```json { "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" ] } } ``` ### 422 Validation Error Media typeapplication/json *HTTPValidationError* object **detail** *Detail* Array\ *ValidationError* object **ctx** *Context* object **input** *Input* **loc** required *Location* Array **msg** required *Message* string **type** required *Error Type* string ##### Examplegenerated ```json { "detail": [ { "ctx": {}, "input": "example", "loc": [ "example" ], "msg": "example", "type": "example" } ] } ```