API Overview

Complete guide to the Scriptix API for speech-to-text transcription, real-time streaming, document management, and custom models.

Introduction

The Scriptix API provides programmatic access to the speech recognition platform. Build applications that:

• Transcribe audio/video files to text (batch processing)
• Stream real-time audio for live transcription
• Manage documents (transcripts and captions)
• Train custom models for domain-specific accuracy
• Create glossaries for terminology customization
• Translate content to multiple languages
• Export in multiple formats

Base URL

All API requests use this base URL:

https://api.scriptix.io

API Versions

The Scriptix API is versioned. Current versions:

Version	Endpoint Prefix	Status	Recommended
v4	/api/v4	Current	✅ For glossaries and realtime
v3	/api/v3	Stable	✅ Primary API version

Recommendation: Use v3 for most operations, v4 for glossaries and realtime features.

Authentication

All API requests require authentication via Bearer token.

Using Your Token

Include your authentication token in the Authorization header:

Authorization: Bearer YOUR_TOKEN

Example:

curl https://api.scriptix.io/api/v3/account/me \
  -H "Authorization: Bearer your_token_here"

⚠️ Never commit tokens to version control or expose them client-side.

API Categories

Speech-to-Text Sessions API

Upload audio/video files for transcription and manage transcription sessions.

Key Endpoints:

• GET /api/v3/speech-to-text/session - List sessions
• GET /api/v3/speech-to-text/session/{sessionId} - Get session details
• DELETE /api/v3/speech-to-text/session/{sessionId} - Delete session

Use cases: Podcasts, interviews, meetings, video subtitles

Documents API

Manage transcripts and captions within sessions.

Key Endpoints:

• GET /api/v3/speech-to-text/session/{sessionId}/document/{docId} - Get document
• PUT /api/v3/speech-to-text/session/{sessionId}/document/{docId} - Update document
• DELETE /api/v3/speech-to-text/session/{sessionId}/document/{docId} - Delete document
• POST /api/v3/speech-to-text/session/{sessionId}/document - Copy document
• PUT /api/v3/speech-to-text/session/{sessionId}/document/{docId}/clear_text - Clear text
• PUT /api/v3/speech-to-text/session/{sessionId}/document/{docId}/reset_to_original - Reset document
• POST /api/v3/speech-to-text/session/{sessionId}/document/{docId}/finished_status - Mark as finished

Query Parameters for GET:

• format - Output format (default: json)
• template_id - Export template ID

Translation API

Translate documents to multiple languages.

Endpoints:

• POST /api/v3/speech-to-text/session/{sessionId}/document/{docId}/translate-multiple - Translate document

Request Body:

{
  "languages": ["nl", "fr", "de"],
  "filename": "translated_document"
}

Document Operations API

Additional document operations.

Endpoints:

• POST /api/v3/speech-to-text/merge - Merge multiple documents
• POST /api/v3/speech-to-text/session/{sessionId}/document/{docId}/export/summarize - Summarize document

Sharing API

Share documents via magic links.

Endpoints:

• POST /api/v3/speech-to-text/session/{sessionId}/document/{docId}/share - Create share link
• POST /api/v3/speech-to-text/session/{sessionId}/document/{docId}/share/email - Share via email
• GET /api/v3/speech-to-text/session/{sessionId}/shared - Get shared session
• GET /api/v3/speech-to-text/session/{sessionId}/shared/document/{docId} - Get shared document
• PUT /api/v3/speech-to-text/session/{sessionId}/shared/document/{docId} - Update shared document
• PUT /api/v3/speech-to-text/session/{sessionId}/shared/document/{docId}/clear_text - Clear shared text
• PUT /api/v3/speech-to-text/session/{sessionId}/shared/document/{docId}/reset_to_original - Reset shared
• PUT /api/v3/speech-to-text/session/{sessionId}/shared/document/{docId}/finish - Finish shared document

Comments API

Collaborate on documents with comments.

Endpoints:

• GET /api/v3/speech-to-text/session/{sessionId}/document/{docId}/comments - List comments
• POST /api/v3/speech-to-text/session/{sessionId}/document/{docId}/comments - Create comment
• PUT /api/v3/speech-to-text/session/{sessionId}/document/{docId}/comments/{commentId} - Update comment
• DELETE /api/v3/speech-to-text/session/{sessionId}/document/{docId}/comments/{commentId} - Delete comment

Custom Models API

Train specialized models for domain-specific vocabulary.

Endpoints:

• GET /api/v3/speech-to-text/models - List available models
• GET /api/v3/custom_models - List custom models
• GET /api/v3/custom_models/{id} - Get model details
• GET /api/v3/custom_models/{id}/data - Get training datasets
• POST /api/v3/custom_models - Create custom model
• POST /api/v3/custom_models/{id} - Update model
• PUT /api/v3/custom_models/{id}/data - Upload training data
• POST /api/v3/custom_models/{id}/run - Start training
• DELETE /api/v3/custom_models/{id} - Delete model
• DELETE /api/v3/custom_models/{id}/data/{dataId} - Delete dataset

Use cases: Medical, legal, technical terminology

Glossaries API (v4)

Create custom glossaries for terminology recognition.

Endpoints:

• GET /api/v4/glossaries - List glossaries
• GET /api/v4/glossaries/{id} - Get glossary details
• GET /api/v4/glossaries/{id}/entries - Get glossary entries (CSV format)
• GET /api/v4/glossaries/supported-languages - Get supported language pairs
• POST /api/v4/glossaries - Create glossary
• PATCH /api/v4/glossaries/{id} - Update glossary
• DELETE /api/v4/glossaries/{id} - Delete glossary

Query Parameters for GET glossary:

• include_entries - Include entries in response (default: false)
• limit - Max entries to return (default: 1000)

Note: Glossary entries are returned in CSV format when requested via the entries endpoint.

Real-time API (v4)

Stream live audio for real-time transcription.

Endpoints:

• POST /api/v4/realtime/initialize - Initialize real-time session
• GET /api/v4/realtime/status - Check real-time service status

Use cases: Live captions, voice assistants, call centers

Folders API

Organize documents in folders.

Endpoints:

• GET /api/v3/folders - List folders
• GET /api/v3/folders/{id} - Get folder contents
• POST /api/v3/folders - Create folder
• PUT /api/v3/folders/{id} - Update folder
• DELETE /api/v3/folders/{id} - Delete folder

Organization Management API

Manage organization settings and members.

Endpoints:

• GET /api/v3/account/organization - Get organization details
• POST /api/v3/account/organization - Update organization
• POST /api/v3/organization/group - Create team/group
• GET /api/v3/organization/group - List teams
• GET /api/v3/organization/group/{id} - Get team details
• GET /api/v3/organization/group/{id}/users - List team members
• PUT /api/v3/organization/group/{id} - Update team
• DELETE /api/v3/organization/group/{id} - Delete team
• POST /api/v3/organization/group/{id}/users - Add members to team
• DELETE /api/v3/organization/group/{id}/users/remove - Remove members
• POST /api/v3/organization/user - Create user
• GET /api/v3/organization/user - List users
• GET /api/v3/organization/user/{id} - Get user details
• PUT /api/v3/organization/user/{id} - Update user
• DELETE /api/v3/organization/user/{id} - Delete user
• POST /api/v3/organization/user/{id}/resend-activation - Resend activation email
• POST /api/v3/organization/profile/{id}/logo - Upload organization logo
• DELETE /api/v3/organization/profile/{id} - Delete organization logo

Export Templates API

Manage custom export templates.

Endpoints:

• GET /api/v3/organization/templates - List templates
• POST /api/v3/organization/templates - Create template
• DELETE /api/v3/organization/templates/{id} - Delete template

User Account API

Manage user accounts and preferences.

Endpoints:

• GET /api/v3/account/me - Get current user
• POST /api/v3/account/me - Update profile
• POST /api/v3/account/password - Change password
• PATCH /api/v3/account - Deactivate account
• DELETE /api/v3/account - Delete account

Authentication API

User authentication and session management.

Endpoints:

• POST /api/v3/auth/login - Login
• POST /api/v3/auth/login/mfa - Login with MFA
• POST /api/v3/auth/logout - Logout
• GET /api/v3/auth/login/microsoft - Microsoft SSO login

Two-Factor Authentication API

Enable and manage 2FA.

Endpoints:

• GET /api/v3/mfa/2fa/qr_code - Get QR code for setup
• GET /api/v3/mfa/2fa/backup_codes - Get backup codes
• POST /api/v3/mfa/2fa/enable - Enable 2FA
• POST /api/v3/mfa/2fa/disable - Disable 2FA
• POST /api/v3/mfa/2fa/verify_totp - Verify TOTP code
• POST /api/v3/mfa/2fa/verify_backup_code - Verify backup code

API Tokens API

Manage API access tokens.

Endpoints:

• GET /api/v3/tokens - List tokens
• POST /api/v3/tokens - Create token (not in POST_URL but implied)
• DELETE /api/v3/tokens/{id} - Delete token

Subscriptions API

Manage subscriptions and billing.

Endpoints:

• GET /api/v3/subscription - List subscriptions
• GET /api/v3/subscription/{id} - Get subscription details
• GET /api/v3/subscription/{id}/usage - Get usage stats
• POST /api/v3/order_subscription/new_order - Create subscription
• DELETE /api/v3/subscription/{id} - Cancel subscription

Invoices API

View and download invoices.

Endpoints:

• GET /api/v3/invoices - List invoices
• GET /api/v3/invoices/{id}/download - Download invoice PDF

Mandates API

Manage payment mandates.

Endpoints:

• GET /api/v3/mandates - List mandates

User Preferences API

Store and retrieve user preferences.

Endpoints:

• GET /api/v3/user_preferences - List preferences
• GET /api/v3/user_preferences/{id} - Get preference
• POST /api/v3/user_preferences - Create preference
• PUT /api/v3/user_preferences/{id} - Update preference
• DELETE /api/v3/user_preferences/{id} - Delete preference

Reseller API

Manage customers and organizations (reseller accounts only).

Endpoints:

• GET /api/v3/reseller/customer - List customers
• GET /api/v3/reseller/customer/{id} - Get customer details
• GET /api/v3/reseller/customer/{id}/usage - Get customer usage
• GET /api/v3/reseller/customer/{id}/logins - List customer logins
• GET /api/v3/reseller/customer/{id}/tokens - List customer tokens
• GET /api/v3/reseller/customer/{id}/subscriptions - List customer subscriptions
• GET /api/v3/reseller/customer/{id}/transcript - List customer transcripts
• GET /api/v3/reseller/plan - List available plans
• GET /api/v3/reseller/usage - Get reseller usage statistics
• GET /api/v3/reseller/statistics - Get reseller statistics
• GET /api/v3/reseller/reporting/export - Export reseller reports
• POST /api/v3/reseller/customer - Create customer
• POST /api/v3/reseller/customer/{id}/logins - Create customer login
• POST /api/v3/reseller/customer/{id}/logins/{loginId}/resend-activation - Resend activation
• POST /api/v3/reseller/customer/{id}/logins/{loginId}/reset - Reset password
• POST /api/v3/reseller/customer/{id}/tokens - Create token
• POST /api/v3/reseller/plan/{planId}/subscribe - Subscribe to plan
• PUT /api/v3/reseller/customer/{id} - Update customer
• PUT /api/v3/reseller/customer/{id}/logins/{loginId}/deactivate - Deactivate login
• DELETE /api/v3/reseller/customer/{id} - Delete customer
• DELETE /api/v3/reseller/customer/{id}/logins/{loginId} - Delete login
• DELETE /api/v3/reseller/customer/{id}/tokens/{tokenId} - Delete token

Pagination

List endpoints return paginated results using offset and limit parameters.

Request Parameters

GET /api/v3/folders?offset=0&limit=25

Parameter	Type	Default	Description
offset	integer	0	Number of items to skip
limit	integer	25	Number of items to return

Response Format

{
  "count": 25,
  "total_results": 150,
  "result": [...]
}

Field	Type	Description
count	integer	Items in current response
total_results	integer	Total items across all pages
result	array	Array of items

Pagination Example

def get_all_folders():
    offset = 0
    limit = 100
    all_folders = []

    while True:
        response = requests.get(
            'https://api.scriptix.io/api/v3/folders',
            headers={'Authorization': 'Bearer YOUR_TOKEN'},
            params={'offset': offset, 'limit': limit}
        )
        data = response.json()

        all_folders.extend(data['result'])

        # Check if more pages exist
        if len(data['result']) < limit:
            break

        offset += limit

    return all_folders

Filtering & Sorting

Many list endpoints support filtering and sorting via query parameters.

Common Query Parameters

Parameter	Type	Example	Description
q	string	meeting	Search query
sort	string	created_at	Field to sort by
direction	string	desc	Sort direction (asc or desc)

Example

# Sort folders by name, descending
GET /api/v3/folders?sort=name&direction=desc

# Search with query
GET /api/v3/folders?q=meeting&limit=50

Error Handling

All errors follow a consistent format with standard HTTP status codes.

HTTP Status Codes

Code	Meaning	Common Causes
200	OK	Request successful
201	Created	Resource created successfully
204	No Content	Successful deletion
400	Bad Request	Invalid parameters
401	Unauthorized	Invalid or missing token
403	Forbidden	Insufficient permissions
404	Not Found	Resource doesn't exist
409	Conflict	Resource state conflict
422	Unprocessable Entity	Validation error
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error

Error Response Format

Errors may include detail arrays or message strings depending on the endpoint.

{
  "detail": [
    {
      "loc": ["body", "field_name"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

or

{
  "message": "Error description"
}

Best Practices

1. Handle Errors Gracefully

Implement retry logic with exponential backoff:

import time
import requests

def api_call_with_retry(func, max_retries=3):
    for attempt in range(max_retries):
        try:
            return func()
        except requests.exceptions.RequestException:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)  # Exponential backoff

2. Use Pagination Efficiently

Don't load all results at once - paginate through data:

# ✅ Good - paginate through results
offset = 0
limit = 100
while True:
    page = get_page(offset, limit)
    process(page)
    if len(page) < limit:
        break
    offset += limit

3. Secure Your Tokens

• Never commit tokens to version control
• Use environment variables
• Rotate tokens regularly
• Use different tokens for dev/production

import os

API_TOKEN = os.environ.get('SCRIPTIX_API_TOKEN')
if not API_TOKEN:
    raise ValueError("SCRIPTIX_API_TOKEN environment variable not set")

4. Respect API Limits

• Check response headers for rate limit information
• Implement backoff when approaching limits
• Cache responses when possible

Quick Start Examples

Get Current User

curl https://api.scriptix.io/api/v3/account/me \
  -H "Authorization: Bearer YOUR_TOKEN"

List Sessions

curl https://api.scriptix.io/api/v3/speech-to-text/session?offset=0&limit=25 \
  -H "Authorization: Bearer YOUR_TOKEN"

Get Document

curl https://api.scriptix.io/api/v3/speech-to-text/session/{sessionId}/document/{docId} \
  -H "Authorization: Bearer YOUR_TOKEN"

Create Glossary

curl -X POST https://api.scriptix.io/api/v4/glossaries \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Medical Terms",
    "source_language": "en",
    "target_language": "nl"
  }'

Translate Document

curl -X POST https://api.scriptix.io/api/v3/speech-to-text/session/{sessionId}/document/{docId}/translate-multiple \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "languages": ["nl", "fr", "de"],
    "filename": "translated_output"
  }'

Next Steps

Explore specific API sections for detailed documentation:

• Custom Models - Custom Models API
• Glossaries - Glossaries API
• Document Management - Documents API
• Real-time - Realtime API

---

Need help? Contact support at support@scriptix.io