Agents
Hosted agent apps
An app is a web app an agent builds in its sandbox and registers for its chat; Alomana serves it at its own link.
How an app is registered
- The agent registers the app with its
register-apptool. Registering again from the same chat updates the same app and increases itsversion. register-appandupdate-appcome with thealo-app-baseskill, which App Builder has.- A new app is
private. The API has no call that publishes an app;publishedin the response cannot be set.
Visibility
visibility | Who can open the app through the app gateway |
|---|---|
private | Its owner, plus collaborators on its build chat who are workspace members |
space | Members of the app's workspace |
global | Any active platform user |
public | Anyone, without signing in |
- Only the owner can change visibility; anyone else gets
403 Only the app owner can change visibility. - An unknown value is stored as
private.
Endpoints
Every route below needs X-Space-Slug.
| Method | URL | Does | Auth |
|---|---|---|---|
GET | /api/v1/agents-v2/my-apps/ | List apps you can open; visibility (all default, space, global, public, private), limit, offset | Key or bearer |
PATCH | /api/v1/agents-v2/apps/{app_id}/ | Edit name, slug, description, preview_url, status, visibility, tags, declared_connection_ids, declared_mcp_connection_ids | Key or bearer |
DELETE | /api/v1/agents-v2/apps/{app_id}/ | Delete the app | Key or bearer |
GET · POST | /api/v1/agents-v2/apps/{app_id}/chats/ | List · start chats for the app | Bearer only |
GET | /api/v1/agents-v2/apps/{app_id}/preview-health/ | Check the running preview | Key or bearer |
POST | /api/v1/agents-v2/apps/{app_id}/open/ | Get a short-lived, single-use token to open the app through the gateway: {ok, token, gateway_url} | Key or bearer |
GET | /api/v1/agents-v2/apps/{app_id}/secrets/ | List secrets, values masked | Key or bearer |
PUT · DELETE | /api/v1/agents-v2/apps/{app_id}/secrets/{key}/ | Set ({value, description}) · delete a secret | Key or bearer |
POST | /api/v1/agents-v2/apps/{app_id}/copy-to-space/ | Copy the app to another workspace | Key or bearer |
GET · POST | /api/v1/agents-v2/apps/{app_id}/sync-status/ · …/pull-from-source/ | Compare a copy with its source · update the copy from it | Key or bearer |
Credentials
Store API keys and passwords the app needs as app secrets; the running app receives them as environment variables, and the API returns only masked values. Data access goes through the workspace's connections.