Media & Transcriptions

Use this guide to pick the right workflow, then follow the steps. All paths are session-scoped unless noted.

Pick your playbook

Playbook 1 — Sync transcript text

You already have the words (full transcript, summary, topics, or translation) and want them on a session.Requires write:transcriptions to create; read:transcriptions to list or verify.

Playbook 2 — Upload a media file

You have a video or audio file (MP4, MOV, MP3, etc.) and want Sessionboard to transcribe it automatically.Requires write:media to upload; read:media to check status. If you upload on a session URL, transcript lines appear in the session transcription list when processing finishes — no separate fragment upload needed.

Playbook 3 — Upload session audio

You have an audio file for a session’s recording archive (live capture, imported audio, or segments to stitch later).Requires write:transcriptions. Accepts common audio formats; Sessionboard normalizes the file when you mark the upload complete.

Not sure which to use? Playbook 1 is for text you generate elsewhere. Playbook 2 is for files you want transcribed inside Sessionboard (same flow as Import → Upload in the admin UI). Playbook 3 is for audio tied to the session recording archive, not the media library.For PDFs, PowerPoint, and other session attachments (slides, handouts), use the separate Uploading session files guide — different scopes (write:sessions) and endpoints.

Before you begin

Replace {eventId} and {sessionId} with your event and session IDs. Send your API token on every request:

X-Access-Token: {your-token}

Create tokens and scopes in Authentication. Writes always need an explicit scope; legacy tokens with empty scopes can read but cannot create or upload.

Playbook 1 — Sync transcript text

When to use it

You produced a transcript outside Sessionboard and want it on a session.
You need summaries, topic insights, or translations alongside transcript text.

Transcription types

`type`	What to send
`fragment`	Transcript text (`transcription`). Use one fragment for a full session transcript, or many for timed lines.
`summary`	Summary content (`content`).
`insight`	Topics or entities (`name`, `insight_type`). Optionally link to fragments with `fragment_ids`.
`translation`	Translated text (`translated_text`) linked to a source fragment or summary.

Create a transcription

POST /v1/event/{eventId}/sessions/{sessionId}/transcriptions
Content-Type: application/json

Example — full session transcript as one fragment:

{
  "type": "fragment",
  "transcription": "Welcome everyone to today's keynote...",
  "provider": "my-platform",
  "is_partial": false,
  "language_code": "en"
}

Set is_partial to false when the text is final. The response includes the new id.

Verify on the session

GET /v1/event/{eventId}/sessions/{sessionId}/transcriptions
GET /v1/event/{eventId}/sessions/{sessionId}/transcriptions/{transcriptionId}

Update or remove (optional)

PUT /v1/event/{eventId}/sessions/{sessionId}/transcriptions/{transcriptionId}
DELETE /v1/event/{eventId}/sessions/{sessionId}/transcriptions/{transcriptionId}

Event-wide listing

To search across all sessions in an event:

GET /v1/event/{eventId}/transcriptions?page=1&page_size=25&type=fragment

By default, in-progress live-capture lines (is_partial=true) are hidden. Add include_partial=true to include them.

Playbook 2 — Upload a media file

When to use it

You have a video or audio file and want automatic transcription.
The file should appear in Sessionboard’s media hub for the session.

What happens

You upload the file in parts (large files supported, up to 50 GB).
Sessionboard processes the file and runs transcription.
You poll until transcript_status is ready.
If the upload URL includes {sessionId}, transcript fragments are added to that session automatically. You do not need Playbook 1 for the same content.

Start the upload

POST /v1/event/{eventId}/sessions/{sessionId}/media/upload/initiate
Content-Type: application/json

{
  "filename": "keynote-recording.mp4",
  "content_type": "video/mp4",
  "size_bytes": 524288000
}

Response includes key, upload_id, and part sizing. Keep these for the next steps.

Get upload URLs for each part

POST /v1/event/{eventId}/sessions/{sessionId}/media/upload/sign-part
Content-Type: application/json

{
  "key": "{key from initiate}",
  "upload_id": "{upload_id from initiate}",
  "part_numbers": [1, 2, 3]
}

Response returns a URL per part number.

Upload each part

PUT the file bytes to each URL from the previous step. Save the ETag header from each response — you need it to finish the upload.

Finish the upload

POST /v1/event/{eventId}/sessions/{sessionId}/media/upload/complete
Content-Type: application/json

{
  "key": "{key}",
  "upload_id": "{upload_id}",
  "filename": "keynote-recording.mp4",
  "size_bytes": 524288000,
  "parts": [
    { "part_number": 1, "etag": "\"abc123\"" },
    { "part_number": 2, "etag": "\"def456\"" }
  ]
}

Response includes mediaItemId. The session is taken from the URL — do not send session_id in the body.

Poll until transcription is ready

GET /v1/event/{eventId}/sessions/{sessionId}/media/{mediaItemId}

Check transcript_status:

Status	Meaning
`queued`	Waiting to process
`processing`	Transcription in progress
`ready`	Done — session fragments are available if you uploaded on a session URL
`failed`	Processing failed — inspect the item or retry upload

Then list session transcriptions to read the generated fragments:

GET /v1/event/{eventId}/sessions/{sessionId}/transcriptions?type=fragment

To cancel an in-progress upload, call POST .../media/upload/abort with key and upload_id.

Playbook 3 — Upload session audio

When to use it

You have audio for a session’s recording archive (not the media library flow in Playbook 2).
You need audio available for session playback, stitching, or downstream transcription inside Sessionboard.

Supported file types

wav, mp3, m4a, aac, flac, ogg, pcm

Start the recording upload

POST /v1/event/{eventId}/sessions/{sessionId}/recordings
Content-Type: application/json

{
  "filename": "session-audio.wav",
  "content_type": "audio/wav",
  "size_bytes": 1048576
}

Response includes a recording id and an upload.url. Use that URL for the next step.

Upload the file

PUT the audio bytes to upload.url using the Content-Type from the response headers.

Mark the upload complete

POST /v1/event/{eventId}/sessions/{sessionId}/recordings/{recordingId}/complete
Content-Type: application/json

{
  "duration_seconds": 3600,
  "file_size_bytes": 1048576
}

Both fields are optional but help accuracy. Sessionboard accepts common formats and prepares the file for the recording pipeline when you complete.Calling complete again on an already-completed recording returns success without duplicating work.

Confirm the recording

GET /v1/event/{eventId}/sessions/{sessionId}/recordings/{recordingId}
GET /v1/event/{eventId}/sessions/{sessionId}/recordings

Scopes quick reference

Scope	Use it for
`read:transcriptions`	List/get transcriptions and recordings
`write:transcriptions`	Create, update, delete transcriptions; upload session audio
`read:media`	Check media upload and transcription status
`write:media`	Multipart media upload

Scoped read tokens must include the matching read scope. For example, read:events alone does not allow transcription or media GET endpoints.

Transcriptions & Media API overview
Uploading session files — PDFs, PowerPoint, and document attachments
Authentication & scopes
OpenAPI — transcriptions endpoints

Getting Started

Guides

Insights & AI

Release Notes

Pick your playbook

Playbook 1 — Sync transcript text

Playbook 2 — Upload a media file

Playbook 3 — Upload session audio

Before you begin

Playbook 1 — Sync transcript text

When to use it

Transcription types

Event-wide listing

Playbook 2 — Upload a media file

When to use it

What happens

Playbook 3 — Upload session audio

When to use it

Supported file types

Scopes quick reference

​Pick your playbook

Playbook 1 — Sync transcript text

Playbook 2 — Upload a media file

Playbook 3 — Upload session audio

​Before you begin

​Playbook 1 — Sync transcript text

​When to use it

​Transcription types

​Event-wide listing

​Playbook 2 — Upload a media file

​When to use it

​What happens

​Playbook 3 — Upload session audio

​When to use it

​Supported file types

​Scopes quick reference

​Related reference

Pick your playbook

Before you begin

Playbook 1 — Sync transcript text

When to use it

Transcription types

Event-wide listing

Playbook 2 — Upload a media file

When to use it

What happens

Playbook 3 — Upload session audio

When to use it

Supported file types

Scopes quick reference

Related reference