API Reference

Integrate Interprivo real-time voice translation into your applications.

Base URL: https://interprivo.net
All responses: application/json
TLS required

Authentication

All API requests must include an Authorization header with a Bearer token. Generate API keys in Settings → Developer.

Authorization: Bearer ip_live_••••••••••••••••

# Keys are prefixed: ip_live_ (production) or ip_test_ (testing)
Rate limits: Authenticated API calls are limited to 100 req / min per API key. Responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.

Error Codes

HTTP StatuscodeMeaning
400BAD_REQUESTMissing or invalid request body / parameters
401UNAUTHORIZEDMissing or invalid API key / session token
403FORBIDDENAuthenticated but lacking required org role
404NOT_FOUNDResource does not exist or is not accessible
409CONFLICTResource state conflict (e.g. session already ended)
422UNPROCESSABLERequest understood but semantically invalid
429RATE_LIMITEDRate limit exceeded — back off and retry
500INTERNAL_ERRORServer-side failure — contact support
501NOT_IMPLEMENTEDFeature planned but not yet available
// Error response shape
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Retry after 30 seconds."
  }
}

Sessions

POST

/api/sessions

Create a new real-time translation session. Returns a LiveKit room token for WebRTC audio connection.

Request Body (JSON)

  • source_lang(string, required)— BCP-47 language code for the speaker (e.g. "en", "es-MX")
  • target_lang(string, required)— BCP-47 language code for the translation output
  • speaker_name(string, optional)— Display name shown in transcript (default: "Speaker")
  • organization_id(string, optional)— Target org if the user belongs to multiple organizations

Response

{
  "sessionId": "sess_01j9x...",
  "roomToken": "eyJ...",
  "liveKitUrl": "wss://your-project.livekit.cloud"
}

Each minute of real-time translation counts against your plan quota. Overage is metered via Stripe.

GET

/api/sessions

List sessions for the authenticated user's organization. Supports pagination.

Request Body (JSON)

  • limit(number, optional)— Max results to return (default 20, max 100)
  • offset(number, optional)— Offset for pagination (default 0)

Response

{
  "sessions": [
    {
      "id": "sess_01j9x...",
      "status": "completed",
      "source_lang": "en",
      "target_lang": "es",
      "started_at": "2026-04-11T14:00:00Z",
      "ended_at": "2026-04-11T14:22:00Z",
      "duration_seconds": 1320
    }
  ],
  "total": 42
}
GET

/api/sessions/:id/intelligence

Retrieve AI-generated intelligence for a completed session: sentiment, topics, action items, confidence metrics.

Path Parameters

  • id(string, required)— Session ID

Response

{
  "overallSentiment": "positive",
  "sentimentScore": 0.6,
  "extractedTopics": ["contract", "deadline", "friday"],
  "actionItems": ["Finalize the contract by Friday."],
  "urgencyLevel": "standard",
  "transcriptCount": 24,
  "speakerCount": 2,
  "averageConfidence": 0.94,
  "averageLatencyMs": 312,
  "durationSeconds": 1320
}
POST

/api/sessions/:id/phone/start

Initiate an outbound PSTN call for a live session via Vapi. Requires owner or admin role. Beta — API workflow only.

Path Parameters

  • id(string, required)— Active session ID

Request Body (JSON)

  • phoneNumber(string, required)— E.164 format (e.g. "+14155550199")
  • assistantId(string, optional)— Override the default Vapi assistant for this call

Response

{ "callId": "vapi_call_01j9x...", "status": "initiated" }

VAPI_API_KEY and VAPI_ASSISTANT_ID must be configured in environment variables.

POST

/api/sessions/:id/escalate

Escalate a live session to a human interpreter queue. Triggers Slack notification if configured.

Path Parameters

  • id(string, required)— Active session ID

Request Body (JSON)

  • reason(string, optional)— Escalation reason (stored in audit log)

Response

{ "escalationId": "esc_01j9x...", "queuePosition": 1 }

Active Session Management

GET

/api/sessions/active

List all currently active sessions in the authenticated user's organization.

Response

{
  "sessions": [
    {
      "id": "sess_01j9x...",
      "status": "active",
      "source_lang": "en",
      "target_lang": "fr",
      "started_at": "2026-04-11T14:00:00Z",
      "participants": [{ "user_id": "usr_...", "role": "member" }]
    }
  ]
}
POST

/api/sessions/:id/revoke/:participantId

Remove a participant from an active session. Requires owner or admin role. The participant is disconnected from the LiveKit room.

Path Parameters

  • id(string, required)— Session ID
  • participantId(string, required)— User ID of the participant to revoke

Response

{ "success": true }

Glossary

Custom glossary terms improve STT accuracy for industry-specific vocabulary (medical, legal, technical).

GET

/api/glossary

List all glossary terms for the authenticated organization.

Response

{
  "terms": [
    { "id": "gloss_01j9x...", "source_term": "myocardial", "target_term": "miocardial", "language_pair": "en-es" }
  ]
}
POST

/api/glossary

Create a new glossary term.

Request Body (JSON)

  • source_term(string, required)— Term in the source language
  • target_term(string, required)— Translation in the target language
  • language_pair(string, required)— BCP-47 pair (e.g. "en-es")

Response

{ "id": "gloss_01j9x...", "source_term": "myocardial", "target_term": "miocardial" }
PATCH

/api/glossary/:id

Update an existing glossary term.

Path Parameters

  • id(string, required)— Glossary term ID

Request Body (JSON)

  • source_term(string, optional)— Updated source term
  • target_term(string, optional)— Updated translation

Response

{ "id": "gloss_01j9x...", "source_term": "...", "target_term": "..." }
DELETE

/api/glossary/:id

Delete a glossary term.

Path Parameters

  • id(string, required)— Glossary term ID

Response

{ "success": true }
POST

/api/glossary/import

Bulk-import glossary terms from a CSV or TXT file. Max 5,000 rows, 1 MB. Requires admin or owner role.

Request Body (JSON)

  • file(File (multipart/form-data), required)— CSV with columns: source_term, target_term, language_pair

Response

{ "imported": 142, "skipped": 3, "errors": [] }

API Keys

GET

/api/api-keys

List all API keys for the authenticated organization (key values are masked after creation).

Response

{
  "keys": [
    { "id": "key_01j9x...", "name": "Production Key", "key_prefix": "ip_live_••••", "created_at": "2026-04-01T00:00:00Z", "last_used_at": null }
  ]
}
POST

/api/api-keys

Create a new API key. The full key value is returned only once — store it securely.

Request Body (JSON)

  • name(string, required)— Human-readable label (e.g. "Production Key")

Response

{ "id": "key_01j9x...", "name": "Production Key", "key": "ip_live_..." }

The key value is shown only at creation time. If lost, delete and create a new key.

POST

/api/api-keys/:id/rotate

Rotate an API key: invalidates the current key and returns a new one with the same name. Requires owner or admin role.

Path Parameters

  • id(string, required)— Key ID to rotate

Response

{ "id": "key_01j9x...", "name": "Production Key", "key": "ip_live_..." }
DELETE

/api/api-keys/:id

Revoke and permanently delete an API key. Any requests using this key will immediately return 401.

Path Parameters

  • id(string, required)— Key ID to delete

Response

{ "success": true }

Billing

GET

/api/billing/invoices

List up to 24 recent invoices for the organization. Requires owner or admin role.

Response

{
  "invoices": [
    {
      "id": "in_1...",
      "number": "INV-0001",
      "status": "paid",
      "amountPaid": 49.00,
      "currency": "USD",
      "createdAt": "2026-04-01T00:00:00Z",
      "hostedInvoiceUrl": "https://invoice.stripe.com/...",
      "invoicePdf": "https://pay.stripe.com/..."
    }
  ]
}

Webhooks (Inbound)

Interprivo accepts inbound webhooks from Stripe and Vapi. Configure the endpoints in each provider's dashboard.

EndpointProviderEvents handled
/api/webhooks/stripeStripecheckout.session.completed, invoice.payment_succeeded, invoice.payment_failed, customer.subscription.deleted, customer.subscription.updated
/api/webhooks/vapiVapicall-started, call-ended, transcript, hang (PSTN call lifecycle events)

Webhook security: Stripe uses signature verification via STRIPE_WEBHOOK_SECRET. Vapi uses a shared secret via VAPI_WEBHOOK_SECRET in the x-vapi-secret header.

Health

GET

/api/health

Basic liveness probe. Returns 200 when the service is running. No authentication required.

Response

{ "status": "ok", "version": "1.0.0", "timestamp": "2026-04-11T14:00:00Z" }
GET

/api/health/uptime

Readiness probe checking database connectivity and environment configuration. Returns 503 if any dependency is unhealthy.

Response

{
  "status": "healthy",
  "checks": {
    "database": "ok",
    "environment": "ok"
  },
  "timestamp": "2026-04-11T14:00:00Z"
}

Quick Start Example

// Create a session and connect to the LiveKit room
const response = await fetch('https://interprivo.net/api/sessions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ip_live_<your_key>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    source_lang: 'en',
    target_lang: 'es',
    speaker_name: 'Dr. Smith',
  }),
});

const { sessionId, roomToken, liveKitUrl } = await response.json();

// Use the LiveKit SDK to join the room
const room = new Room();
await room.connect(liveKitUrl, roomToken);
console.log('Connected to translation room:', sessionId);

For complete SDK examples and language bindings, see the LiveKit documentation. For questions or API access, contact support@interprivo.net.