Build on and customise Ramphearth

Our first priority as revenue comes in

Signed and notarised Windows and macOS apps, and native apps in the App Store and Google Play. See the download page for the apps available today.

Everything you can connect, automate and build on Ramphearth, in one place: the API, bots, webhooks, native integrations, bridges and the controls admins have over them.

Each card says what it does, who can set it up, which plans include it, with Coming soon for anything still being built. The examples use the hosted service at https://api.ramphearth.com. If your organisation runs its own Ramphearth server, use your server's API URL instead; everything else is the same, and a self-hosted server has every feature switched on.

Some integrations need the server operator to register an app or configure a key; each guide explains how. Ramphearth never sells or shares your data: an integration moves data only when someone in your org connects it, and only what it needs. Each guide has a What data moves section.

Quick start

New to the API? These five steps post your first message with curl.

1. Make a token

In Ramphearth, open Settings → Developer (on a phone: You → Developer) and make a personal token. Give it only the scopes this script needs: channels:read and messages:write for this example. The token is shown once. Keep it in a secret store or an environment variable:

export RAMPHEARTH_TOKEN=rh_pat_…

2. Check who the token is

GET /v1/me needs no scope. It says who the token acts as, which orgs it can reach and which scopes it has.

curl -H "Authorization: Bearer $RAMPHEARTH_TOKEN" https://api.ramphearth.com/v1/me

3. Find your org

curl -H "Authorization: Bearer $RAMPHEARTH_TOKEN" https://api.ramphearth.com/v1/orgs

Every list answers { "data": [...], "next_cursor": … }. Note the id of the org you want.

4. List its channels

curl -H "Authorization: Bearer $RAMPHEARTH_TOKEN" \
  https://api.ramphearth.com/v1/orgs/<orgId>/channels

You see only the channels you could see in the app. Note a channel's id.

5. Post a message

curl -X POST https://api.ramphearth.com/v1/channels/<channelId>/messages \
  -H "Authorization: Bearer $RAMPHEARTH_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"content": "Deploy finished"}'

The Idempotency-Key makes a retry safe: if you send the same key again within 24 hours, you get the first message back instead of a second post. See Conventions.

To follow a channel, read it oldest first and keep the next_cursor. Next time, pass it back to get only what's new:

curl -H "Authorization: Bearer $RAMPHEARTH_TOKEN" \
  "https://api.ramphearth.com/v1/channels/<channelId>/messages?order=oldest&limit=100&cursor=<next_cursor>"

The reference

The API reference lists every operation, the scope it needs, its parameters, its request body and its responses. It is generated from the OpenAPI 3.1 document that every Ramphearth server serves at GET /v1/openapi.json, with no token needed. Load that document into Postman, Insomnia or a code generator. The app also draws it, with a filter, at /developers.