Overview
Base URL. Production is https://www.intelliaigroup.co.za/api/v1. The local development server proxies /api/* to the Express backend on 127.0.0.1:3556, so the same relative paths work at http://localhost:3100/api/v1.
Versioning. The major version is in the path (/v1). Breaking changes ship as a new path version; additive fields may appear inside a version. Clients must ignore unknown fields and must not depend on object key order.
| Property | Value |
|---|---|
| Transport | HTTPS only in production; HSTS max-age=31536000; includeSubDomains; preload |
| Content type | application/json; charset=utf-8 |
| Request body limit | 16 KB (413 PAYLOAD_TOO_LARGE) |
| Caching | private, no-store on every /api response |
| CORS | https://www.intelliaigroup.co.za and https://intelliaigroup.co.za, credentials enabled |
| General rate limit | 100 requests / minute / client on /api/ |
06.2-BACKEND/serverless_api/index.js. If a capability is not listed, it is not part of the v1 contract. Do not build against a route discovered in a mock, screenshot or old proposal.Quickstart
1. Probe the platform
curl -s https://www.intelliaigroup.co.za/api/v1/health | jq
# {
# "success": true,
# "data": {
# "status": "ok",
# "healthy": true,
# "checks": { "database": "ok", "paystack": "ok", "gpu": "ok" },
# "database": { "ok": true, "connected": true, "latencyMs": 42 }
# }
# }
The example is illustrative of the shape. Live values are never hard-coded; read them from the response or the status page.
2. Establish a CSRF token
curl -s -c cookies.txt \
https://www.intelliaigroup.co.za/api/v1/auth/csrf | jq '.data.csrfToken'
3. Sign in
curl -s -b cookies.txt -c cookies.txt \
-H 'Content-Type: application/json' \
-d '{"email":"you@example.com","password":"your-password"}' \
https://www.intelliaigroup.co.za/api/v1/auth/login
Login sets access_token (15 minutes, HttpOnly, Secure, SameSite=Strict) and refresh_token (7 days, HttpOnly, Secure, SameSite=Strict). The tokens are never exposed to JavaScript.
4. Read the current identity
curl -s -b cookies.txt \
https://www.intelliaigroup.co.za/api/v1/users/me | jq '.data'
5. State changes from a browser
Cookie-authenticated POST/PUT/DELETE requests must echo the CSRF token in X-CSRF-Token. A request carrying an explicit Authorization: Bearer header is exempt because the browser does not attach it automatically.
const csrf = await fetch('/api/v1/auth/csrf', { credentials: 'include' })
.then(r => r.json());
await fetch('/api/v1/users/me', {
method: 'PUT',
credentials: 'include',
headers: {
'Content-Type': 'application/json',
'X-CSRF-Token': csrf.data.csrfToken
},
body: JSON.stringify({ display_name: 'New name' })
});
Authentication and identity
Two authentication modes share the same routes:
- Browser session — HttpOnly cookies, automatic refresh, CSRF double-submit on state changes.
- Service client —
Authorization: Bearer <access_token>, no CSRF requirement.
| Method | Path | Auth | Purpose |
|---|---|---|---|
| POST | /auth/register | — | Create an account. Password 12–128 chars with upper, lower, digit and special; supply displayName or full_name; optional SA phone +27/0XXXXXXXXX. |
| POST | /auth/login | — | Email + password. Sets access/refresh cookies or returns a bearer token for API clients. |
| GET | /auth/csrf | — | Issues a 24-hour csrf_token cookie and returns the same token in data.csrfToken. |
| POST | /auth/mfa/challenge | — | Completes a login that requires a TOTP second factor. |
| POST | /auth/mfa/setup | Cookie + CSRF | Starts TOTP enrolment; returns the provisioning URI/secret. |
| POST | /auth/mfa/verify | Cookie + CSRF | Verifies a TOTP code and activates MFA. |
| POST | /auth/mfa/disable | Cookie + CSRF | Disables MFA after re-authentication. |
| POST | /auth/change-password | Cookie + CSRF | Changes the password; rate-limited 5/min. |
| POST | /auth/refresh | Refresh cookie | Rotates the session and issues a new access token. |
| POST | /auth/logout | Optional | Deletes the session row and clears both cookies. |
| GET | /auth/verify-email | Token | Consumes an email verification token. |
| POST | /auth/resend-verification | — | Re-sends the verification email; 5/min. |
| POST | /auth/forgot-password | — | Sends a reset link; 3/hour. |
| POST | /auth/reset-password | Token | Consumes a 64-hex reset token and sets a new password; 5/15 min. |
| GET | /users/me | Session | Returns the current profile. |
| PUT | /users/me | Session + CSRF | Updates the profile. Bearer callers are CSRF-exempt. |
Request and response envelope
Successful responses use a stable envelope:
{
"success": true,
"data": { }
}
Errors use one shape and one machine code:
{
"success": false,
"error": {
"code": "INVALID_JSON",
"message": "Request body is not valid JSON"
}
}
| HTTP | Code | Meaning |
|---|---|---|
| 400 | INVALID_JSON | Body is not parseable JSON. |
| 400 | VALIDATION_ERROR | A field failed schema validation; the message names the field. |
| 401 | UNAUTHORIZED | Missing, expired or invalid credentials. |
| 403 | CSRF_REJECTED | Cookie-authenticated state change without a matching X-CSRF-Token. |
| 413 | PAYLOAD_TOO_LARGE | Body exceeds 16 KB. |
| 429 | RATE_LIMITED | Per-route limiter exceeded; inspect RateLimit-* headers. |
| 500 | INTERNAL_ERROR | Unexpected fault. A correlation id is written to the server log. |
| 503 | CONFIG_REQUIRED | A dependency or key is not configured; the route cannot operate. |
Rate limits
Limits are per client, counted in a sliding window, and return standard RateLimit-* headers. Exceeding a limit returns 429 RATE_LIMITED.
| Scope | Limit | Window |
|---|---|---|
All /api/ traffic | 100 | 1 minute |
/auth/login, /auth/mfa/challenge, /auth/change-password | 5 | 1 minute |
/auth/register | 5 | 15 minutes |
/auth/forgot-password | 3 | 1 hour |
/auth/reset-password | 5 | 15 minutes |
/contact | 5 | 1 minute |
/tickets | 10 | 1 minute |
/newsletter | 10 | 1 minute |
/gpu/chat | 10 | 1 minute |
Endpoint catalogue
Treasury and billing
| Method | Path | Auth | Purpose |
|---|---|---|---|
| GET | /treasury/plans | — | Active plans with monthly/annual cents, currency, features and metadata. |
| GET | /treasury/config | — | Public payment configuration (mode, public key presence). |
| POST | /treasury/checkout | Session | Initialises a Paystack checkout. Alias: /payments/initialize. |
| GET | /treasury/subscription | Session | Current subscription and renewal state. |
| GET | /treasury/invoices | Session | Invoice list for the authenticated account. |
| GET | /treasury/invoices/:id/pdf | Session | Invoice PDF stream. |
| GET | /treasury/transactions | Session | Transaction history. |
| GET | /treasury/receipts/:reference | Session | Receipt for a payment reference. |
| GET | /treasury/billing-settings | Session | Billing profile and preferences. |
| PUT | /treasury/billing-settings | Session + CSRF | Updates billing profile. |
| POST | /treasury/webhook | HMAC | Paystack webhook. Alias: /payments/webhook. |
Inference and GPU
| Method | Path | Auth | Purpose |
|---|---|---|---|
| GET | /gpu/status | — | GPU/Ollama availability and model count. |
| GET | /gpu/models | — | Models exposed by the local runtime. |
| GET | /gpu/verify | — | Inference integrity/verification probe. |
| POST | /gpu/chat | — | Chat completion against the sovereign runtime; 10/min. |
| GET | /workloads/predict | — | Division workloads and pre-fetched task vectors; ?division=1..9. |
Operational intelligence
| Method | Path | Auth | Purpose |
|---|---|---|---|
| GET | /axiom/world | — | World signal feed used by Axiom World Monitor. |
| GET | /axiom/market | — | Market signal feed. |
| GET | /axiom/news | — | Curated news feed. |
| POST | /session/context | Optional | Records zero-click/session context for attribution. |
| POST | /marketing/track | — | First-party marketing event. |
| POST | /marketing/identify | — | Associates a visitor with a known identity. |
Support and health
| Method | Path | Auth | Purpose |
|---|---|---|---|
| GET | /health | — | Dependency-aware health probe; drives the status page. |
| POST | /contact | — | Contact form. Requires consent: true; 5/min. |
| POST | /tickets | Optional | Support ticket. Requires division and consent: true; 10/min. |
| POST | /newsletter | — | Newsletter subscription; 10/min. |
Health and observability
GET /api/v1/health is a real probe, not a static ok. It checks Supabase connectivity, Paystack key configuration and the GPU/Ollama endpoint, then returns 200 with status: "ok" | "degraded".
| Field | Meaning |
|---|---|
data.status | ok when the database probe succeeds; otherwise degraded. |
data.checks.database | ok or fail from a live query. |
data.checks.paystack | ok or fail based on key-mode configuration. |
data.checks.gpu | ok or offline; a GPU outage does not fail the platform health by itself. |
data.database.latencyMs | Measured round-trip to the database probe. |
data.paystack.configuredMode | test unless live mode is explicitly enabled. |
data.timestamp | ISO-8601 server time. |
Use the public status page for a human view. Do not scrape it; call the health route directly and alert on healthy === false.
Webhooks
Paystack events are accepted at POST /api/v1/treasury/webhook (alias /api/v1/payments/webhook). The raw request bytes are captured before JSON parsing and verified with HMAC SHA-512 using the Paystack secret key.
- Required header:
x-paystack-signature. - Comparison is constant-time (
crypto.timingSafeEqual). - Missing signature →
401; invalid signature →401; processing failure →503so Paystack retries. - Payment claims are idempotent: the reference is claimed before fulfilment and released on failure.
Client guidance
There is no published SDK package in this repository. Use fetch, curl, or your language's HTTP client against the JSON contract. The reference patterns below are the supported integration shapes.
| Concern | Do | Do not |
|---|---|---|
| Sessions | Store cookies with credentials: 'include'; let the browser manage HttpOnly tokens. | Read access_token in JavaScript or persist it in localStorage. |
| CSRF | Fetch /auth/csrf and echo X-CSRF-Token. | Disable the header for cookie-auth writes. |
| Retries | Retry 429/503 with exponential backoff and jitter; honour Retry-After. | Retry 4xx validation errors unchanged. |
| Webhooks | Verify the raw-body signature before parsing business logic. | Trust an unsigned event or a client-supplied amount. |
| Versioning | Pin /v1; tolerate additive fields. | Scrape HTML for data that the API already exposes. |
Changelog
| Date | Version | Change |
|---|---|---|
| 2026-11-15 | 8.0.0 | Published this developer interface; documented the v1 route table, health probe fields, rate limits, CSRF double-submit and webhook verification. Added the brand runtime and standards layer to all pages. |
| 2026-11-11 | 7.x | Canonical SEO baseline; 58 pages with canonical/OG/Twitter URLs; 48 sitemap URLs; lint clean. |
| 2026-10-13 | 6.x | Vercel publish root moved to public/; legacy import retained read-only. |
Support and disclosure
Integration support: info@intelliaigroup.co.za. Security reports: see Security → Disclosure and /.well-known/security.txt.
IntelliAI Group (Pty) Ltd · CIPC 2026/429045/07 · South Africa. This page documents the deployed contract; it is not a promise of future features.