Apps API — Configurator

API reference for Configurator app management endpoints

configurator

apiconfiguratorapps

Updated 2026-11-03

Verified 2026-11-03

The Apps API manages apps: the end-user deployment unit that binds an orchestrator agent to channel configuration (chat, voice, email, WhatsApp) and guardrails. For architecture and configuration, see Configurator.

Paths are relative to the Configurator service root (port 8100 locally). Authentication, required headers, errors, and the pagination envelope follow the API conventions; see Pagination for page and page_size.

When a request sends X-Project-Id, list and bulk-fetch results only include apps enabled in that project, and detail routes return 404 for apps that are not enabled. New apps are bound to the project after creation; when binding fails, the response reports the failure instead of 201.

Endpoints

Method	Path	Permission	Description
GET	`/api/v1/apps/`	`HasCanViewAppPermission`	List apps
POST	`/api/v1/apps/`	`HasCanCreateAppPermission`	Create an app (`201`)
GET	`/api/v1/apps/{id}/`	`HasCanViewAppPermission`	Get an app with its configurations
PUT	`/api/v1/apps/{id}/`	`HasCanUpdateAppPermission`	Update an app (creates or edits a draft)
DELETE	`/api/v1/apps/{id}/`	`HasCanDeleteAppPermission`	Delete an app (`204`)
POST	`/api/v1/apps/{id}/deploy/`	`HasCanUpdateAppPermission`	Deploy the latest draft
GET	`/api/v1/apps/bulk-fetch/`	`HasCanViewAppPermission`	Fetch several apps by reference
POST	`/api/v1/apps/{id}/share-with-organization/`	Organization administrator	Share a project app with the organization

There is no PATCH, versions, or app-code lookup route.

Create or Update an App

POST /api/v1/apps/ and PUT /api/v1/apps/{id}/

Field	Type	Required	Description
`name`	string	yes	App name
`description`	string	no	Description
`industry`	string	no	`hospitality`, `banking`, `consumer_goods`, `legal`, `healthcare`, `manufacturing`, or `electronics`
`framework`	string	no	`google_adk`
`configuration`	object	yes	Configuration fields below
`visibility`	string	no	Create only; project or organization visibility when `X-Project-Id` is sent

Configuration fields

Field	Description
`orchestrator_agent`	`{"id": "...", "version": "1.0"}`, the root agent the app runs
`chat_config`	Chat channel: `chat`, `chatbot_config`, `first_message`
`voice_config`	Voice channel (see below)
`email_config`	Email channel: `{"cloud_email": {"provider": "..."}}`
`whatsapp_config`	WhatsApp channel: `{"cloud_whatsapp": {"provider": "..."}}`
`guardrails`, `use_org_default_guardrails`	App guardrails, or the organization defaults

Read-only fields: version and status.

Voice configuration

voice_config accepts only the modern profile: profile: "modern" with schema_version: 2. It contains stt, tts, cloud_calling, vad, turn_detection, interruptions, idle, max_duration, background_audio, noise_cancellation, first_message, and is_recording_enabled.

bash

curl -s -X POST 'http://localhost:8100/api/v1/apps/' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'X-Org-Id: YOUR_ORG_ID' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Acme Support",
    "description": "Customer-facing support assistant",
    "industry": "consumer_goods",
    "framework": "google_adk",
    "configuration": {
      "orchestrator_agent": {"id": "AGENT_ID", "version": "1.0"},
      "chat_config": {"first_message": "Hello! How can I help you today?"}
    }
  }'

The response is the app (id, org_id, name, description, industry, framework, timestamps) with a configurations list. Each configuration includes the hydrated orchestrator agent.

Versioning

Versions are major.minor strings. On update:

Latest version	Change	Result
Deployed	Only the orchestrator agent version changed	Next minor version
Deployed	Anything else	Next major version
Draft (major) or only the orchestrator agent version changed	Any	The draft is updated in place
Draft (minor)	Anything else	Next major version

Each new configuration emits app.configuration.added or app.configuration.updated on the configurator Kafka topic.

List Apps

GET /api/v1/apps/

Parameter	Description
`name`	Name filter
`industry`	One or more industries
`status`	`draft` or `deployed`
`version`	Configuration version
`version_type`	`all`, `major`, or `minor`
`page`, `page_size`	Pagination

Get an App

GET /api/v1/apps/{id}/ accepts status, version, and version_type to select which configurations are returned.

Deploy

POST /api/v1/apps/{id}/deploy/

Takes no body and deploys the latest draft. Returns 400 with No draft configuration to deploy. or Configuration already deployed.. Deployment also requires the orchestrator agent's whole sub-agent tree to be deployed; otherwise it returns 400 listing the sub-agents still in draft. Consumers receive app.configuration.deployed.

Delete

DELETE /api/v1/apps/{id}/ deletes the app and returns 204. Consumers receive app.deleted.

Bulk Fetch

GET /api/v1/apps/bulk-fetch/?app=<uuid>&app=<uuid>:2.0

Each app value is either a UUID (latest deployed configuration; returned with configuration: null when nothing is deployed) or uuid:version (that exact version; omitted when it does not exist). The response is a list with no pagination wrapper. Service callers must act on behalf of a user unless they are allowlisted ownership-query services.

Agents API: agents that apps orchestrate
Tools API: tools that agents use
ADK Converse API: agent execution