Initiate session file upload

POST/v1/event/{eventId}/sessions/{sessionId}/files

US Region: https://public-api.sessionboard.com · EU Region: https://public-api-eu.sessionboard.com

Creates a file record and returns a short-lived S3 upload URL. Requires write:sessions.

Next: PUT the file bytes to data.upload.url, then call POST .../files/{fileId}/complete. For files up to 50 MB, prefer POST .../files/upload (one multipart call). This direct-to-storage path supports up to 500 MB. See Uploading session files.

Request example

curl --request POST \
  --url 'https://public-api.sessionboard.com/v1/event/{eventId}/sessions/{sessionId}/files' \
  --header 'x-access-token: <api-token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "filename": "keynote-slides.pptx",
  "size_bytes": 2457600,
  "content_type": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
  "title": "Keynote slides"
}'

const response = await fetch('https://public-api.sessionboard.com/v1/event/{eventId}/sessions/{sessionId}/files', {
  method: 'POST',
  headers: {
    "x-access-token": "<api-token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "filename": "keynote-slides.pptx",
    "size_bytes": 2457600,
    "content_type": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
    "title": "Keynote slides"
  }),
});

const data = await response.json();
console.log(data);

import requests

response = requests.request(
    "POST",
    "https://public-api.sessionboard.com/v1/event/{eventId}/sessions/{sessionId}/files",
    headers={
        "x-access-token": "<api-token>",
        "Content-Type": "application/json"
    },
    json={
        "filename": "keynote-slides.pptx",
        "size_bytes": 2457600,
        "content_type": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
        "title": "Keynote slides"
    },
)

print(response.json())

<?php

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://public-api.sessionboard.com/v1/event/{eventId}/sessions/{sessionId}/files",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => '{
  "filename": "keynote-slides.pptx",
  "size_bytes": 2457600,
  "content_type": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
  "title": "Keynote slides"
}',
    CURLOPT_HTTPHEADER => [
        "x-access-token: <api-token>",
        "Content-Type: application/json",
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

package main

import (
  "fmt"
  "io"
  "net/http"
  "strings"
)

func main() {
  req, _ := http.NewRequest("POST", "https://public-api.sessionboard.com/v1/event/{eventId}/sessions/{sessionId}/files", strings.NewReader(`{
  "filename": "keynote-slides.pptx",
  "size_bytes": 2457600,
  "content_type": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
  "title": "Keynote slides"
}`))
  req.Header.Add("x-access-token", "<api-token>")
  req.Header.Add("Content-Type", "application/json")

  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)

  fmt.Println(string(body))
}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://public-api.sessionboard.com/v1/event/{eventId}/sessions/{sessionId}/files"))
    .header("x-access-token", "<api-token>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\n  \"filename\": \"keynote-slides.pptx\",\n  \"size_bytes\": 2457600,\n  \"content_type\": \"application/vnd.openxmlformats-officedocument.presentationml.presentation\",\n  \"title\": \"Keynote slides\"\n}"))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());

Try it

Response headers

Authorizations

x-access-tokenstringheader
Organization API token. Generate from Organization Settings → API Tokens.
AuthorizationBearer <token>headeror
OAuth 2.1 access token. Obtained via the OAuth PKCE flow at /oauth/token.

Send one of these. See Authentication.

Path parameters

eventIdintegerpathrequired
Event ID
sessionIdstring<uuid>pathrequired
Session UUID

Request body

application/jsonrequired

filenamestringrequired
Original filename including extension (e.g. slides.pptx, handout.pdf).
Example
"keynote-slides.pptx"
size_bytesintegerrequired
Exact file size in bytes. Maximum 500 MB (524288000) for direct-to-storage upload. Use POST .../files/upload for files up to 50 MB without specifying size.
Minimum
1
Maximum
524288000
content_typestring
MIME type. Optional; inferred from the filename extension when omitted.
Example
"application/vnd.openxmlformats-officedocument.presentationml.presentation"
mimetypestring
Alias for content_type.
titlestring
Display title. Defaults to filename.
assigned_participant_idstring<uuid> | null
Contact UUID of a session participant to assign this file to.
content_slot_idstring<uuid> | null
The upload slot this file answers. Optional — API callers act as the organization, so no slot deadline applies and a file may be attached without a slot. When set, the slot must be active, apply to the session (GET .../content-slots?session_id=), accept the file's declared type and have room under its max_files; otherwise 400 names the slot. The file's type is derived from the slot's content_type. Ignored on events that still use a single file request.

{
  "filename": "keynote-slides.pptx",
  "size_bytes": 2457600,
  "content_type": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
  "title": "Keynote slides"
}

{
  "filename": "handout.pdf",
  "size_bytes": 512000,
  "content_type": "application/pdf",
  "title": "Session handout"
}

{
  "filename": "poster.pdf",
  "size_bytes": 3145728,
  "content_type": "application/pdf",
  "title": "Poster",
  "content_slot_id": "2783cb27-958a-4a24-89d9-2d71387f04cc"
}

Responses

201`application/json`

Created — upload URL included

dataobject
A content attachment (file, document, or media) associated with a session.

Approvals. On events using Approvals (Early Access), a file can be held back until it is approved and its release time has passed. The Session Files endpoints still list a held file, so an integration knows it exists, but return url: null until it is released. Publish only files whose approval_status is approved or not_required. When a file you already published moves to any other status, remove it from your destination.
Show child attributes
- idstring<uuid>
- urlstring<uri> | null
  Download URL. null while Approvals holds the file back (see approval_status), so nothing built on the API can publish it early.
- titlestring
- filenamestring
- sizeinteger
- mimetypestring
- typestring | null
  Organizer-facing file type, e.g. presentation, handout, poster, or holding_slide for slides generated by Sessionboard. Filterable with ?type= on the list endpoint.
  Example
  "holding_slide"
- labelstring | null
  Display label shown on the session's Files tab, e.g. Holding Slide.
  Example
  "Holding Slide"
- created_atstring<date-time>
- updated_atstring<date-time>
- assigned_participant_idstring<uuid> | null
  Contact UUID of the session participant this file is assigned to.
- assigned_participant_emailstring<email> | null
- assigned_participant_namestring | null
- content_slot_idstring<uuid> | null
  The upload slot this file answers — see GET /v1/event/{eventId}/content-slots. Present only while the event uses upload slots; null for events on a single file request, and for files uploaded before slots existed or outside any slot.
- approval_statusstring
  Approval state, returned by the Session Files endpoints.
  
  not_required: not under an approval workflow (no workflow, workflow off, or uploaded before it was turned on).
  
  pending: waiting on a reviewer.
  
  approved: approved and released.
  
  denied: sent back to the uploader for changes.
  
  superseded: a newer version replaced it before it was decided.
  
  embargoed: approved (or not required) but held until a release time; see embargo_until.
  
  Only approved and not_required files have a url.
  Allowed values
  "not_required", "pending", "approved", "denied", "superseded", "embargoed"
  Example
  "approved"
- embargo_untilstring<date-time> | null
  When an embargoed file is released (UTC). null when it is not embargoed, or when it waits for its session to be scheduled (release "when each file's session starts").
- uploadobject
  Show child attributes
  - urlstring<uri>
    Presigned S3 URL — PUT the file bytes here.
  - methodstring
    Example
    "PUT"
  - headersobject
    Show child attributes
    Content-Typestring

400

Validation error (missing fields, oversize, denied type, or a content_slot_id that is inactive, does not apply to the session, rejects the file type or is full)

403

Missing write:sessions scope

Response examples

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "url": "https://example.com",
    "title": "<string>",
    "filename": "<string>",
    "size": 123,
    "mimetype": "<string>",
    "type": "holding_slide",
    "label": "Holding Slide",
    "created_at": "2026-01-15T09:30:00Z",
    "updated_at": "2026-01-15T09:30:00Z",
    "assigned_participant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "assigned_participant_email": "jane@example.com",
    "assigned_participant_name": "<string>",
    "content_slot_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "approval_status": "approved",
    "embargo_until": "2026-01-15T09:30:00Z",
    "upload": {
      "url": "https://example.com",
      "method": "PUT",
      "headers": {
        "Content-Type": "<string>"
      }
    }
  }
}