Skip to content
Docs

API v1

Rive SMS API

Send messages, follow their delivery, and receive signed events over a JSON REST API. Anything that can make an HTTPS request can use it.

Overview

  • Predictable JSON — every endpoint returns success, data, and meta.request_id.
  • Bearer auth — scoped API keys per environment with instant revocation.
  • Routing by destination — Rive prices each message for its country and chooses the route; the API retries through the next connector when one returns a retryable error.
  • Signed webhooks — HMAC-SHA-256 signatures with exponential-backoff retries.

Base URL

https://rivesms.com/api/v1

Send your first message

Authenticate with your API key, then POST a JSON body to /messages/send:

Example
curl https://rivesms.com/api/v1/messages/send \
  -H "Authorization: Bearer ds_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to":   "+12025550143",
    "from": "RiveSMS",
    "body": "Your verification code is 482194"
  }'
import fetch from "node-fetch";

const res = await fetch("https://rivesms.com/api/v1/messages/send", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RIVESMS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "+12025550143",
    from: "RiveSMS",
    body: "Your verification code is 482194",
  }),
});

console.log(await res.json());
import os, requests

resp = requests.post(
    "https://rivesms.com/api/v1/messages/send",
    headers={
        "Authorization": f"Bearer {os.environ['RIVESMS_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "to":   "+12025550143",
        "from": "RiveSMS",
        "body": "Your verification code is 482194",
    },
)
print(resp.json())

A successful call returns the created message:

{
  "success": true,
  "data": {
    "id": "msg_VyB2pNkX0wnA9aTrLqDh1Z3Fc",
    "object": "message",
    "to": "+12025550143",
    "from": "RiveSMS",
    "body": "Your verification code is 482194",
    "status": "sent",
    "cost": 0.0500,
    "currency": "USD",
    "created_at": "2026-05-12T11:34:21+00:00",
    "sent_at":   "2026-05-12T11:34:21+00:00"
  },
  "meta": { "request_id": "req_dXp9k...", "api_version": "v1" }
}

Endpoints at a glance

POST /v1/messages/send
POST /v1/messages/bulk
GET /v1/messages/{id}
GET /v1/messages
GET /v1/account
GET /v1/balance
GET /v1/usage
GET /v1/senders
POST /v1/senders/create
GET /v1/senders/{id}
GET /v1/api-keys
POST /v1/api-keys/create
DELETE /v1/api-keys/{id}
GET /v1/webhooks
POST /v1/webhooks/create
DELETE /v1/webhooks/{id}
GET /v1/events

Next steps