> Documentation index: [/llms.txt](/llms.txt). Every page as one file: [/llms-full.txt](/llms-full.txt).

# Hosted agent apps

Hosted agent apps [#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 [#how-an-app-is-registered]

* The agent registers the app with its `register-app` tool. Registering again from the same chat updates the same app and increases its `version`.
* `register-app` and `update-app` come with the `alo-app-base` skill, which App Builder has.
* A new app is `private`. The API has no call that publishes an app; `published` in the response cannot be set.

Visibility [#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 [#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 [#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](../connectors/connections/overview).