AQUAVIA API

Introduction

One REST API for the whole platform — send an SMS, place a call, verify a phone number, deliver an email, or run an AI agent, all with the same authentication, conventions, and webhooks.

The API is organized around predictable, resource-oriented URLs. It accepts JSON request bodies, returns JSON responses, and uses standard HTTP verbs, status codes, and authentication. Every response includes a request ID so support can trace exactly what happened. If you can make an HTTPS request, you can use AtomMatrix — the official SDKs are thin wrappers over the same endpoints documented here.

Base URL & versioning

All requests go to a single base URL over HTTPS. Plain HTTP is not supported.

https://api.aquavia.ai/v1

The API is versioned in the path (/v1). We add fields and endpoints without bumping the version; those are considered backward-compatible and your integration should ignore unknown fields. Breaking changes ship under a new version with advance notice and an overlap period. We recommend pinning to /v1 and reading the conventions below so additive changes never break you.

Authentication

Authenticate every request with an API key sent as a bearer token in the Authorization header. You create and rotate keys in the AtomMatrix console under Settings → API keys.

Authorization: Bearer sk_live_3f9c...your_key

Keys come in two flavors, distinguished by prefix:

• sk_test_... — test keys. Requests are fully processed by the API but nothing is actually sent to a carrier or inbox, and you aren't billed. Use these in development and CI.
• sk_live_... — live keys. Real messages, real calls, real charges.

Keep secret keys secret. A key grants full access to your account. Never embed one in client-side code, a mobile app, or a public repo. If a key leaks, revoke it in the console — revocation takes effect immediately. Scope keys per environment and per service where possible.

Requests without a valid key return 401 Unauthorized. See Errors & limits for the full list.

Quickstart

Go from zero to a first API call in a few steps.

• Get a test key (sk_test_...) from the AtomMatrix console under Settings → API keys.
• Send a first request to https://api.aquavia.ai/v1 over HTTPS, with your key in the Authorization: Bearer header and a JSON body.
• Read the JSON response and note the request ID included with it — support can use it to trace exactly what happened.
• When you are ready for real traffic, switch to a live key (sk_live_...).

Conventions

Every endpoint follows the same conventions, so what you learn once applies across messaging, voice, verification, email, and AI agents.

• Predictable, resource-oriented URLs under the /v1 base path.
• JSON request bodies and JSON responses, with standard HTTP verbs and status codes.
• A request ID on every response, for tracing and support.
• Additive changes ship without a new version, so ignore fields you do not recognize.

SMS

Send transactional and marketing text messages through the same API. Programmable SMS covers time-critical sends, campaigns at scale, two-way messaging with inbound replies and keywords, and sender IDs and numbers chosen by what each market allows.

Per-message delivery receipts report status, carrier-level delivery detail, and clear failure reasons. Opt-out handling and suppression lists keep you compliant.

Voice calls

Place and receive calls programmatically. Voice covers outbound notifications, IVR menus with keypad (DTMF) input, inbound service lines that answer, route, queue, and record calls, and text-to-speech in 90+ languages.

Call events and recordings, such as ringing, answered, and completed, can feed your workflows and analytics, and machine detection tells a person from a voicemail.

One-time passcodes

Verify phone numbers with one-time passcodes. Codes are sent over SMS or voice, with automatic fallback when a route stalls, so the passcode actually arrives.

You control expiry, retries, and how often a single number can request codes, and velocity and fraud controls help prevent your verification flow from being abused. Verification outcomes feed the customer record and your workflows.

Email

Deliver transactional and marketing email through the same API. Email covers receipts and alerts, campaigns and journeys, guided domain authentication (SPF, DKIM, DMARC), sender reputation, and bounce and complaint handling.

Open, click, and delivery events are available to act on and feed back into analytics.

AI agents

Run AI agents that understand intent, retrieve knowledge, call your tools, and hand off to a person when a case needs judgment. The same agent carries context across SMS, chat, voice, and email, in 90+ languages.

Agents use the same authentication, conventions, and webhooks as the rest of the API.

Knowledge & RAG

Ground agent answers in your approved documents and live business data instead of guessing. Knowledge retrieval lets responses come from your help center and policies rather than a generic reply.

Webhooks

Webhooks work the same way across every product on the platform. Delivery receipts, call events, verification outcomes, email engagement, and agent results are reported as events, so your systems stay in sync without polling.

Errors & limits

The API uses standard HTTP status codes and returns JSON error responses. A request without a valid key returns 401 Unauthorized.

Every response includes a request ID. Include it when you contact support so they can trace exactly what happened.

SDKs & libraries

If you can make an HTTPS request, you can use AtomMatrix. The official SDKs are thin wrappers over the same endpoints documented here, so everything in this documentation applies whichever way you integrate.