Skip to main content

Magic Links

Generate a secure, shareable link to allow others to view a transcription document—without requiring direct API authentication.

Use the same API token that was used to create the original transcript session. Magic links are bound to the session-level authentication.

Required Authentication​

HeaderTypeRequiredDescription
Content-TypestringMust be application/json
X-Zoom-S2T-KeystringBatch API token tied to the original session

Path Parameters​

ParameterDescription
sessionIdThe Transcript Session ID from the original batch job
documentIdThe Document ID from a Create or Get Document response

Endpoint​

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

Example Response​

{
  "result": {
    "link": "https://scriptix.app/shared/x/y/z"
  }
}

Response Codes​

Status CodeDescription
201Share link created successfully
400Bad request – e.g., document already marked as finished
401Unauthorized – invalid or missing API token
403Forbidden – token does not have access to this document
404Not found – the document doesn't exist or doesn't belong to the session

Use Cases​

  • Share transcript results with collaborators
  • Enable one-click viewing for clients or reviewers
  • Provide external access without exposing API credentials
  • Generate time-limited download links for public file sharing
  • Embed transcript downloads in web applications without backend proxying

Once you have a magic link, documents can be retrieved using the public shared endpoint without authentication.

Endpoint​

GET /api/v3/shared/{sessionId}/document/{documentId}

Query Parameters​

KeyTypeDefaultDescription
formatstringjsonDocument format (json, pdf, docx, srt, vtt, sbv, ttml, stl, html, template)
direct_downloadbooleanfalseRECOMMENDED: Set to true
Returns time-limited download URL instead of streaming
Streaming Deprecated

Like the authenticated endpoint, direct streaming (direct_download=false) is deprecated. Use direct_download=true for better performance and reliability.

Response Structure​

Both download methods now return the unified DocumentDownloadUrlResponse structure.

HTTP 200 OK

With URL Download (direct_download=true)

{
  "result": {
    "download_url": "https://scriptixbox.blob.core.windows.net/documents/abc123/transcript.pdf?sv=2021-08-06&se=2025-12-07T15:30:00Z&sr=b&sp=r&sig=...",
    "expires_in": 3600,
    "filename": "shared-transcript.pdf",
    "content_type": "application/pdf",
    "size_bytes": null,
    "document": null,
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "created": "2024-01-15T10:30:00Z",
    "last_modified": "2024-01-15T11:00:00Z",
    "language": "en",
    "type": "document",
    "timecode_offset": "00:00:00.000",
    "finished": true,
    "use_plain_document": false,
    "plain_document_changed": false
  },
  "count": 0,
  "total_results": 0
}

With Embedded Document (direct_download=false)

{
  "result": {
    "document": [
      {
        "start": 525,
        "stop": 6252,
        "speaker": "M1",
        "text": "Example transcription text."
      }
    ],
    "download_url": null,
    "expires_in": null,
    "filename": "shared-transcript.json",
    "content_type": "application/json",
    "size_bytes": null,
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "created": "2024-01-15T10:30:00Z",
    "last_modified": "2024-01-15T11:00:00Z",
    "language": "en",
    "type": "document",
    "timecode_offset": "00:00:00.000",
    "finished": true,
    "use_plain_document": false,
    "plain_document_changed": false
  },
  "count": 0,
  "total_results": 0
}
Response Unification

The response now always includes document metadata (id, created, language, etc.) regardless of download method. When direct_download=true, the download_url and expires_in fields are populated. When direct_download=false, the document field contains the embedded content.

The URL expires in 1 hour (3600 seconds). Download URLs are time-limited but can be regenerated.

See Retrieve Document for detailed response schema and field descriptions.

Example Usage​

Get Download URL for Shared PDF:

curl "https://api.scriptix.io/api/v3/shared/SESSION_ID/document/DOC_ID?format=pdf&direct_download=true"

Response:

{
  "result": {
    "download_url": "https://scriptixbox.blob.core.windows.net/.../document.pdf?...",
    "expires_in": 3600,
    "filename": "transcript.pdf",
    "content_type": "application/pdf",
    "size_bytes": null,
    "document": null,
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "created": "2024-01-15T10:30:00Z",
    "last_modified": "2024-01-15T11:00:00Z",
    "language": "en",
    "type": "document",
    "timecode_offset": "00:00:00.000",
    "finished": true,
    "use_plain_document": false,
    "plain_document_changed": false
  },
  "count": 0,
  "total_results": 0
}

Then use the download_url to download the file directly. The response also includes full document metadata for tracking and display purposes.

Next Steps​