--- title: Get App Surface Template | Luma Agents --- GET /v1/apps/{app\_slug}/surface-template Select code samplecURL (shell:curl) ```js const url = 'https://agents.lumalabs.ai/v1/apps/example/surface-template'; 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/surface-template \ --header 'Authorization: Bearer ' ``` - Productionagents.lumalabs.ai/v1/apps/{app\_slug}/surface-template The app's declared intake surface — its pages, fields, and action copy. ## Authorizations - **[BearerAuth](/api/agents/index.md#bearerauth)** ## Parameters ### Path Parameters **app\_slug** required *App Slug* string ## Responses ### 200 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](#tab-panel-0-0) - [null](#tab-panel-0-1) string null **commands** Any of: - [DeclaredCommandsDeclaration](#tab-panel-1-0) - [null](#tab-panel-1-1) *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\ *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](#tab-panel-2-0) - [null](#tab-panel-2-1) string <= 256 characters null **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](#tab-panel-3-0) - [ItemIndexSource](#tab-panel-3-1) - [LiteralSource](#tab-panel-3-2) - [AskSource](#tab-panel-3-3) *FromFieldSource* The kit reads the current document value at a `
.` path. object **kind** required *Kind* string Allowed value: from\_field **path** required *Path* string *ItemIndexSource* The list index of the item tile the affordance sits on (`placement: item` only). object **kind** required *Kind* string Allowed value: item\_index *LiteralSource* object **kind** required *Kind* string Allowed value: literal **value** required Any of: - [string](#tab-panel-4-0) - [integer](#tab-panel-4-1) - [boolean](#tab-panel-4-2) string integer boolean *AskSource* The kit renders an input for this param (its declared kind picks the control), optionally prefilled from a state path. object **kind** required *Kind* string Allowed value: ask **prefill\_from** Any of: - [string](#tab-panel-5-0) - [null](#tab-panel-5-1) string null **operations** required *Operations* Array\ *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 null **input\_schema** Any of: - [object](#tab-panel-6-0) - [null](#tab-panel-6-1) object ***key*** additional properties any null **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 ```json { "commands": { "affordances": [ { "placement": "document", "sources": { "additionalProperty": { "kind": "from_field" } } } ] }, "picks_as_files": false, "runnable": false } ``` ### 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" } ] } ```