Skip to content
INTELLIAIGROUPDETERMINISTIC SOVEREIGN AI
Platform documentation · API v1

Developer interface

A versioned JSON interface for identity, treasury, inference and operational telemetry. This page documents the contract that is actually deployed: 40 routes under /api/v1, HttpOnly cookie sessions, CSRF double-submit and verified Paystack webhooks.

● API v1 live Base URL /api/v1 JSON · 16 KB body limit Last verified 2026-11-15

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.

PropertyValue
TransportHTTPS only in production; HSTS max-age=31536000; includeSubDomains; preload
Content typeapplication/json; charset=utf-8
Request body limit16 KB (413 PAYLOAD_TOO_LARGE)
Cachingprivate, no-store on every /api response
CORShttps://www.intelliaigroup.co.za and https://intelliaigroup.co.za, credentials enabled
General rate limit100 requests / minute / client on /api/
Zero invented endpoints. Every route on this page exists in 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

shellunauthenticated
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

shellcookie jar
curl -s -c cookies.txt \
  https://www.intelliaigroup.co.za/api/v1/auth/csrf | jq '.data.csrfToken'

3. Sign in

shellsets HttpOnly cookies
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

shellcookie auth
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.
MethodPathAuthPurpose
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/setupCookie + CSRFStarts TOTP enrolment; returns the provisioning URI/secret.
POST/auth/mfa/verifyCookie + CSRFVerifies a TOTP code and activates MFA.
POST/auth/mfa/disableCookie + CSRFDisables MFA after re-authentication.
POST/auth/change-passwordCookie + CSRFChanges the password; rate-limited 5/min.
POST/auth/refreshRefresh cookieRotates the session and issues a new access token.
POST/auth/logoutOptionalDeletes the session row and clears both cookies.
GET/auth/verify-emailTokenConsumes 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-passwordTokenConsumes a 64-hex reset token and sets a new password; 5/15 min.
GET/users/meSessionReturns the current profile.
PUT/users/meSession + CSRFUpdates the profile. Bearer callers are CSRF-exempt.
MFA is TOTP. The v1 contract exposes TOTP enrolment and challenge routes. Do not assume WebAuthn/passkey routes are available in this build; they are not part of the v1 route table.

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"
  }
}
HTTPCodeMeaning
400INVALID_JSONBody is not parseable JSON.
400VALIDATION_ERRORA field failed schema validation; the message names the field.
401UNAUTHORIZEDMissing, expired or invalid credentials.
403CSRF_REJECTEDCookie-authenticated state change without a matching X-CSRF-Token.
413PAYLOAD_TOO_LARGEBody exceeds 16 KB.
429RATE_LIMITEDPer-route limiter exceeded; inspect RateLimit-* headers.
500INTERNAL_ERRORUnexpected fault. A correlation id is written to the server log.
503CONFIG_REQUIREDA 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.

ScopeLimitWindow
All /api/ traffic1001 minute
/auth/login, /auth/mfa/challenge, /auth/change-password51 minute
/auth/register515 minutes
/auth/forgot-password31 hour
/auth/reset-password515 minutes
/contact51 minute
/tickets101 minute
/newsletter101 minute
/gpu/chat101 minute

Endpoint catalogue

Treasury and billing

MethodPathAuthPurpose
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/checkoutSessionInitialises a Paystack checkout. Alias: /payments/initialize.
GET/treasury/subscriptionSessionCurrent subscription and renewal state.
GET/treasury/invoicesSessionInvoice list for the authenticated account.
GET/treasury/invoices/:id/pdfSessionInvoice PDF stream.
GET/treasury/transactionsSessionTransaction history.
GET/treasury/receipts/:referenceSessionReceipt for a payment reference.
GET/treasury/billing-settingsSessionBilling profile and preferences.
PUT/treasury/billing-settingsSession + CSRFUpdates billing profile.
POST/treasury/webhookHMACPaystack webhook. Alias: /payments/webhook.

Inference and GPU

MethodPathAuthPurpose
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

MethodPathAuthPurpose
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/contextOptionalRecords 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

MethodPathAuthPurpose
GET/health—Dependency-aware health probe; drives the status page.
POST/contact—Contact form. Requires consent: true; 5/min.
POST/ticketsOptionalSupport 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".

FieldMeaning
data.statusok when the database probe succeeds; otherwise degraded.
data.checks.databaseok or fail from a live query.
data.checks.paystackok or fail based on key-mode configuration.
data.checks.gpuok or offline; a GPU outage does not fail the platform health by itself.
data.database.latencyMsMeasured round-trip to the database probe.
data.paystack.configuredModetest unless live mode is explicitly enabled.
data.timestampISO-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 → 503 so Paystack retries.
  • Payment claims are idempotent: the reference is claimed before fulfilment and released on failure.
Never re-serialise the body. Verify against the exact bytes received. A parsed-then-stringified body will not match the signature.

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.

ConcernDoDo not
SessionsStore cookies with credentials: 'include'; let the browser manage HttpOnly tokens.Read access_token in JavaScript or persist it in localStorage.
CSRFFetch /auth/csrf and echo X-CSRF-Token.Disable the header for cookie-auth writes.
RetriesRetry 429/503 with exponential backoff and jitter; honour Retry-After.Retry 4xx validation errors unchanged.
WebhooksVerify the raw-body signature before parsing business logic.Trust an unsigned event or a client-supplied amount.
VersioningPin /v1; tolerate additive fields.Scrape HTML for data that the API already exposes.

Changelog

DateVersionChange
2026-11-158.0.0Published 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-117.xCanonical SEO baseline; 58 pages with canonical/OG/Twitter URLs; 48 sitemap URLs; lint clean.
2026-10-136.xVercel 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.