REST API Reference
Complete endpoint specification, parameters, and response schemas for the GNS REST API.
GNS REST API Reference
All requests to the GNS API are served over HTTPS and expect/return JSON payloads.
- Production Base URL:
https://api.gns.iitdeveloper.com - Current API Version:
v1(/api/v1/...) - OpenAPI Schema: Statically exported at
/content/openapi.json(85 paths)
Global Headers
| Header | Required | Example / Format | Description |
|---|---|---|---|
Authorization | Yes | Bearer gns_live_sk_... | Application secret key or Keycloak JWT. |
Content-Type | Yes (for POST/PATCH) | application/json | Request payload format. |
Idempotency-Key | Optional | 9b1deb4d-3b7d-4bad-... | Prevents duplicate sends on network retries. |
Core Notification Endpoints
1. Dispatch Notification
POST /api/v1/notifications
Dispatches a notification across email, SMS, WhatsApp, or in-app channels.
Request Body Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
channel | string | Yes | Destination channel: email, sms, whatsapp, in_app. |
recipient | string | Yes | Target email address, E.164 phone number, or user ID. |
subject | string | Optional | Subject line (used for email and in-app). |
body | string | Yes | Plaintext message body. |
html_body | string | Optional | Formatted HTML content (for email). |
template_id | string | Optional | Stored template identifier. |
template_data | object | Optional | Key-value pairs interpolated into template placeholders. |
{
"status": "accepted",
"notification_id": "notif_01J7K3X9AB0C1D2E",
"channel": "email",
"delivery_status": "queued"
}Transactional OTP Endpoints
2. Send OTP Code
POST /api/v1/otp/send
Generates and delivers a cryptographically secure one-time password.
Request Body Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
channel | string | Yes | email or sms. |
recipient | string | Yes | Target recipient. |
length | integer | Optional | Number of digits (default: 6, options: 4 or 6). |
ttl_seconds | integer | Optional | Time before expiry (default: 300). |
code | string | Optional | Caller-provided custom code (requires otp:custom_code permission). |
{
"status": "sent",
"transaction_id": "otp_01J7M5QW8B9C0D1E",
"expires_in_seconds": 300
}3. Verify OTP Code
POST /api/v1/otp/verify
Validates a user-submitted code against an active session.
{
"status": "verified",
"transaction_id": "otp_01J7M5QW8B9C0D1E",
"verified_at": "2026-09-13T13:30:00Z"
}Custom Sending Domain Endpoints
4. List Verified Domains
GET /api/v1/domains
Returns all custom sending domains configured for the current tenant.
5. Add Custom Domain
POST /api/v1/domains
Registers a new sending domain and generates DNS challenge tokens.
6. Verify Domain DNS Records
POST /api/v1/domains/{domain_id}/verify
Triggers immediate DNS resolution checks for SPF and DKIM.
Delivery Activity Endpoints
7. Query Activity Feed
GET /api/v1/activity
Queries the paginated, masked delivery timeline across all applications and channels.
8. Retry Delivery
POST /api/v1/activity/{id}/retry
Re-enqueues a previously failed dispatch for execution.