Skip to main content
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

typeWhat to send
fragmentTranscript text (transcription). Use one fragment for a full session transcript, or many for timed lines.
summarySummary content (content).
insightTopics or entities (name, insight_type). Optionally link to fragments with fragment_ids.
translationTranslated text (translated_text) linked to a source fragment or summary.
1

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.
2

Verify on the session

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

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

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

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.
2

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.
3

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.
4

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.
5

Poll until transcription is ready

GET /v1/event/{eventId}/sessions/{sessionId}/media/{mediaItemId}
Check transcript_status:
StatusMeaning
queuedWaiting to process
processingTranscription in progress
readyDone — session fragments are available if you uploaded on a session URL
failedProcessing 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
1

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.
2

Upload the file

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

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.
4

Confirm the recording

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

​
Scopes quick reference

ScopeUse it for
read:transcriptionsList/get transcriptions and recordings
write:transcriptionsCreate, update, delete transcriptions; upload session audio
read:mediaCheck media upload and transcription status
write:mediaMultipart media upload
Scoped read tokens must include the matching read scope. For example, read:events alone does not allow transcription or media GET endpoints.