Skip to content
DevelopersIn development

API reference

The RapidRoot REST API is in development. This page documents the intended resource model, formats and conventions so integration teams can plan ahead.

Status

The public API is not generally available. Endpoints, field names and behaviour described here may change before release. Pilot customers can request early access through technical sales.

Request and response format

  • JSON over HTTPS. TLS is required; plain HTTP will not be accepted.
  • Authentication via an API key sent as a bearer token.
  • UTF-8 encoding, ISO 8601 timestamps in UTC.
  • Collection endpoints will be paginated with cursor-based paging.
Example format — not a live endpoint
GET /v1/conversations?limit=25&cursor=eyJpZCI6...
Authorization: Bearer <API_KEY>
Accept: application/json

200 OK
{
  "data": [ { "id": "cnv_2h81", "channel": "whatsapp", "state": "open" } ],
  "next_cursor": "eyJpZCI6Li4u",
  "has_more": true
}

Planned resources

Messages

In development

Send template and session messages, read delivery state.

Conversations

In development

List and update conversations in the shared inbox.

Contacts

In development

Create, update and search contacts and attributes.

Calls

In development

Trigger outbound AI calls and read call outcomes.

Agents

In development

Read voice agent configuration.

Events

In development

Read event history that mirrors webhook deliveries.

Error handling philosophy

  • Standard HTTP status codes — 4xx for caller mistakes, 5xx for platform faults.
  • A stable machine-readable error code alongside a human-readable message.
  • Validation errors identify the specific field that failed.
  • A request identifier on every response so support can trace a specific call.
Example format
422 Unprocessable Entity
{
  "error": {
    "code": "invalid_parameter",
    "message": "\"to\" must be a phone number in E.164 format.",
    "field": "to",
    "request_id": "req_01H..."
  }
}

Versioning

  • Endpoints will be versioned in the path, starting at /v1.
  • Additive changes — new fields, new endpoints — may ship within a version.
  • Breaking changes require a new version; we will not silently change existing behaviour.
  • A deprecation notice period will be published with the first stable release. We do not promise perpetual compatibility for any single version.

Rate limits

Coming soonPublished limits

Rate limits are not published yet. Concrete per-endpoint limits, headers and burst behaviour will be documented when the public API becomes available. Channel providers such as WhatsApp apply their own throughput and template limits independently of RapidRoot.

Performance guidance

  • Retry failed requests with exponential backoff and jitter; treat 5xx and network timeouts as retryable.
  • Make retries idempotent by keying on your own reference identifier.
  • Prefer webhooks over polling for state changes once webhook delivery is available.
  • Request only the pages you need and page through results rather than fetching everything.
  • Handle errors explicitly instead of assuming success — surface failures to your own logs.