Documents API

Manage transcripts and captions created from speech-to-text sessions.

Overview

The Documents API allows you to:

List sessions containing documents
Retrieve document content (transcript or caption)
Update document content and metadata
Export to multiple formats
Translate documents to 30+ languages
Share documents via magic links
Delete documents

Document Architecture

Documents in Scriptix are always part of a session. Each transcription session contains one or more documents (transcript and/or caption). Documents are not standalone entities.

Document Types

Type	Description	Internal Key
Transcript	Full text transcript with timestamps and speaker labels	`document`
Caption	Subtitle/caption file with time-coded segments	`caption`

Base Endpoints

/api/v3/speech-to-text/session
/api/v3/speech-to-text/session/{sessionId}/document/{documentId}

Quick Start

List Sessions (containing documents)

curl https://api.scriptix.io/api/v3/speech-to-text/session \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Document

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

Update Document

curl -X PUT https://api.scriptix.io/api/v3/speech-to-text/session/{sessionId}/document/{documentId} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "Updated Meeting Notes",
    "document": {...},
    "plain_document_changed": "false"
  }'

Delete Document

curl -X DELETE https://api.scriptix.io/api/v3/speech-to-text/session/{sessionId}/document/{documentId} \
  -H "Authorization: Bearer YOUR_API_KEY"

Document Object

{
  "id": "doc_abc123",
  "filename": "Team Meeting January 2025",
  "type": "document",
  "language": "en",
  "created": "2025-01-17T10:00:00Z",
  "last_modified": "2025-01-17T15:30:00Z",
  "finished": false,
  "timecode_offset": "00:00:00:00",
  "content_type": "application/json",
  "size_bytes": 245600,
  "document": {
    "document_type": "document",
    "metadata": {...},
    "content": {...}
  }
}

Key Properties

Property	Type	Description
`id`	string	Unique document identifier
`filename`	string	Document filename
`type`	string	Document type: `document` or `caption`
`language`	string	Language code (e.g., `en`, `nl`, `fr`)
`finished`	boolean	Whether document is finalized
`timecode_offset`	string	Timecode offset for synchronization
`document`	object	Document content (transcript or caption data)
`download_url`	string	Direct download URL (Azure Blob Storage)
`expires_in`	number	URL expiration time in seconds

Direct Download Mode

For performance optimization, documents support direct download from Azure Blob Storage:

curl https://api.scriptix.io/api/v3/speech-to-text/session/{sessionId}/document/{documentId}?direct_download=true \
  -H "Authorization: Bearer YOUR_API_KEY"

Response includes download_url for fetching content directly from blob storage, reducing load balancer costs.

Export Formats

Export to SRT, VTT, SBV, TTML, STL (captions) or TXT, HTML, DOCX, PDF (transcripts). See Export Guide for complete format details and examples.

Translation

Translate documents to 30+ languages. See Translation Guide for details.

Create public sharing links for documents. See Share Guide for details.

curl -X POST https://api.scriptix.io/api/v3/speech-to-text/session/{sessionId}/document/{documentId}/share \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "allow_editing": false,
    "allow_export": true
  }'

curl -X POST https://api.scriptix.io/api/v3/speech-to-text/session/{sessionId}/document/{documentId}/share/email \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "colleague@example.com",
    "message": "Please review this transcript"
  }'

Magic links allow access without authentication. Recipients can view and optionally edit documents based on permissions.

Additional Operations

Copy Document

curl -X POST https://api.scriptix.io/api/v3/speech-to-text/session/{sessionId}/document \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_document_id": "doc_abc123",
    "new_filename": "Copy of Meeting Notes"
  }'

Merge Documents

curl -X POST https://api.scriptix.io/api/v3/speech-to-text/merge \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document_ids": ["doc_abc123", "doc_def456"],
    "output_filename": "Merged Transcript"
  }'

Summarize Document

curl -X POST https://api.scriptix.io/api/v3/speech-to-text/session/{sessionId}/document/{documentId}/export/summarize \
  -H "Authorization: Bearer YOUR_API_KEY"

Reset to Original

curl -X PUT https://api.scriptix.io/api/v3/speech-to-text/session/{sessionId}/document/{documentId}/reset_to_original \
  -H "Authorization: Bearer YOUR_API_KEY"

Clear Text Content

curl -X PUT https://api.scriptix.io/api/v3/speech-to-text/session/{sessionId}/document/{documentId}/clear_text \
  -H "Authorization: Bearer YOUR_API_KEY"

Finalize Document

curl -X POST https://api.scriptix.io/api/v3/speech-to-text/session/{sessionId}/document/{documentId}/finished_status?status=true \
  -H "Authorization: Bearer YOUR_API_KEY"

Session Object

Sessions contain documents and metadata about the transcription process:

{
  "id": 12345,
  "session_id": "sess_abc123",
  "filename": "meeting-recording.mp3",
  "status": "completed",
  "duration": 3600,
  "language": "en",
  "media_type": "audio/mpeg",
  "media_url": "https://...",
  "date_session_start": "2025-01-17T10:00:00Z",
  "last_modified": "2025-01-17T15:30:00Z",
  "session_mode": "decode"
}

Session Status Values

Status	Description
`queued`	Waiting for processing
`processing`	Currently transcribing
`completed`	Transcription finished
`failed`	Transcription failed
`dead_letter`	Permanently failed

Session Modes

Mode	Description
`decode`	Standard transcription from audio/video
`align`	Align existing text with media timestamps
`upload`	Direct document upload without media

Pagination

List endpoints support pagination:

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

Pagination Parameters

Parameter	Type	Default	Description
`offset`	integer	0	Number of records to skip
`limit`	integer	25	Maximum records to return
`q`	string	-	Search query
`sort`	string	-	Field to sort by
`direction`	string	-	Sort direction: `asc` or `desc`

Search & Filtering

Search sessions by filename, language, or status:

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

Error Handling

Common error responses:

Status Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
404	Not Found - Document or session doesn't exist
422	Unprocessable Entity - Validation error
500	Internal Server Error

Example error response:

{
  "error": "Document not found",
  "error_description": "The requested document does not exist or has been deleted",
  "status": 404
}

Rate Limits

API requests are subject to rate limits based on your subscription plan. Monitor response headers:

X-RateLimit-Limit - Maximum requests per window
X-RateLimit-Remaining - Remaining requests
X-RateLimit-Reset - Reset time (Unix timestamp)

Next Steps

Retrieve Document - Detailed document retrieval
Update Document - Update content and metadata
Export Formats - Export to various formats
Translation - Multi-language translation
Share & Magic Links - Public sharing

Overview​

Document Architecture​

Document Types​

Base Endpoints​

Quick Start​

List Sessions (containing documents)​

Get Document​

Update Document​

Delete Document​

Document Object​

Key Properties​

Direct Download Mode​

Export Formats​

Translation​

Sharing & Magic Links​

Share via Email​

Additional Operations​

Copy Document​

Merge Documents​

Summarize Document​

Reset to Original​

Clear Text Content​

Finalize Document​

Session Object​

Session Status Values​

Session Modes​

Pagination​

Pagination Parameters​

Search & Filtering​

Error Handling​

Rate Limits​

Next Steps​