Skip to content
Agents
Workflow apps

Get App Surface Template

GET
/v1/apps/{app_slug}/surface-template
curl --request GET \
--url https://agents.lumalabs.ai/v1/apps/example/surface-template \
--header 'Authorization: Bearer <token>'

The app's declared intake surface — its pages, fields, and action copy.

app_slug
required
App Slug
string

Successful Response

Media typeapplication/json
AppSurfaceTemplateResponse

A registered app's declared intake surface plus its identity.

The sibling of AppSpecTemplateResponse: that one says what tools and providers a session gets, this one says what the app asks a user for. surface_template is the page/field declaration a generated-page renderer consumes directly; intake_page_id names the page to open on, so no host re-derives it.

object
app_slug
required
App Slug
string
app_version
Any of:
string
commands
Any of:
DeclaredCommandsDeclaration

The commands member of a declared app's surface template: the operations and the controls that issue them, verbatim from the package. Present only while declared_commands_cfg is ON.

object
affordances
required
Affordances
Array<object>
CommandAffordance

Which surface element issues which command, and where each param's value comes from. Read server-side only by publish validation; served verbatim to the kit.

object
description
Any of:
string
<= 256 characters
label
required
Label
string
>= 1 characters <= 64 characters
operation
required
Operation
string
/^[a-z][a-z0-9_]*$/
placement
required
Placement
string
Allowed values: document item
sources
Sources
object
key
additional properties
One of: discriminator: kind
FromFieldSource

The kit reads the current document value at a <section>.<field> path.

object
kind
required
Kind
string
Allowed value: from_field
path
required
Path
string
operations
required
Operations
Array<object>
DeclaredCommandOperation

One command a declared app's surface may issue: its name, the tool it runs, and the JSON Schema of the body the generic /commands route parses — served so the kit validates before it posts, since a declared slug is not known when OpenAPI is compiled.

object
body_schema
required
Body Schema
object
key
additional properties
any
description
required
Description
string
operation
required
Operation
string
target_tool
required
Target Tool
string
input_schema
Any of:
object
key
additional properties
any
intake_page_id
required
Intake Page Id

Which page of surface_template a host opens on.

string
picks_as_files
Picks As Files

Whether an image picked from a catalog goes to the run as the library file itself (its media ref) rather than as a copy on the project board.

boolean
renderer_key
required
Renderer Key

Frontend renderer id for this app's plan artifact.

string
runnable
Runnable

Whether runs execute without planner turns.

boolean
schema_ref
required
Schema Ref

The plan-artifact schema the app's sessions produce.

string
surface_template
required
Surface Template

The app's declared pages, fields, and action copy.

object
key
additional properties
any
Example
{
"commands": {
"affordances": [
{
"placement": "document",
"sources": {
"additionalProperty": {
"kind": "from_field"
}
}
}
]
},
"picks_as_files": false,
"runnable": false
}

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"
}
]
}