telecom-platform/docs/API.md

TaaS Platform API Documentation

Overview

The TaaS Platform provides a RESTful API for managing cellular connectivity programmatically. All API endpoints are available at https://api.taas-platform.com/v1 (production) or http://localhost:8000/v1 (development).

Authentication

All API requests require authentication using Bearer tokens:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.taas-platform.com/v1/esims

Get your API key from the Developer Dashboard.

Endpoints

Health Check

GET /health

Check API server status.

Response:

{
  "status": "healthy",
  "service": "api-server",
  "timestamp": 1711929600
}

Create eSIM

POST /v1/esims

Provision a new eSIM with cellular connectivity.

Request:

{
  "data_plan": "1GB",
  "country_code": "US",
  "carrier": "optional-carrier-name"
}

Response:

{
  "esim_id": "550e8400-e29b-41d4-a716-446655440000",
  "imsi": "208930000000001",
  "iccid": "8933123456789012345",
  "activation_code": "LPA:1$smdp.example.com$MATCHING_ID",
  "status": "provisioned",
  "data_plan": "1GB",
  "country_code": "US",
  "created_at": "2026-04-01T12:00:00Z"
}

Get eSIM Details

GET /v1/esims/:id

Retrieve information about a specific eSIM.

Response:

{
  "esim_id": "550e8400-e29b-41d4-a716-446655440000",
  "imsi": "208930000000001",
  "iccid": "8933123456789012345",
  "status": "active",
  "data_plan": "1GB",
  "created_at": "2026-04-01T12:00:00Z"
}

Get eSIM Usage

GET /v1/esims/:id/usage

Get data usage statistics for an eSIM.

Response:

{
  "esim_id": "550e8400-e29b-41d4-a716-446655440000",
  "data_used": 262144000,
  "data_limit": 1073741824,
  "sessions": [
    {
      "started_at": "2026-04-01T10:00:00Z",
      "ended_at": "2026-04-01T11:00:00Z",
      "bytes_up": 10485760,
      "bytes_down": 52428800
    }
  ],
  "updated_at": "2026-04-01T12:00:00Z"
}

Terminate eSIM

DELETE /v1/esims/:id

Permanently terminate an eSIM.

Response:

{
  "message": "eSIM terminated successfully",
  "esim_id": "550e8400-e29b-41d4-a716-446655440000"
}

Status Codes

• 200 OK - Request successful
• 201 Created - Resource created
• 400 Bad Request - Invalid request parameters
• 401 Unauthorized - Missing or invalid authentication
• 404 Not Found - Resource not found
• 500 Internal Server Error - Server error

Rate Limits

• Free Tier: 100 requests/hour
• Pro Tier: 10,000 requests/hour
• Enterprise: Unlimited

Rate limit headers are included in all responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1711933200

SDKs

TypeScript/JavaScript

npm install @taas-platform/sdk

import { TaasClient } from '@taas-platform/sdk';

const client = new TaasClient({ apiKey: 'YOUR_API_KEY' });

// Create eSIM
const esim = await client.esims.create({
  dataPlan: '1GB',
  countryCode: 'US'
});

// Get usage
const usage = await client.esims.getUsage(esim.esimId);

Go

go get github.com/taas-platform/sdk-go

import "github.com/taas-platform/sdk-go"

client := taas.NewClient("YOUR_API_KEY")

// Create eSIM
esim, err := client.ESims.Create(&taas.CreateESIMRequest{
    DataPlan:    "1GB",
    CountryCode: "US",
})

Webhooks

Configure webhooks to receive real-time notifications:

Events

• esim.created - New eSIM provisioned
• esim.activated - eSIM activated on device
• usage.threshold - Data usage threshold reached (50%, 75%, 90%)
• usage.depleted - Data plan exhausted
• esim.terminated - eSIM terminated

Webhook Payload

{
  "event": "usage.threshold",
  "timestamp": "2026-04-01T12:00:00Z",
  "data": {
    "esim_id": "550e8400-e29b-41d4-a716-446655440000",
    "threshold": 75,
    "data_used": 805306368,
    "data_limit": 1073741824
  }
}

Examples

Create and Activate eSIM

# 1. Create eSIM
curl -X POST https://api.taas-platform.com/v1/esims \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data_plan": "1GB",
    "country_code": "US"
  }'

# 2. Show QR code to user (activation_code)
# User scans QR code on their device

# 3. Monitor usage
curl https://api.taas-platform.com/v1/esims/ESIM_ID/usage \
  -H "Authorization: Bearer YOUR_API_KEY"

Support

• Documentation: https://docs.taas-platform.com
• API Status: https://status.taas-platform.com
• Support Email: [email protected]
• GitHub Issues: https://github.com/nutcas3/telecom-platform/issues