Overview

An app is software of yours that acts in an Amedeus workspace: it posts messages, reacts to what people write, and answers slash commands. Everything documented here is stable within v1: we add fields and endpoints, and never rename or remove them.

An app belongs to the workspace that created it. Who may create one is each workspace’s choice, as in Slack: only owners and admins (the default), any member, or members who ask and admins who approve. Owners and admins can always manage every app; a member manages the apps they made, under Manage → Your apps. It is its own member of the workspace, with a name and an avatar, and it acts only where it belongs.

A member’s app reaches only public channels and the private ones they are in, and an AI agent is always made by an owner or admin.

Way in	Use it to
Incoming webhooks	Post to a channel with one URL, no token
Web API	Post, read, react and list, with a bot token
Events	Hear about messages and mentions
Slash commands	Let people ask your app for something with /command

Conventions

• Base URL: https://amedeus.app/api/public/apps/v1 (for a self-hosted Amedeus, your own origin).
• Authentication: Authorization: Bearer amd_bot_…. The token is shown once, when the app is created or its token replaced. Incoming webhook URLs and slash command response URLs carry their own secret and need no token.
• Format: requests and responses are JSON (Content-Type: application/json). Send nothing else.
• Identifiers: UUIDs, as strings.
• Times: ISO 8601 in UTC, for example 2026-11-12T19:18:43.527829+00:00.
• Message text: Markdown, exactly as the person wrote it. A person’s mention appears as @Name in the text, and the ids of the people mentioned are listed in mentions.
• Success: { "ok": true, … }.
• Failure: { "ok": false, "error": "<code>", "message": "…" } with the real HTTP status. Compare the error code; the message is for people and can change. See Errors.
• Pagination: list endpoints take limit (1 to 200) and cursor, and answer next_cursor: when it is not null, pass it as cursor to read the next page.
• Limits: 60 messages a minute per app and channel, 60 a minute per webhook URL, and 300 requests a minute per address. Over the limit you get 429 with error: "ratelimited" and a Retry-After header in seconds.

Versioning

The version is in the URL (/v1) and in the User-Agent of what we send (Amedeus-Apps/1). Inside a version we only add: new fields in responses and payloads, new endpoints, new event types, new error codes. Write your code to ignore what it doesn’t know. A breaking change would be a new version, announced with notice, with the old one kept running.