Workflow of bulk scheduling via ScheduledRecordings API
in API
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:
- Create a bulk upload request and get a job ID using:
POST /api/v1/scheduledRecordings/bulk/upload - Start the scheduling using:
POST /api/v1/scheduledRecordings/bulk/{jobId}/start - Check the validation of the scheduling to see if the upload was successful:
GET /api/v1/scheduledRecordings/bulk/{jobId}/validation - 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:
0
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, becausestartis the step that creates the recordings.The real workflow:
POST /bulk/uploadsends the CSV and returns ajobId. Validation then runs in the backgroundGET /bulk/{jobId}/validation: poll untilstatusisCompleted, then check the countsGET /bulk/{jobId}/downloadValidationResultsreturns a zip withvalidated.csv,errors.csvandconflicts.csv, so you can see which rows failed and whyPOST /bulk/{jobId}/startbegins scheduling the rows that passed validationGET /bulk/{jobId}/schedule: poll untilstatusisCompletedorFailed. It returns 404 if scheduling hasn't been started yetGET /bulk/{jobId}/downloadJobResultsreturns a zip withscheduled.csvandnot_scheduled.csvNote that
/scheduleshows progress and counts for the scheduling step. It doesn't list the recordings that were created; those are in thedownloadJobResultszipAll paths below start with
/api/v1/scheduledRecordingsStatus values are sent as strings:
Processing,CompletedorFailedBefore 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
Send the result as
Authorization: Bearer <access_token>. That user also needs bulk scheduling permission; otherwise every endpoint returns403with error codeForbiddenGetting the values for your CSV. Two download endpoints help you build the CSV:
GET /bulk/downloadResources/sampleSchedulereturns a CSV template with every columnGET /bulk/downloadResources/resourcesreturns a zip listing the recorders, recorder templates, folders and owners you're allowed to use1. Upload the CSV
The body is raw CSV with
Content-Type: text/csv. Don't send JSON or multipart/form-dataHow the columns work:
Title(up to 255 characters),Recorder(a name or ID),StartTimeandEndTimeStartViewingTime,EndViewingTime,Description,IsWebcast,RecorderTemplate,OwnerandTags.IsWebcastaccepts1/0,true/falseoryes/noOwnercan be a user ID, a username, orProvider\username. If you leave it blank, the owner is the caller.Tagslook like#tag1 #tag2Folder(a name or ID) orFolderExternalContext, never bothRowIndex,IssueandDetailsonly appear in the result files, so you can re-upload an error file without removing themZor an explicit offset avoids any time zone ambiguityResponse:
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) and502 WorkerUnavailable2. Poll validation
No request body
GET /api/v1/scheduledRecordings/bulk/{jobId}/validationResponse:
200 OK{ "jobId": "3f2c9a1e-7b4d-4c8e-9a10-2b6f1d5e8c47", "status": "Completed", "valid": 2, "errors": 0, "conflicts": 0, "folderCount": 1, "recorderCount": 1 }valid: rows that passed validationerrors: rows that failed validationconflicts: rows that overlap recordings that are already scheduledfileError: only present when the whole file couldn't be processed. The value isParseErrororTooManyRowsWhile validation is still running,
statusisProcessing, so keep polling. The automated tests poll every 2 seconds3. Download validation results (optional)
GET /api/v1/scheduledRecordings/bulk/{jobId}/downloadValidationResultsThis returns
validation_results.zip. The zip can occasionally return 502 for a few seconds right after validation showsCompleted, so retry briefly if that happens4. Start scheduling
There's no JSON body, but send an empty body with
Content-Length: 0. Without it, IIS rejects a bodyless POST with411 Length Required; curl in particular hits thisPOST /api/v1/scheduledRecordings/bulk/{jobId}/start?resolveConflicts=false Content-Length: 0Response:
200 OK{ "jobId": "3f2c9a1e-7b4d-4c8e-9a10-2b6f1d5e8c47", "status": "Processing" }startagain on the same job doesn't schedule anything twice. It just returns the current statusresolveConflicts=true: only site admins may pass this. Anyone else gets403startdoesn't check that validation has finished. Only call it once validation showsCompletedand nofileError5. Poll scheduling
GET /api/v1/scheduledRecordings/bulk/{jobId}/scheduleResponse:
200 OK{ "jobId": "3f2c9a1e-7b4d-4c8e-9a10-2b6f1d5e8c47", "status": "Completed", "scheduled": 2, "notScheduled": 0, "completedAt": "2026-10-28T10:12:44Z" }completedAtstaysnulluntil the job finishes. A404here meansstarthasn't been called for this job yet6. Download job results (optional)
GET /api/v1/scheduledRecordings/bulk/{jobId}/downloadJobResultsThis returns
execution_results.zip, containingscheduled.csvandnot_scheduled.csvErrors on any of these endpoints
403 Forbidden: the user lacks bulk scheduling permission404 NotFound: the job doesn't exist or isn't visible to you502,503or504withWorkerUnavailable: the backend is temporarily unavailable or slow. Retry with backoffI hope this helps.
Thanks,
-Adis