# Overview

> What an Amedeus app is, and the conventions every endpoint and payload follows.

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](/guides/incoming-webhooks/) | Post to a channel with one URL, no token              |
| [Web API](/api-reference/)                      | Post, read, react and list, with a bot token          |
| [Events](/guides/events/)                       | Hear about messages and mentions                      |
| [Slash commands](/guides/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](/reference/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.