Copy page

API Catalogue

Explore our APIs. Pick a card to open the full reference.

Tip: You can authorize requests using the top-right login and your tenant will be applied automatically.

Overview

The Tech231 Platform exposes multiple APIs for managing USSD applications, SMS messaging, and related services. All APIs follow REST conventions and use JSON for request/response payloads.

API Services

• SMS API - Manage SMS messaging, sender IDs, and message delivery
• USSD API - Deploy and manage USSD applications, handle session execution
• Auth API - (Reference only) Multi-tenant authentication and authorization via Zitadel OIDC

---

SMS API

Base URL: https://sms.tech231apps.net/api/v2

Documentation: See sms-api.json for full OpenAPI specification

Endpoints by Category

SMS Management

• POST /sms - Send SMS message
• GET /sms/{messageId} - Get message status
• DELETE /sms/{messageId} - Cancel pending message

Sender ID Management

• GET /senderid - List sender IDs for tenant
• POST /senderid - Register new sender ID
• PATCH /senderid/{senderId} - Update sender ID
• DELETE /senderid/{senderId} - Deactivate sender ID

Message Templates

• GET /templates - List message templates
• POST /templates - Create template
• PUT /templates/{templateId} - Update template
• DELETE /templates/{templateId} - Delete template

Reporting & Analytics

• GET /reports/delivery-status - Delivery status report
• GET /reports/cost-analysis - Cost analysis by sender/destination
• GET /reports/compliance - Compliance and regulatory report

---

USSD API

Base URL: https://api.tech231.com/api/ussd

Documentation: See ussd-api.json for full OpenAPI specification

Endpoints by Category

Application Deployment (Deployment Service)

• POST /deploy - Deploy new USSD application from DSL
• PUT /deploy/{applicationName} - Update deployed USSD application
• DELETE /deploy/{applicationName} - Undeploy application
• GET /deploy/{applicationName} - Get application definition and metadata

Session Execution (Execution Service)

• POST /session - Start new USSD session
• POST /session/{sessionId}/input - Send user input to session
• GET /session/{sessionId} - Get current session state
• DELETE /session/{sessionId} - Terminate session

Monitoring & Observability (Monitoring Service)

• GET /health - Service health status
• GET /metrics - Prometheus-format metrics (OpenTelemetry)
• GET /logs - Structured logs (if enabled)

---

USSD DSL (Domain-Specific Language)

The USSD API accepts application definitions in HCL-like DSL format.

DSL Structure Overview

Code
app "ApplicationName" {
  shortcode = "*123#"
  version   = "1.0.0"
  start     = "MainMenu"

  menu "MainMenu" {
    text = "Select an option:"
    option "1" {
      label = "Check Balance"
      goto  = "BalanceMenu"
    }
    option "2" {
      label = "Buy Airtime"
      goto  = "AirtimeMenu"
    }
  }

  menu "BalanceMenu" {
    text = "Your balance is: {{response.balance}}"
    option "0" {
      label = "Back"
      goto  = "MainMenu"
    }
  }

  action "BalanceCheck" {
    type = "http_call"
    url  = "https://backend.example.com/api/balance"
    method = "GET"
    headers = {
      Authorization = "Bearer {{session.auth_token}}"
    }
  }
}

Terminal Search Example

New in v2.1 — Use terminal menus for search results and one-time displays.

Code
app "UserSearch" {
  shortcode = "*123*5#"
  version   = "2.1.0"
  start     = "SearchInput"

  options {
    http_base_url = "https://api.example.com"
    global_actions {
      back_key = "0"
      home_key = "99"
    }
  }

  menu "SearchInput" {
    text = "Enter phone number to search:"
    option "*" {
      label = "Search"
      goto  = "PerformSearch"
    }
  }

  action "PerformSearch" {
    type       = "http_call"
    url        = "/users/search?phone={{session.input}}"
    on_success = "SearchResult"
    on_error   = "SearchError"
  }

  menu "SearchResult" {
    text = "User Found:\nName: {{response.name}}\nStatus: {{response.status}}\nRegistered: {{response.registered_at}}"
    # No options = terminal menu, session ends after displaying
  }

  menu "SearchError" {
    text = "Search failed: {{response.error}}\nPlease try again later."
    terminal = true  # Explicit terminal flag
  }
}

See USSD DSL Guide for full specification.

---

Authentication & Authorization

All APIs require authentication via OAuth 2.0 (OIDC) with Zitadel.

Request Headers

Code
Authorization: Bearer <jwt_token>
X-Tenant-ID: <tenant-id>  (optional, extracted from JWT claims if not provided)

JWT Token Structure

The token includes standard claims:

• sub - Subject (user ID)
• org_id or tenant_id - Organization/Tenant ID
• roles - User roles for authorization
• iat - Issued at
• exp - Expiration time

---

Error Handling

All APIs follow a consistent error response format:

Code
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      "field": "Additional context (optional)"
    }
  }
}

Common Error Codes

• UNAUTHORIZED - Missing or invalid authentication
• FORBIDDEN - User lacks required permissions
• NOT_FOUND - Resource not found
• INVALID_INPUT - Malformed request or invalid data
• CONFLICT - Resource already exists or state conflict
• INTERNAL_ERROR - Server error

---

Rate Limiting

APIs implement rate limiting per tenant and API key:

• SMS API: 1000 requests per minute
• USSD API: 100 requests per minute

Rate limit status is included in response headers:

Code
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1635360000

---

Webhooks & Callbacks

SMS Delivery Callbacks

POST to your configured webhook URL when SMS delivery status changes:

Code
{
  "messageId": "msg_123abc",
  "status": "delivered",
  "timestamp": "2025-11-25T10:30:45Z",
  "cost": 0.05
}

USSD Session Callbacks (Optional)

If configured, notifications are sent at key session events:

• Session started
• Session terminated (with reason: completed, abandoned, timeout)
• Action execution result

---

SDK & Client Libraries

Official client libraries are available for:

• Node.js/TypeScript - @tech231/platform-sdk
• Python - tech231-platform-sdk
• .NET - Tech231.Platform.SDK
• Go - github.com/tech231/platform-sdk-go

See SDK Documentation for usage examples.

---

Versioning

APIs use semantic versioning. The current version is v1.

• Breaking changes → Major version bump (v1 → v2)
• New features → Minor version bump (v1.0 → v1.1)
• Bug fixes → Patch version bump (v1.0.0 → v1.0.1)

The version is specified in the Base URL: /api/sms/v1/...

---

Support & Issues

For API issues, feature requests, or documentation corrections:

• GitHub Issues: tech231/platform
• Email: api-support@tech231.com
• Slack: #api-support (internal)

---

See Also

• SMS API Full Spec
• USSD API Full Spec
• USSD DSL Guide
• Integration Guides
• Getting Started