Pinnacle API Documentation Portal

Complete application and feature reference
Last updated: 27 August 2026

1. Overview

The Pinnacle API Documentation Portal is a Node.js, Express, EJS, and PostgreSQL application for publishing, governing, searching, testing, and distributing versioned communication APIs.

It combines:

• A public API discovery portal
• Versioned endpoint documentation
• Code samples, simulators, mock APIs, exports, and SDKs
• Organisation registration, OTP verification, login, and password recovery
• Role-based administration and content governance
• Virtual and actual SMS/email delivery
• Media, contacts, analytics, auditing, themes, and operational health
• JSON catalog and MCP interfaces
• Automated unit, security, accessibility, and browser testing

2. Users and roles

Public developers

Developers discover products and endpoints, inspect authentication and schemas, search documentation, simulate supported payloads, compare versions, copy examples, and download integration assets.

Organisation administrators

Organisation administrators register, verify a mobile number by OTP, sign in, recover forgotten passwords, access the organisation account, and sign out.

Super Admin

Super Admins manage all content, users, organisations, themes, delivery providers, publishing, revision restoration, audits, and system configuration.

Editor

Editors manage assigned products, versions, endpoints, imports, drafts, media, contacts, and review activity. Product assignments restrict their access.

Viewer

Viewer accounts have read-oriented Admin access and cannot perform editor or Super Admin mutations.

Coding agents

MCP-compatible agents use the read-only /mcp interface to discover and search published API documentation.

3. Architecture

SQL migrations are idempotent. PostgreSQL stores products, documentation, users, organisations, OTP challenges, workflows, media metadata, analytics, contacts, delivery settings, and audit history.

4. API products

The catalog currently contains:

1. WhatsApp
2. SMS
3. RCS
4. Voice
5. Email
6. Customer Data Platform

Products are database-driven and can store a name, slug, summary, Markdown description, base URL, SVG icon, display order, homepage visibility, accent colour, Coming Soon status, versions, and endpoints. All presentation controls are editable in Admin. Hidden products remain available through direct documentation URLs; Coming Soon cards are marked and do not link into unfinished documentation.

5. Public homepage

The API Reference homepage includes:

• Pinnacle and 1SPOC branding
• Database-driven Channel API cards
• Links to the latest available product versions
• Compact icon-and-name card design
• Developer tooling and workflow overviews
• Login or organisation-account navigation
• Product Guide and Contact links
• Global API Search
• Full-height page layout with footer at the bottom
• Homepage language tabs with PHP before cURL and cURL last

6. Product, version, and endpoint documentation

Product pages

Product pages introduce a product and link to its available API versions.

Version pages

Version pages provide lifecycle information, categories, endpoint counts, endpoint search, HTTP-method filters, grouped navigation, OpenAPI/Postman/SDK downloads, and version comparison. Versions are labelled Current, Beta, Deprecated, or Retired. Admin can configure lifecycle dates and a recommended migration version. Deprecated and Retired version pages show a prominent notice, sunset information when available, and a migration link.

API detail pages

Endpoint pages can display:

• Breadcrumbs and product/version/category context
• HTTP method, base URL, path, and copyable request URL
• Overview and purpose
• Deprecated or Retired notices with sunset dates and migration links inherited from the version
• Authentication location and field name
• Path and query parameters
• Request-body fields
• Request example/schema tabs
• Code examples
• Response example/schema tabs
• Status codes
• Previous and Next endpoint navigation
• WhatsApp or RCS simulation where supported

All major sections use a shared padded card treatment.

7. Global API Search

Global API Search is available site-wide through the floating Search APIs control and Ctrl/Cmd + K.

It searches:

• Products and versions
• Endpoint names, paths, methods, and categories
• Purpose text and authentication field names
• Request/response schemas and examples
• Payload fields

It includes live database results, type/product/method filters, match highlighting, Arrow-key navigation, Enter to open, Escape to close, responsive layout, and loading/empty/error states. A full results page remains available at /search. Search intentionally stays out of the top bar.

8. Code examples

Generated examples support:

• cURL
• JavaScript
• Node.js
• Python
• Java
• PHP
• C#
• Go

Features include JetBrains Mono, syntax highlighting, language tabs, remembered selection, copy confirmation, full-screen mode, request-URL customization, responsive controls, and SDK download.

Samples preserve <API_KEY> or <ACCESS_TOKEN> placeholders. Live credentials cannot be entered into or rendered by the code-sample component.

9. JSON documentation and editors

Request/response panels include Example and Schema tabs, copy actions, formatted JSON, JetBrains Mono, and responsive overflow.

WhatsApp and RCS simulation editors add:

• Line numbers with synchronized scrolling
• Matching font metrics and padding
• Live validation
• Error line and column reporting
• Invalid-state highlighting
• Format JSON and Restore Example
• Tab/Shift+Tab indentation
• Submission blocking for invalid JSON

10. WhatsApp simulator

Supported endpoints offer a local iPhone-style preview with sample WABA credentials and editable JSON. Payload rendering supports text, image, video, document, audio, location, location requests, contacts, interactive content, catalogs, templates, and carousels where documented. No real WhatsApp API call is made.

11. RCS simulator

Supported RCS endpoints offer a local Android-style preview for text, rich cards, carousels, templates, media, and suggested actions. No real RCS provider call is made.

12. Interactive API console

The secure API-console backend:

• Builds requests only from published documentation
• Accepts documented path/query parameters, authentication, headers, and JSON bodies
• Never stores submitted credentials
• Blocks transport-controlled headers
• Rejects private, local, and loopback targets
• Rejects upstream redirects
• Enforces timeout and size limits
• Returns status, duration, headers, and body
• Applies rate limits

The endpoint template currently keeps the live console hidden through showLiveApiConsole = false; the backend is available for controlled enablement.

13. Mock server

The mock server provides method/path matching, path extraction, schema validation, request discriminators, documented examples, selectable status codes, simulated latency, CORS, analytics, and rate limiting.

/mock/:product/:version/*

14. Version comparison

Version comparison identifies added, removed, changed, and unchanged endpoints and fields to support migration planning.

15. OpenAPI, Postman, SDK, and catalog exports

OpenAPI

Published versions export OpenAPI 3.1 JSON and YAML.

Postman

The application exports importable Postman Collections and Environments without live credentials.

SDKs

Downloadable ZIP SDKs are generated for Node.js, Python, Java, PHP, C#, and Go. Archives include a reusable client, endpoint catalog, OpenAPI document, project metadata, and README.

JSON catalog

GET /api/catalog
GET /api/catalog/:product/:version
GET /api/catalog/:product/:version/:endpoint/examples

16. MCP interface

The read-only Streamable HTTP MCP endpoint is available at /mcp and supports:

• list_products
• list_versions
• list_endpoints
• get_endpoint
• search_api_docs

Only published documentation is exposed. Setup guidance is available at /mcp-setup.

17. Product Guide and Contact

The Product Guide explains platform products and integration capabilities.

The Contact form captures organisation details, website, contact information, phone numbers, GST number, and consent. It includes validation, normalization, duplicate protection, honeypot and timing checks, rate limiting, CSRF, optional Turnstile, and hashed IP storage. Submissions can be delivered by email and signed webhook.

Admin users can search/filter enquiries, view details, update lead status, inspect delivery state, and retry email or webhook delivery.

18. Organisation registration and account

Registration collects organisation name, administrator email, international mobile number, password, and confirmation. It creates inactive records and sends a six-digit OTP.

OTP controls:

• Ten-minute expiry
• Five incorrect attempts per challenge
• Transaction-safe verification
• Consumption of replaced, expired, or exhausted challenges
• HMAC-hashed OTP in the challenge table

Successful verification activates the organisation and administrator.

Organisation login includes bcrypt verification, active-status checks, failed-login counters, temporary lockout, session-version validation, and rate limiting.

Forgot Password sends an OTP to the registered mobile, verifies it, prevents password reuse, invalidates old sessions, and avoids disclosing whether an email exists.

19. Admin authentication

Admin authentication includes login, account lockout, rate limiting, role checks, session-version invalidation, Change Password, Sign Out, and email-based Forgot Password.

Admin reset links are random, hashed in storage, single-use, expiring, and protected against password reuse. Password-reset email is delivered through the configured Virtual or Actual Email sender.

20. Admin Home

Admin Home shows the Products and Organisations KPI cards, the product catalog, SVG icons, and role-appropriate navigation to platform operations.

21. Content management

Products

Super Admins manage name, slug, summary, description, base URL, SVG icon, conflicts, drafts, and audit history.

Versions

Authorized users create/edit/delete versions, set lifecycle status, release dates and notes, compare versions, import definitions, and manage drafts.

Endpoints

Endpoint authoring covers name, slug, category, purpose, method, path, authentication, request/response schemas and examples, status codes, publication, sorting, conflicts, drafts, and revisions.

22. API import

The Admin importer supports OpenAPI 3, Swagger 2, and Postman Collections in JSON/YAML as appropriate. It extracts and normalizes operations, schemas, categories, examples, and authentication and records import audit data.

23. Drafts & Reviews

The workflow at /admin/drafts_and_reviews supports:

• Save draft
• Submit for review
• Request changes with guidance
• Approve
• Publish
• Revision recording
• Current/proposed comparisons
• Activity history
• Restoration of published revisions
• Stale-save conflict protection
• Role and product-assignment enforcement

Legacy workflow URLs redirect to the current route.

24. Media Gallery

The Admin Media Gallery includes folders, multi-file upload, image/video/audio/document support, filtering, previews, public URLs, Copy URL, deletion, folder safety, size/MIME validation, and range delivery. Metadata is in PostgreSQL; objects use SeaweedFS by default or private S3.

25. Admin user and organisation management

Super Admins can list/create/edit/delete Admin users, assign roles, activate/deactivate accounts, reset passwords, and assign products to editors. Self-demotion, self-deactivation, and self-deletion protections apply.

The Organisations page supports search, active/pending/inactive filters, verification status, user counts, administrator email, and last-login visibility.

26. Application themes and typography

Super Admins apply database-stored application themes. Theme variables control public, organisation, and Admin surfaces, text, borders, accents, controls, and code areas, with safe fallback to the default theme.

Inter is the site-wide interface font. JetBrains Mono is used for code and structured technical editors. Material Symbols Rounded is used for icons.

See docs/DESIGN-GUIDELINES.md for detailed UI rules.

27. SMS delivery

Virtual SMS

Virtual SMS is the default. OTPs are stored in a Super Admin inbox showing recipient, purpose, message, OTP, time, read state, and expiry.

Actual SMS

Configuration includes Entity ID, Sender ID, SMS API URL, Template ID, and API Key. Requests use validated HTTP(S) URLs and timeouts.

Health

The SMS page reports virtual readiness, missing configuration, invalid URLs, actual-provider readiness, and checked time.

28. Email delivery

Virtual Email

Virtual Email is the default. Messages appear in the Super Admin inbox with recipient, subject, category, time, reply-to, and body.

Actual SMTP

Configuration includes From address, optional contact recipient, host, port, TLS selection, username, and password.

Actual Email API

Configuration includes From address, API URL, and API Key.

Health

The Email page reports virtual readiness, missing configuration, invalid URLs, Email API readiness, live SMTP connection verification, and checked time.

29. Credential encryption and secret protection

AES-256-GCM encryption protects SMS Entity ID, Sender ID, Template ID, SMS API Key, SMTP username/password, and Email API Key at rest.

Production requires CREDENTIAL_ENCRYPTION_KEY. Existing values can be migrated with:

npm.cmd run security:encrypt-credentials

Secret inputs remain blank in the browser. Logging recursively redacts passwords, OTPs, tokens, cookies, API keys, authorization values, Bearer tokens, URL-query secrets, and JSON secrets. Code samples retain placeholders only.

See docs/SECURITY-HARDENING.md for complete security details.

30. Analytics and auditing

Analytics includes total activity, endpoint views, downloads, mock requests, searches, daily trend, popular endpoints, language selections, exports, and search quality. Filters support product and date range.

Credentials, request bodies, and search text are not stored. Search analytics retains query length and result count only.

The audit log records authentication, user/content changes, workflow, publication/restoration, imports, delivery configuration, themes, media, and conflicts. Sensitive fields are excluded.

31. Editor Tutor

The Editor Tutor provides role-aware guidance for authorized content editors.

32. Security controls

• CSRF protection
• Signed sessions and secure production cookies
• Role and product authorization
• Session-version invalidation
• bcrypt passwords
• Login counters and temporary lockouts
• Rate limits for login, registration, OTP, password reset, API console, and simulation
• Hashed OTP challenges and reset tokens
• Content Security Policy and Helmet headers
• Request IDs
• API-console SSRF protections, redirect blocking, timeouts, and size limits
• AES-256-GCM provider credential encryption
• Recursive log and string redaction
• Generic password-recovery responses

Current rate limits are documented in docs/SECURITY-HARDENING.md.

33. Logging and health

Winston emits structured JSON logs with request ID, method, path without query string, status, duration, and safe user context. Optional Loki delivery is enabled only in production when configured. Logs are flushed during graceful shutdown.

GET /health verifies PostgreSQL connectivity. Provider readiness remains visible only to authenticated Super Admins on SMS/Email pages.

34. Accessibility and responsive UI

The application uses semantic landmarks, breadcrumbs, labels, accessible dialogs/buttons, visible focus states, live regions, keyboard search, contrast checking, and responsive touch targets.

Layouts adapt across desktop, laptop, tablet, and mobile using collapsing grids, scrollable tabs, stacked rows, viewport-safe dialogs, responsive simulators, and mobile code controls.

35. Automated tests

Unit and security suite:

npm.cmd test

Current baseline: 64 passing tests covering analytics, API-console safety, code generation, contacts, workflow, encryption, CSRF, search, redaction, media, mocks, OpenAPI, authentication, OTP, password reset, Postman, rate limiting, SDKs, themes, and comparisons.

Browser/accessibility/security suite:

npm.cmd run test:e2e

Current baseline: 5 passing Playwright tests covering global search, filtering/highlighting, credential placeholders, JSON validation, security headers, secret leakage, and Axe accessibility.

Focused commands:

npm.cmd run test:accessibility
npm.cmd run test:security

36. Local operation

npm.cmd install
docker compose up -d postgres seaweedfs-filer
npm.cmd run db:migrate
npm.cmd run db:seed-superadmin
npm.cmd run dev

Application: http://localhost:4001
Admin: http://localhost:4001/admin

Media migration:

npm.cmd run media:migrate-object-storage

37. Configuration groups

• Runtime: NODE_ENV, PORT, PUBLIC_BASE_URL, TRUST_PROXY
• Database: DATABASE_URL, DATABASE_SSL
• Security: SESSION_SECRET, CREDENTIAL_ENCRYPTION_KEY, OTP_SECRET, contact IP hash secret
• Super Admin bootstrap: identity settings and production password hash
• Media: provider, SeaweedFS, or S3 settings
• Contact: Turnstile and signed webhook configuration
• Observability: Loki URL, port, app, and service names

SMS and Email provider configuration is managed through Admin and encrypted in PostgreSQL.

38. Public route reference

39. Admin route reference

40. Related documentation and status

• README.md — repository introduction
• DEPLOYMENT.md — production deployment
• docs/SECURITY-HARDENING.md — security controls
• docs/DESIGN-GUIDELINES.md — UI and interaction rules
• docs/APPLICATION_DOCUMENTATION.md — this complete feature reference

Current verified state:

• Six database-backed API products
• Virtual SMS and Virtual Email defaults
• 64 unit/security tests passing
• Five browser/accessibility/security tests passing
• Security-hardening migration applied
• Health endpoint responding successfully on port 4001