Welcome to the Panopto Community

Workflow of bulk scheduling via ScheduledRecordings API

Samuel ChanSamuel Chan Crackerjack

Hi, I can't find much information about the bulk scheduling feature with ScheduledRecordings API. Can someone explain to me a workflow of the bulk scheduling process?

Without finding much documentation about this, I am guessing the workflow would be:

  1. Create a bulk upload request and get a job ID using:
    POST /api/v1/scheduledRecordings/bulk/upload
  2. Start the scheduling using:
    POST /api/v1/scheduledRecordings/bulk/{jobId}/start
  3. Check the validation of the scheduling to see if the upload was successful:
    GET /api/v1/scheduledRecordings/bulk/{jobId}/validation
  4. Afterwards, I can check the schedules of the job with:
    GET /api/v1/scheduledRecordings/bulk/{jobId}/schedule

Also, can I get some examples of the request payload and response payload of each endpoint? I don't understand what exactly is needed to be fed into the requests.

Tagged:

Answers

  • Hi Samuel,

    Your list has the right endpoints, but steps 2 and 3 are in the wrong order. Uploading a CSV only validates it. You have to wait for validation to finish before you call start, because start is the step that creates the recordings.

    The real workflow:

    1. POST /bulk/upload sends the CSV and returns a jobId. Validation then runs in the background
    2. GET /bulk/{jobId}/validation: poll until status is Completed, then check the counts
    3. (Optional) GET /bulk/{jobId}/downloadValidationResults returns a zip with validated.csv, errors.csv and conflicts.csv, so you can see which rows failed and why
    4. POST /bulk/{jobId}/start begins scheduling the rows that passed validation
    5. GET /bulk/{jobId}/schedule: poll until status is Completed or Failed. It returns 404 if scheduling hasn't been started yet
    6. (Optional) GET /bulk/{jobId}/downloadJobResults returns a zip with scheduled.csv and not_scheduled.csv

    Note that /schedule shows progress and counts for the scheduling step. It doesn't list the recordings that were created; those are in the downloadJobResults zip

    All paths below start with /api/v1/scheduledRecordings
    Status values are sent as strings: Processing, Completed or Failed

    Before you start

    Authentication. The token has to represent a user. Use a "User Based Server Application" OAuth client and the password grant. A token from client credentials alone (a plain "Server Application" client) has no user attached, and every bulk endpoint rejects it

    POST /oauth2/connect/token
    Content-Type: application/x-www-form-urlencoded
    
    grant_type=password&client_id=...&client_secret=...&username=...&password=...&scope=api
    

    Send the result as Authorization: Bearer <access_token>. That user also needs bulk scheduling permission; otherwise every endpoint returns 403 with error code Forbidden

    Getting the values for your CSV. Two download endpoints help you build the CSV:

    • GET /bulk/downloadResources/sampleSchedule returns a CSV template with every column
    • GET /bulk/downloadResources/resources returns a zip listing the recorders, recorder templates, folders and owners you're allowed to use

    1. Upload the CSV

    The body is raw CSV with Content-Type: text/csv. Don't send JSON or multipart/form-data

    POST /api/v1/scheduledRecordings/bulk/upload
    Authorization: Bearer <token>
    Content-Type: text/csv
    
    Title,Recorder,StartTime,EndTime,Folder,Description,Owner
    "Lecture 1","Room 101 Recorder","2026-11-02T09:00:00Z","2026-11-02T10:00:00Z","Biology 101","Week 1","jane.doe"
    "Lecture 2","Room 101 Recorder","2026-11-04T09:00:00Z","2026-11-04T10:00:00Z","Biology 101","Week 1",
    

    How the columns work:

    • Required: Title (up to 255 characters), Recorder (a name or ID), StartTime and EndTime
    • Optional: StartViewingTime, EndViewingTime, Description, IsWebcast, RecorderTemplate, Owner and Tags.
      • IsWebcast accepts 1/0, true/false or yes/no
      • Owner can be a user ID, a username, or Provider\username. If you leave it blank, the owner is the caller.
      • Tags look like #tag1 #tag2
    • Folder: give either Folder (a name or ID) or FolderExternalContext, never both
    • Ignored on upload: RowIndex, Issue and Details only appear in the result files, so you can re-upload an error file without removing them
    • Formatting: column order doesn't matter, and header names ignore case and spaces. Times are ISO 8601; adding a Z or an explicit offset avoids any time zone ambiguity

    Response: 202 Accepted

    { "jobId": "3f2c9a1e-7b4d-4c8e-9a10-2b6f1d5e8c47" }
    

    Possible errors are 400 InvalidPayload (empty body), 413 PayloadTooLarge (the CSV is over the site's size limit) and 502 WorkerUnavailable

    2. Poll validation

    No request body

    GET /api/v1/scheduledRecordings/bulk/{jobId}/validation
    

    Response: 200 OK

    {
      "jobId": "3f2c9a1e-7b4d-4c8e-9a10-2b6f1d5e8c47",
      "status": "Completed",
      "valid": 2,
      "errors": 0,
      "conflicts": 0,
      "folderCount": 1,
      "recorderCount": 1
    }
    
    • valid: rows that passed validation
    • errors: rows that failed validation
    • conflicts: rows that overlap recordings that are already scheduled
    • fileError: only present when the whole file couldn't be processed. The value is ParseError or TooManyRows

    While validation is still running, status is Processing, so keep polling. The automated tests poll every 2 seconds

    3. Download validation results (optional)

    GET /api/v1/scheduledRecordings/bulk/{jobId}/downloadValidationResults
    

    This returns validation_results.zip. The zip can occasionally return 502 for a few seconds right after validation shows Completed, so retry briefly if that happens

    4. Start scheduling

    There's no JSON body, but send an empty body with Content-Length: 0. Without it, IIS rejects a bodyless POST with 411 Length Required; curl in particular hits this

    POST /api/v1/scheduledRecordings/bulk/{jobId}/start?resolveConflicts=false
    Content-Length: 0
    

    Response: 200 OK

    { "jobId": "3f2c9a1e-7b4d-4c8e-9a10-2b6f1d5e8c47", "status": "Processing" }
    
    • Safe to retry: calling start again on the same job doesn't schedule anything twice. It just returns the current status
    • resolveConflicts=true: only site admins may pass this. Anyone else gets 403
    • Wait for validation first: start doesn't check that validation has finished. Only call it once validation shows Completed and no fileError
    • No email: the API doesn't send the completion email that the web UI sends, so you need to poll the next endpoint

    5. Poll scheduling

    GET /api/v1/scheduledRecordings/bulk/{jobId}/schedule
    

    Response: 200 OK

    {
      "jobId": "3f2c9a1e-7b4d-4c8e-9a10-2b6f1d5e8c47",
      "status": "Completed",
      "scheduled": 2,
      "notScheduled": 0,
      "completedAt": "2026-10-28T10:12:44Z"
    }
    

    completedAt stays null until the job finishes. A 404 here means start hasn't been called for this job yet

    6. Download job results (optional)

    GET /api/v1/scheduledRecordings/bulk/{jobId}/downloadJobResults
    

    This returns execution_results.zip, containing scheduled.csv and not_scheduled.csv

    Errors on any of these endpoints

    • 403 Forbidden: the user lacks bulk scheduling permission
    • 404 NotFound: the job doesn't exist or isn't visible to you
    • 502, 503 or 504 with WorkerUnavailable: the backend is temporarily unavailable or slow. Retry with backoff

    I hope this helps.

    Thanks,

    -Adis

Sign In or Register to comment.