REST API

The REST API service provides HTTP endpoints for account management, device registration, language listing, and Twilio video integration for the Sanas Translate platform.

Base URL

https://api.sanaslt.com/v2

Authentication

All /v2/* endpoints require authentication via one of:

Method	Header	Value
JWT Bearer	`Authorization`	`Bearer <jwt_token>`
API Key	`x-api-key`	`<api_key>`

JWT tokens are issued by Supabase and validated using HS256 (shared secret) or ES256 (JWKS). The aud claim must be authenticated. On authentication failure, the server returns HTTP 401:

{
  "success": false,
  "error": {
    "code": 1002,
    "message": "Unauthorized"
  }
}

Response Format

All v2 endpoints return JSON in a standard envelope. Success (HTTP 200):

{
  "success": true,
  "data": { ... }
}

Error:

{
  "success": false,
  "error": {
    "code": 1100,
    "message": "Bad request",
    "data": null
  }
}

The HTTP status code matches the error type (400, 401, 404, 500, etc.).

Common Headers

Optional headers that some endpoints use for localization:

Header	Default	Description
`x-lang`	`en-US`	Locale for localized responses (e.g., `es-ES`, `fr-FR`)
`x-version`	(none)	Client app version
`x-platform`	(none)	Client platform (`ios`, `android`, `web`)

Endpoints

Health Check

GET /health

No authentication required. Returns service health status. Response:

{
  "status": "healthy",
  "service": "api"
}

Error Codes

GET /v2/errors

Returns the complete error code catalog for client-side error handling. Response:

{
  "success": true,
  "data": [
    {
      "name": "NO_TOKEN_PROVIDED",
      "code": 1000,
      "message": "No token provided",
      "http_status": 401
    },
    ...
  ]
}

Error code ranges:

Range	Category
1000-1099	Authentication errors
1100-1199	Request validation errors
1200-1299	Language errors
1300-1399	Resource errors
1400-1499	Session errors
1500-1599	Rate limiting
1900-1999	Server errors
2000-2099	Device management errors
2100-2199	Twilio errors
2200-2299	Account management errors
2400-2499	Languages mobile errors

Languages

GET  /v2/languages/list
POST /v2/languages/list

Returns the available language list with names localized to the x-lang header value. Supports both GET and POST. Request headers:

Header	Required	Description
`x-lang`	No	Locale for language name localization (default: `en-US`)

Response:

{
  "success": true,
  "data": {
    "languages": [
      {
        "code": "en-US",
        "name": "English",
        "native_name": "English"
      },
      {
        "code": "es-ES",
        "name": "Spanish",
        "native_name": "Espanol"
      }
    ]
  }
}

Cache headers:

Cache-Control: public, max-age=86400, stale-while-revalidate=3600
Vary: x-lang, Accept-Encoding

CloudFront caches one entry per x-lang value. First request per locale hits origin; subsequent requests are served from edge cache.

Languages (Mobile)

GET  /v2/languages-mobile/list
POST /v2/languages-mobile/list

Returns the language list enriched with mobile-specific fields (listening_text, ready_text). Response:

{
  "success": true,
  "data": {
    "languages": [
      {
        "code": "en-US",
        "name": "English",
        "native_name": "English",
        "listening_text": "Listening...",
        "ready_text": "Ready to translate"
      }
    ]
  }
}

Same cache headers as the standard languages endpoint.

Device Registration

POST /v2/device/register
Content-Type: application/json

Registers or updates a mobile device for push notifications. Request body:

{
  "device_name": "iPhone 15",
  "device_platform": "ios",
  "push_token": "abc123..."
}

Field	Type	Values	Description
`device_name`	string		Human-readable device name
`device_platform`	string	`ios`, `android`	Device platform
`push_token`	string		Push notification token

Response:

{
  "success": true,
  "data": {
    "id": "device-uuid",
    "device_platform": "ios",
    "device_name": "iPhone 15",
    "is_active": true
  }
}

Device Deactivation

POST /v2/device/deactivate
Content-Type: application/json

Deactivates a registered mobile device. Request body:

{
  "push_token": "abc123..."
}

Response:

{
  "success": true,
  "data": {
    "id": "device-uuid",
    "is_active": false
  }
}

Twilio Video Token

POST /v2/twilio/token/create
Content-Type: application/json

Creates a Twilio access token for joining a video room. Verifies the room exists and is in-progress before issuing the token. Request body:

{
  "room_name": "1234567890"
}

Response:

{
  "success": true,
  "data": {
    "token": "<twilio_jwt_token>"
  }
}

Errors:

404 (code 2102): Room not found or not in-progress
500 (code 2100): Token creation failure

Twilio Video Room

POST /v2/twilio/room/create

Creates a new Twilio video room. No request body required. Response:

{
  "success": true,
  "data": {
    "room_name": "1234567890",
    "status": "in-progress",
    "max_participant_duration": 3600
  }
}

Room properties:

Type: group
Max participants: 2
Max participant duration: 3600 seconds
Unused room timeout: 1 minute

Account: Opt In

POST /v2/account/opt-in

Opts the authenticated user in to data sharing. No request body required. Response:

{
  "success": true,
  "data": {}
}

Account: Opt Out

POST /v2/account/opt-out

Opts the authenticated user out of data sharing. No request body required. Response:

{
  "success": true,
  "data": {}
}

Account: Check Opted Out

POST /v2/account/check-opted-out

Returns the user’s current data sharing opt-out status. No request body required. Response:

{
  "success": true,
  "data": {
    "opted_out": false
  }
}

Account: Query

POST /v2/account/query

Returns the authenticated user’s account details. No request body required. Response:

{
  "success": true,
  "data": {
    "id": "user-uuid",
    "opted_out": false,
    "privacy_agreed": true,
    "onboard_finished": true,
    "my_lang": "en-US",
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-06-01T00:00:00Z"
  }
}

Account: Update Privacy Agreed

POST /v2/account/privacy-agreed/update
Content-Type: application/json

Updates the authenticated user’s privacy agreement status. Request body:

{
  "privacy_agreed": true
}

Response:

{
  "success": true,
  "data": {}
}

Account: Update Onboarding

POST /v2/account/onboard/update
Content-Type: application/json

Marks onboarding as finished and sets the user’s preferred language. Request body:

{
  "my_lang": "es-ES"
}

Response:

{
  "success": true,
  "data": {}
}

Account: Delete

POST /v2/account/delete

Permanently deletes the authenticated user’s account and associated data. This includes:

Supabase auth user deletion
PostHog person cleanup (best-effort)
S3 file cleanup (best-effort)

Cleanup failures for PostHog and S3 are logged but do not cause the request to fail. Response:

{
  "success": true,
  "data": {}
}

Errors:

404 (code 2204): User not found in Supabase auth
500 (code 2203): Deletion failure

Service Configuration

The API service is configured via environment variables. See services/api/AGENTS.md for the complete list. Key variables:

SUPABASE_URL, SUPABASE_JWT_SECRET, SUPABASE_SERVICE_ROLE_KEY for Supabase integration
TWILIO_ACCOUNT_SID, TWILIO_API_KEY, TWILIO_API_SECRET for Twilio video
GATEWAY_API_KEYS for API key authentication
LANGUAGES_CONFIG_PATH for language list configuration

Getting Started

Models

Deployment

Tutorials/Examples

Enterprise

Resources

Base URL

Authentication

Response Format

Common Headers

Endpoints

Health Check

Error Codes

Languages

Languages (Mobile)

Device Registration

Device Deactivation

Twilio Video Token

Twilio Video Room

Account: Opt In

Account: Opt Out

Account: Check Opted Out

Account: Query

Account: Update Privacy Agreed

Account: Update Onboarding

Account: Delete

Service Configuration

​Base URL

​Authentication

​Response Format

​Common Headers

​Endpoints

​Health Check

​Error Codes

​Languages

​Languages (Mobile)

​Device Registration

​Device Deactivation

​Twilio Video Token

​Twilio Video Room

​Account: Opt In

​Account: Opt Out

​Account: Check Opted Out

​Account: Query

​Account: Update Privacy Agreed

​Account: Update Onboarding

​Account: Delete

​Service Configuration

Base URL

Authentication

Response Format

Common Headers

Endpoints

Health Check

Error Codes

Languages

Languages (Mobile)

Device Registration

Device Deactivation

Twilio Video Token

Twilio Video Room

Account: Opt In

Account: Opt Out

Account: Check Opted Out

Account: Query

Account: Update Privacy Agreed

Account: Update Onboarding

Account: Delete

Service Configuration