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	Time-limited direct download URL
expires_in	number	URL expiration time in seconds

Direct Download Mode

Documents support direct download via a time-limited URL:

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 a download_url for fetching the content directly, without streaming it through the API.

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.

Sharing & Magic Links

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
  }'

Share via Email

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