Skip to content
Agents
Workflow apps

Get App

GET
/v1/apps/{app_slug}
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.

app_slug
required
App Slug
string

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 format: date-time
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

Why the session would refuse every user.command right now.

string
Allowed values: not_accepted_here app_commands_disabled
state
required
AppCommandLaneState
string
Allowed values: open closed
commands
required
Commands

Empty when the app takes no direct commands.

Array<object>
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<string>
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<string>
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<object>
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
roles
Any of:
string
value
Any of:
string
max_items
Any of:
integer
>= 1
min_items
Min Items
integer
0
name
required
Name
string
>= 1 characters
roles
Roles
Array<string>
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<string>
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<object>
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
roles
Any of:
string
value
Any of:
string
max_items
Any of:
integer
>= 1
min_items
Min Items
integer
0
name
required
Name
string
>= 1 characters
roles
Roles
Array<string>
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
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<string>
Allowed values: transport uploads media locale telemetry navigation boardExport downloads connectivity
surfaces
required
Surfaces

Placements the app's release declares.

Array<string>
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
{
"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

Media typeapplication/json
HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
ctx
Context
object
input
Input
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
Examplegenerated
{
"detail": [
{
"ctx": {},
"input": "example",
"loc": [
"example"
],
"msg": "example",
"type": "example"
}
]
}