> Documentation index: [/llms.txt](/llms.txt). Every page as one file: [/llms-full.txt](/llms-full.txt). # Set landing defaults Set landing defaults [#set-landing-defaults] Publish the landing suggestions that every workspace without its own list shows. Requires: a platform admin, signed in or with a [platform key](../api-basics/authentication). Everyone else, workspace admins and client administrators included, gets `403`. Limits [#limits] | Item | Rule | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Suggestions | At most 9 per deployment | | `label` | Required; 1–48 characters, at most three words | | `prompt` | Required; 1–4,000 characters, inserted when the user chooses the suggestion | | `agent_id` | Required; an active global agent whose `catalog_kind` is `alo`. Find one with `GET /api/v1/agents-v2/agents/?show_platform=true` | | `model_config_id` | Optional; an enabled global model | | `icon` | A built-in icon key (default `bot`) or a PNG, JPEG or WebP data URL | | `categories` | Up to 8; each needs `id` (1–64 characters) and `label` (1–48) and holds up to 12 examples | | Examples | At most 60 in total. Each needs `id` (8–64 letters, digits or `-`, unique), `title` (1–80) and `prompt` (1–4,000); `agent_id`, `model_config_id` and an image are optional overrides | | Example image | PNG, JPEG or WebP up to 10 MB; resized to fit 1200 × 1200 and stored as WebP | How workspaces inherit them [#how-workspaces-inherit-them] `GET /api/v1/spaces/current/settings/` returns the effective list: | Workspace state | Effective suggestions | `landing_suggestions_source` | | ----------------------------------------- | --------------------- | ---------------------------- | | One or more workspace suggestions | Workspace list only | `workspace` | | Missing or empty workspace list | Platform list | `platform_default` | | No workspace list and empty platform list | Empty list | `platform_default` | * Platform and workspace lists never merge. * To restore inheritance, send `landing_suggestions: []` to the workspace settings endpoint or delete the final custom suggestion. * `suggested_agent_ids` is derived from the active resolved suggestions. Resolving platform defaults for a workspace applies these checks without changing the stored configuration: | In that workspace | Result | | ----------------------------------------------- | ---------------------------------------------------- | | Suggestion's base agent is inactive or disabled | Suggestion omitted | | Example-agent override unavailable | Cleared; the example inherits its suggestion's agent | | Model override unavailable | Cleared; normal model fallback applies | Set them in the web app [#set-them-in-the-web-app] 1. Open [**Settings → Admin → General → Landing suggestions**](https://platform.alomana.com/settings/admin/general). 2. Edit the list and save. Saving publishes the complete list to all inheriting workspaces immediately. Set them through the API [#set-them-through-the-api] The settings are deployment-wide, so no `X-Space-Slug` is sent. 1. Read the current defaults. The response holds the complete `landing_suggestions` list plus other settings such as `agent_selector`: ```bash curl "$CENTRAL_HUB_URL/api/v1/platform-admin/settings/" \ -H "X-API-Key: $ALO_PLATFORM_API_KEY" ``` 2. Optional: upload an image for an example before publishing the suggestion that uses it: ```bash curl -X POST \ "$CENTRAL_HUB_URL/api/v1/platform-admin/settings/examples/product-launch-2026/image/" \ -H "X-API-Key: $ALO_PLATFORM_API_KEY" \ -F "file=@product-launch.webp" ``` The response gives the normalized size and a temporary `image_url`; copy the size into the example and set `has_image` to `true`: ```json { "id": "product-launch-2026", "image_width": 1200, "image_height": 675, "image_url": "https://storage.example.com/..." } ``` 3. Publish the suggestions. `PATCH` changes only the fields you send, but `landing_suggestions` replaces the whole list: send every suggestion you keep. An empty list publishes none: ```bash curl -X PATCH "$CENTRAL_HUB_URL/api/v1/platform-admin/settings/" \ -H "X-API-Key: $ALO_PLATFORM_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "landing_suggestions": [ { "agent_id": 42, "active": true, "label": "Launch a campaign", "prompt": "Help me plan and launch a campaign.", "icon": "megaphone", "model_config_id": null, "categories": [ { "id": "campaign-types", "label": "Campaigns", "examples": [ { "id": "product-launch-2026", "title": "Product launch", "prompt": "Create a launch plan for a new product.", "agent_id": null, "model_config_id": null, "has_image": true, "image_width": 1200, "image_height": 675 } ] } ] } ] }' ``` Troubleshooting [#troubleshooting] | Response | Cause | Fix | | ---------------------------------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------- | | `422` `Landing defaults may only use an active global Alo agent` | An `agent_id` is not an active global agent with `catalog_kind` `alo` | Pick an agent that qualifies | | `422` `Landing defaults may only use an enabled global model` | A `model_config_id` is not an enabled global model | Pick a model that qualifies, or send `null` | | `422` `A workspace may have at most 60 examples` | More than 60 examples in total | Remove examples | | `422` `Invalid example ID` on the image upload | The ID is not 8–64 letters, digits or `-` | Use a valid ID, the same one as in the example | | `403` | The caller is not a platform admin | Use a platform admin's session or platform key | Images are stored under the platform-owned `platform-landing-examples/` prefix, separate from workspace images; removing an example from the saved configuration schedules its image for cleanup.