# NGAIGE API & SDK — executive overview
## In plain English
This page is for someone deciding whether to care, and it reads in under
two minutes. The product has one official front door through which another
company's software can do everything a shop owner could do in chat — bring a
permitted contact list, run a campaign, prove a human approved it, send,
and see the bill. Two promises carry the money story: every legal rule is
enforced inside that door itself, so no partner software can accidentally
break the law for you; and nothing private ever leaves the operator's
walls — the clever part of the product sees only the merchant's own brief
words, never a phone number. **The one takeaway:** a partner can build
against this without becoming a compliance risk — the door does the
policing, and every claim on this page is demonstrated by a real exchange
in the engineer guides it links. *(≈135 words)*
## Why it matters
- **Compliance is inside the door.** Consent, the forever-STOP and the human
approval gate are enforced server-side for every caller — a partner's bug
cannot become your regulatory fine.
- **Privacy sells the deal.** The intelligence sees briefs, never phone
numbers — the one sentence that ends most procurement privacy reviews.
- **Proven, not presented.** Every claim links to an executed request and
response — the page survives a judge asking "that really happened?"
*(The one-page overview for decision-makers follows unchanged.)*
---
*One page for decision-makers. Engineers: start with the human API guide
(`docs/api/README.md`) and the reference client guide (`docs/sdk/README.md`);
every technical claim below is demonstrated there with executed examples.*
```mermaid
%%{init: {"theme":"base","themeVariables":{"background":"#ffffff","fontFamily":"-apple-system, Segoe UI, Helvetica, Arial, sans-serif","fontSize":"16px","primaryColor":"#ffffff","primaryBorderColor":"#440088","primaryTextColor":"#1b1230","lineColor":"#6b5d86","clusterBkg":"#f6f2fb","clusterBorder":"#440088","titleColor":"#1b1230","edgeLabelBackground":"#ffffff"}}}%%
%% truth: docs/collateral/api-sdk-overview.md §1–§4 (the five flows; compliance inside the contract) · docs/sdk/README.md two-realm note (what crosses and what never does)
flowchart LR
MNO["Your operator's app
the business signs up and
runs campaigns from inside it"]
NG[["NGAIGE
run by your operator, inside its estate
every import consent-proofed · every send human-approved ·
every opt-out honoured by construction"]]
CUST["The small business's
customers
every one of them said yes"]
NOTE["Data never leaves either realm
phone numbers, consent proofs and receipts stay operator-side —
the AI lanes see only the merchant's own brief, never a number"]
MNO -->|"one versioned door (HTTPS + JSON)"| NG
NG -->|"approved, consent-checked texts"| CUST
NG --- NOTE
classDef hero fill:#eaf3fc,stroke:#2a78d6,stroke-width:2px,color:#1b1230
classDef amber fill:#fdf6e3,stroke:#eda100,stroke-width:2px,color:#1b1230
classDef greencall fill:#eafff4,stroke:#0FFC5A,stroke-width:2.5px,color:#0b5c2e
class MNO hero
class CUST amber
class NOTE greencall
linkStyle 1 stroke:#0FFC5A,stroke-width:3.5px
linkStyle 2 stroke:#0FFC5A,stroke-width:2px
```
*The five-second picture: green marks the consent-checked path; the data
callout is the two-realm law. Truth source: this page §1–§4 and the
reference client guide's two-realm note —
what crosses (the merchant's own brief) and what never does (phone numbers,
consent proofs, receipts).*
## 1. What it is
NGAIGE's **Channel API** is the front door to the whole Phase One engine for
external software: onboard a small business, import its consented contact
list, draft and plan a campaign, record a human approval, dispatch the
messages over the operator's network, and read back delivery, cost and the
opt-out ledger — over plain HTTPS + JSON, per-tenant keys, one versioned
surface. An "SDK" today is a small guide-away problem, not a codebase: the
surface is deliberately few routes with executes-exactly-as-documented
behaviour, so integrators build against it directly from the reference
client guide.
## 2. Why an operator would embed it
- **Compliance as the pitch, not the footnote.** Every recipient provably
consented, every opt-out honoured by construction, every send
human-approved — and the receipts are API-readable, so the MNO sells
"compliant business messaging" with evidence, not promises.
- **Embeddable in a day.** Five flows cover the common journeys; the
refusal grammar is a single table; idempotency and rate-limit answers
are machine-honest. No SDK to wait for, no vendor runtime to host.
- **Data stays operator-side.** In an MNO embedding the system of record —
recipient lists, consent evidence, opt-outs, delivery and billing
records — lives inside the operator's realm. The AI lanes see only the
business-authored brief text, never a phone number. That is a property
of the architecture, not a policy setting.
- **Model-agnostic by construction.** A sovereign model router picks the
best available self-hosted model for each job from a hierarchy that
improves over time — the operator adopts better models without changing
the product: no vendor lock, upgrades without migration. (Today's
hierarchy is a dated config example in `docs/api/README.md`.)
## 3. The five flows (the whole product, API-shaped)
1. Onboard a business (sender id + tenant isolation from the key).
2. Import contacts — refused unless one consent proof carrier rides along.
3. Draft → plan → submit → approve a campaign. The approval step is its
own API scope: machines can prepare everything but the human decision.
4. Dispatch — refused until approved; numbers on the STOP ledger are
skipped server-side and the response names them.
5. Report — sent/delivered/failed/suppressed plus actual-vs-estimated cost
— and the masked opt-out ledger, which never exposes a raw number.
## 4. Compliance, enforced where it can't be skipped
Three laws run **server-side inside the API contract**, identical for every
caller — a friendly portal, an integrator's script, or something hostile:
- **Consent:** an import without a proof carrier stores nothing (HTTP 422,
zero rows written).
- **STOP:** the dispatch machine checks every target against the durable
opt-out ledger inside the send path; there is no unsuppress path.
- **Approval:** no API path lets a machine mint an approval — the human
gate has its own credential scope and a named actor lands in the audit
trail.
These are pinned by executable specification, demonstrated on every
release, and documented with real response bytes.
## 5. State of play (2026-08-27)
| Piece | State |
| --- | --- |
| HTTP contract (OpenAPI 3.0.3) | Shipped; pinned by executable spec |
| Human API guide | Shipped; all examples executed for real |
| Reference client guide (curl + language-agnostic patterns) | Shipped; 23 executed calls in Appendix A |
| Staging boundary (`product-staging.staging.con5ult.com`) | Pending platform enable (ask on file); local boot verified end-to-end |
| Per-language SDK packages | Not yet — thin bindings over this surface when they land; shapes frozen |
## 6. Brand notes for collateral builds
Markdown is the portable form. For the styled HTML twin (welcome file,
decks, one-pagers), build on `docs/brand/README.md` tokens: deep surfaces
`#110022`/`#220044`, primary purple `#440088`, consent-and-success green
`#0FFC5A`, attention orange `#FF4700` (warning, not error-red), info blue
`#00AAFF`. Wordmark: **NGAIGE** (caps) or **Ngaige** in prose. Voice:
direct, assured, compliance-positive — consent is the selling point
("every recipient consented — here's the receipt").