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. Everyone else, workspace admins and client administrators included, gets 403.

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

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

Open Settings → Admin → General → Landing suggestions.
Edit the list and save. Saving publishes the complete list to all inheriting workspaces immediately.

Set them through the API

The settings are deployment-wide, so no X-Space-Slug is sent.

Read the current defaults. The response holds the complete landing_suggestions list plus other settings such as agent_selector:
```
curl "$CENTRAL_HUB_URL/api/v1/platform-admin/settings/" \
  -H "X-API-Key: $ALO_PLATFORM_API_KEY"
```

Optional: upload an image for an example before publishing the suggestion that uses it:

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:

{
  "id": "product-launch-2026",
  "image_width": 1200,
  "image_height": 675,
  "image_url": "https://storage.example.com/..."
}

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:

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

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.