Skip to main content

Share Documents & Magic Links

Create shareable magic links for documents without requiring authentication.

Overview​

Magic links allow you to share documents with anyone, even if they don't have a Scriptix account. Recipients can view and optionally edit documents through the shared link.

Generate a shareable link for a document.

Endpoint​

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

Request​

{
  "sessionId": "sess_abc123",
  "documentId": "doc_xyz789"
}

Optional payload (can also be empty {}).

Response​

Status: 200 OK

{
  "result": {
    "link": "https://app.scriptix.io/shared/transcript/abc123xyz?token=magic_token_here"
  }
}

Examples​

cURL​

curl -X POST https://api.scriptix.io/api/v3/speech-to-text/session/sess_abc123/document/doc_xyz789/share \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Share via Email​

Send magic link directly to recipients via email.

Endpoint​

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

Request​

{
  "emails": ["colleague@example.com", "partner@company.com"],
  "message": "Please review this transcript from our meeting."
}

Parameters​

ParameterTypeRequiredDescription
emailsstring[]YesArray of recipient email addresses
messagestringNoOptional personal message to include in email

Response​

Status: 200 OK

{
  "result": {
    "link": "https://app.scriptix.io/shared/transcript/abc123xyz?token=...",
    "emails_sent": ["colleague@example.com", "partner@company.com"],
    "success": true
  }
}

Examples​

cURL​

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

Access Shared Documents​

Recipients access shared documents through the magic link without authentication.

Shared Document Endpoints​

Magic links provide access to these endpoints:

Get Shared Session​

GET /api/v3/speech-to-text/session/{sessionId}/shared?token={token}

Get Shared Document​

GET /api/v3/speech-to-text/session/{sessionId}/shared/document/{documentId}?token={token}

Update Shared Document (if editing allowed)​

PUT /api/v3/speech-to-text/session/{sessionId}/shared/document/{documentId}?token={token}

Clear Text in Shared Document​

PUT /api/v3/speech-to-text/session/{sessionId}/shared/document/{documentId}/clear_text?token={token}

Reset Shared Document​

PUT /api/v3/speech-to-text/session/{sessionId}/shared/document/{documentId}/reset_to_original?token={token}

Finalize Shared Document​

PUT /api/v3/speech-to-text/session/{sessionId}/shared/document/{documentId}/finish?token={token}

Example - Access Shared Document​

curl "https://api.scriptix.io/api/v3/speech-to-text/session/sess_abc123/shared/document/doc_xyz789?token=magic_token_here"

No Authorization header required - the token grants access.

What Recipients Can Do​

With a magic link, recipients can:

  • ✅ View document content
  • ✅ View timestamps and speaker labels
  • ✅ Play associated media
  • ✅ Export document
  • ✅ Edit content (if editing enabled)

What Recipients Cannot Do​

  • ❌ Access other documents in the account
  • ❌ Delete documents
  • ❌ Create new documents
  • ❌ Change sharing settings

Magic link behavior is controlled server-side based on session settings:

SettingDescription
EditingWhether recipients can edit document content
ExportWhether recipients can download/export documents
CommentsWhether recipients can add comments
ExpiryWhen the link expires (configured per session)

Check session settings:

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

Look for allow_magic_link_export and other permission flags.

Use Cases​

1. Client Review​

Share transcripts with clients for review and approval:

# Generate magic link
response = requests.post(
    f'https://api.scriptix.io/api/v3/speech-to-text/session/{session_id}/document/{doc_id}/share',
    headers={'Authorization': f'Bearer {api_key}'},
    json={}
)

link = response.json()['result']['link']

# Send to client
print(f"Review link for client: {link}")

2. Team Collaboration​

Share with team members via email:

requests.post(
    f'https://api.scriptix.io/api/v3/speech-to-text/session/{session_id}/document/{doc_id}/share/email',
    headers={'Authorization': f'Bearer {api_key}'},
    json={
        'emails': ['team@company.com'],
        'message': 'Please review and add your edits.'
    }
)

3. Public Distribution​

Share meeting notes or podcasts publicly:

const link = await createMagicLink(sessionId, documentId);

// Share on social media, embed in website, etc.
document.getElementById('share-btn').href = link;

Security Considerations​

Best Practices​

  1. Use Email Sharing for Sensitive Content

    • Sends link directly to specific recipients
    • Provides audit trail of who received access

  2. Monitor Shared Links

    • Track which documents are shared
    • Revoke access when no longer needed

  3. Be Cautious with Public Links

    • Anyone with the link can access the document
    • Don't share sensitive/confidential content publicly

  4. Check Export Permissions

    • Disable export if you don't want recipients downloading content
    • Configure via session settings

Token Security​

  • Tokens are included in URL query parameters
  • Tokens grant access without authentication
  • Tokens may expire based on server configuration
  • Don't log or expose tokens unnecessarily

Error Handling​

StatusDescription
400Invalid request parameters
401Unauthorized - invalid API key
403Sharing disabled for this document/session
404Document or session not found
422Validation error (e.g., invalid email addresses)
500Internal server error

Common Errors​

Invalid Email Address​

{
  "detail": [
    {
      "loc": ["body", "emails", 0],
      "msg": "value is not a valid email address",
      "type": "value_error.email"
    }
  ]
}

Sharing Not Allowed​

{
  "error": "Sharing is not enabled for this session",
  "message": "Contact the session owner to enable sharing",
  "status": 403
}

Limitations​

  • Maximum 50 email recipients per request
  • Links may expire (check session settings)
  • Shared documents cannot access private workspace features
  • Export capabilities depend on session configuration