Scheduler Service REST Documentation

General Notes

All paths above are relative to the REST endpoint base (something like http://your.server/files)
If the service is down or not working it will return a status 503, this means the the underlying service is not working and is either restarting or has failed
A status code 500 means a general failure has occurred which is not recoverable and was not anticipated. In other words, there is a bug! You should file an error report with your server logs from the time when the error occurred: Opencast Issue Tracker

Read methods

Method / Path: GET /{id}/lastmodified

Description: Retrieves the last modified hash for specified agent

Path params: id: ID of capture agent for which the last modified hash will be retrieved

Optional (query) params: NONE

Response formats: text/plain

Status codes: 200: OK, The last modified hash of agent is in the body of response

Notes:

Return value description: The last modified hash

Testing:

Sample: /{id}/lastmodified

Testing form (click to reveal)

Method / Path: GET /conflicts.{type:xml|json}

Description: Searches for conflicting recordings based on parameters and returns result as XML or JSON

Path params: type: The media type of the response [xml|json]

Required (form) params: agent: Device identifier for which conflicts will be searched
start: Start time of conflicting period, in milliseconds
end: End time of conflicting period, in milliseconds

Optional (query) params: rrule: Rule for recurrent conflicting, specified as: "FREQ=WEEKLY;BYDAY=day(s);BYHOUR=hour;BYMINUTE=minute". FREQ is required. BYDAY may include one or more (separated by commas) of the following: SU,MO,TU,WE,TH,FR,SA.
duration(Default value=0): If recurrence rule is specified duration of each conflicting period, in milliseconds
timezone: The timezone of the capture device

Response formats: application/xml
application/json

Status codes: 204: No Content, No conflicting events found
200: OK, Found conflicting events, returned in body of response
400: Bad Request, Missing or invalid parameters
401: Unauthorized, Not authorized to make this request
500: Internal Server Error, A detailed stack track of the internal issue.

Notes:

Return value description: Returns NO CONTENT if no recordings are in conflict within specified period or list of conflicting recordings in XML or JSON

Testing:

Sample: /conflicts.{type:xml|json}?rrule={rrule}&duration=0&timezone={timezone}

Testing form (click to reveal)

Form action: /recordings/conflicts.{type:xml|json}

* type:		The media type of the response [xml\|json]
* agent:		Device identifier for which conflicts will be searched
* start:		Start time of conflicting period, in milliseconds
* end:		End time of conflicting period, in milliseconds
rrule:		Rule for recurrent conflicting, specified as: "FREQ=WEEKLY;BYDAY=day(s);BYHOUR=hour;BYMINUTE=minute". FREQ is required. BYDAY may include one or more (separated by commas) of the following: SU,MO,TU,WE,TH,FR,SA.
duration:		If recurrence rule is specified duration of each conflicting period, in milliseconds
timezone:		The timezone of the capture device

Response:

Method / Path: GET /conflicts.json

Description: Searches for conflicting recordings based on parameters

Path params: NONE

Response formats: application/json

Notes:

Return value description: Returns NO CONTENT if no recordings are in conflict within specified period or list of conflicting recordings in JSON

Testing:

Sample: /conflicts.json?rrule={rrule}&duration=0&timezone={timezone}

Testing form (click to reveal)

Method / Path: GET /capture/{agent}

Description: Get the current capture event catalog as JSON

Path params: agent: The agent identifier

Optional (query) params: NONE

Response formats: application/json

Status codes: 200: OK, DublinCore of current capture event is in the body of response
404: Not Found, There is no ongoing recording
503: Service Unavailable, The agent is not ready to communicate

Notes:

Return value description: The current capture event catalog as JSON

Testing:

Sample: /capture/{agent}

Testing form (click to reveal)

Method / Path: GET /currentRecording/{agent}

Description: Get the current capture event as XML

Path params: agent: The agent identifier

Optional (query) params: NONE

Response formats: text/xml

Status codes: 200: OK, current event is in the body of response
204: No Content, There is no current recording

Notes:

Return value description: The current capture event as XML

Testing:

Sample: /currentRecording/{agent}

Testing form (click to reveal)

Method / Path:	GET /eventCount
Description:	Get the number of scheduled events
Path params:	NONE
Optional (query) params:	NONE
Response formats:	text/plain
Status codes:	`200: OK`, The event count
Notes:	Return value description: The number of scheduled events
Testing:	Sample: `/eventCount` /recordings/eventCount

Method / Path:	GET /recordingStatus
Description:	Return all registered recordings and their state
Path params:	NONE
Optional (query) params:	NONE
Response formats:	application/json
Status codes:	`200: OK`, Returns all known recordings.
Testing:	Sample: `/recordingStatus` /recordings/recordingStatus

Method / Path: GET /calendars

Description: Returns iCalendar for specified set of events

Path params: NONE

Optional (query) params: agentid: Filter events by capture agent
seriesid: Filter events by series
cutoff(Default value=0): A cutoff date in UNIX milliseconds to limit the number of events returned in the calendar.

Response formats: text/calendar

Status codes: 304: Not Modified, Events were not modified since last request
200: OK, Events were modified, new calendar is in the body

Notes:

Return value description: ICalendar for events

Testing:

Sample: /calendars?agentid={agentid}&seriesid={seriesid}&cutoff=0

Testing form (click to reveal)

Method / Path: GET /calendar.json

Description: Returns a calendar in JSON format for specified events. This endpoint is not yet stable and might change in the future with no priot notice.

Path params: NONE

Optional (query) params: agentid: Filter events by capture agent
cutoff(Default value=0): A cutoff date in UNIX milliseconds to limit the number of events returned in the calendar.

Response formats: application/json

Status codes: 304: Not Modified, Events were not modified since last request
200: OK, Events were modified, new calendar is in the body

Notes:

Return value description: Calendar for events in JSON format

Testing:

Sample: /calendar.json?agentid={agentid}&cutoff=0

Testing form (click to reveal)

Method / Path: GET /{id:.+}/mediapackage.xml

Description: Retrieves media package for specified event

Path params: id: ID of event for which media package will be retrieved

Optional (query) params: NONE

Response formats: text/xml

Status codes: 200: OK, DublinCore of event is in the body of response
404: Not Found, Event with specified ID does not exist
401: Unauthorized, You do not have permission to remove the event. Maybe you need to authenticate.

Notes:

Return value description: media package in XML

Testing:

Sample: /{id:.+}/mediapackage.xml

Testing form (click to reveal)

Method / Path: GET /{id}/recordingStatus

Description: Return the state of a given recording

Path params: id: The ID of a given recording

Optional (query) params: NONE

Response formats: application/json

Status codes: 200: OK, Returns the state of the recording with the correct id
404: Not Found, The recording with the specified ID does not exist

Testing:

Sample: /{id}/recordingStatus

Testing form (click to reveal)

Method / Path: GET /{id:.+}/technical.json

Description: Retrieves the technical metadata for specified event

Path params: id: ID of event for which the technical metadata will be retrieved

Optional (query) params: NONE

Response formats: text/xml

Status codes: 200: OK, technical metadata of event is in the body of response
404: Not Found, Event with specified ID does not exist
401: Unauthorized, You do not have permission to remove the event. Maybe you need to authenticate.

Notes:

Return value description: technical metadata as JSON

Testing:

Sample: /{id:.+}/technical.json

Testing form (click to reveal)

Method / Path: GET /{id:.+}/workflow.properties

Description: Retrieves workflow configuration for specified event

Path params: id: ID of event for which workflow configuration will be retrieved

Optional (query) params: NONE

Response formats: text/plain

Status codes: 200: OK, workflow configuration of event is in the body of response
404: Not Found, Event with specified ID does not exist
401: Unauthorized, You do not have permission to remove the event. Maybe you need to authenticate.

Notes:

Return value description: workflow configuration in the form of key, value pairs

Testing:

Sample: /{id:.+}/workflow.properties

Testing form (click to reveal)

Method / Path: GET /{id:.+}/agent.properties

Description: Retrieves Capture Agent properties for specified event

Path params: id: ID of event for which agent properties will be retrieved

Optional (query) params: NONE

Response formats: text/plain

Status codes: 200: OK, Capture Agent properties of event is in the body of response
404: Not Found, Event with specified ID does not exist
401: Unauthorized, You do not have permission to remove the event. Maybe you need to authenticate.

Notes:

Return value description: Capture Agent properties in the form of key, value pairs

Testing:

Sample: /{id:.+}/agent.properties

Testing form (click to reveal)

Method / Path: GET /{id:.+}/dublincore.json

Description: Retrieves DublinCore for specified event

Path params: id: ID of event for which DublinCore will be retrieved

Optional (query) params: NONE

Response formats: application/json

Notes:

Return value description: DublinCore in JSON

Testing:

Sample: /{id:.+}/dublincore.json

Testing form (click to reveal)

Method / Path: GET /recordings.{type:xml|json}

Description: Searches recordings and returns result as XML or JSON

Path params: type: The media type of the response [xml|json]

Optional (query) params: agent: Search by device
startsfrom(Default value=0): Search by when does event start
startsto(Default value=0): Search by when does event start
endsfrom(Default value=0): Search by when does event finish
endsto(Default value=0): Search by when does event finish

Response formats: application/xml
application/json

Status codes: 200: OK, Search completed, results returned in body

Notes:

Return value description: XML or JSON formated results

Testing:

Sample: /recordings.{type:xml|json}?agent={agent}&startsfrom=0&startsto=0&endsfrom=0&endsto=0

Testing form (click to reveal)

Method / Path: GET /{id:.+}/dublincore.xml

Description: Retrieves DublinCore for specified event

Path params: id: ID of event for which DublinCore will be retrieved

Optional (query) params: NONE

Response formats: text/xml

Notes:

Return value description: DublinCore in XML

Testing:

Sample: /{id:.+}/dublincore.xml

Testing form (click to reveal)

Method / Path: GET /capture/{agent}/upcoming

Description: Get the upcoming capture event catalog as JSON

Path params: agent: The agent identifier

Optional (query) params: NONE

Response formats: application/json

Status codes: 200: OK, DublinCore of the upcomfing capture event is in the body of response
404: Not Found, There is no upcoming recording
503: Service Unavailable, The agent is not ready to communicate

Notes:

Return value description: The upcoming capture event catalog as JSON

Testing:

Sample: /capture/{agent}/upcoming

Testing form (click to reveal)

Method / Path: GET /upcomingRecording/{agent}

Description: Get the upcoming capture event as XML

Path params: agent: The agent identifier

Optional (query) params: NONE

Response formats: text/xml

Status codes: 200: OK, upcoming event is in the body of response
204: No Content, There is no upcoming recording

Notes:

Return value description: The upcoming capture event as XML

Testing:

Sample: /upcomingRecording/{agent}

Testing form (click to reveal)

Write methods

Method / Path: DELETE /{id:.+}

Description: Removes scheduled event with specified ID.

Path params: id: Event ID

Optional (query) params: NONE

Response formats: text/plain

Status codes: 200: OK, Event was successfully removed
404: Not Found, Event with specified ID does not exist
401: Unauthorized, You do not have permission to remove the event. Maybe you need to authenticate.
409: Conflict, Event with specified ID is locked by a transaction, unable to delete event.

Notes:

Return value description: OK if event were successfully removed or NOT FOUND if event with specified ID does not exist

Testing:

Sample: /{id:.+}

Testing form (click to reveal)

Method / Path: POST /

Description: Creates new event with specified parameters

Path params: NONE

Required (form) params: start: The start date of the event in milliseconds from 1970-01-01T00:00:00Z
end: The end date of the event in milliseconds from 1970-01-01T00:00:00Z
agent: The agent of the event
mediaPackage: The media package of the event

Optional (form) params: users: Comma separated list of user ids (speakers/lecturers) for the event
wfproperties: Workflow configuration keys for the event. Each key will be prefixed by 'org.opencastproject.workflow.config.' and added to the capture agent parameters.
agentparameters: The capture agent properties for the event
source: The scheduling source of the event

Status codes: 201: Created, Event is successfully created
409: Conflict, Unable to create event, conflicting events found (ConflicsFound)
409: Conflict, Unable to create event, event locked by a transaction (TransactionLock)
401: Unauthorized, You do not have permission to create the event. Maybe you need to authenticate.
400: Bad Request, Missing or invalid information for this request

Notes:

Return value description: If an event was successfully created

Testing:

Sample: /

Testing form (click to reveal)

Form action: /recordings/

* start:		The start date of the event in milliseconds from 1970-01-01T00:00:00Z
* end:		The end date of the event in milliseconds from 1970-01-01T00:00:00Z
* agent:		The agent of the event
mediaPackage: The media package of the event
users:		Comma separated list of user ids (speakers/lecturers) for the event
wfproperties: Workflow configuration keys for the event. Each key will be prefixed by 'org.opencastproject.workflow.config.' and added to the capture agent parameters.
agentparameters: The capture agent properties for the event
source:		The scheduling source of the event

Response:

Method / Path: POST /multiple

Description: Creates new event with specified parameters

Path params: NONE

Required (form) params: rrule: The recurrence rule for the events
start: The start date of the event in milliseconds from 1970-01-01T00:00:00Z
end: The end date of the event in milliseconds from 1970-01-01T00:00:00Z
duration: The duration of the events in milliseconds
tz: The timezone of the events
agent: The agent of the event
templateMp: The template mediapackage for the events

Notes:

Return value description: If an event was successfully created

Testing:

Sample: /multiple

Testing form (click to reveal)

Form action: /recordings/multiple

* rrule:		The recurrence rule for the events
* start:		The start date of the event in milliseconds from 1970-01-01T00:00:00Z
* end:		The end date of the event in milliseconds from 1970-01-01T00:00:00Z
* duration:		The duration of the events in milliseconds
* tz:		The timezone of the events
* agent:		The agent of the event
templateMp: The template mediapackage for the events
users:		Comma separated list of user ids (speakers/lecturers) for the event
wfproperties: Workflow configuration keys for the event. Each key will be prefixed by 'org.opencastproject.workflow.config.' and added to the capture agent parameters.
agentparameters: The capture agent properties for the event
source:		The scheduling source of the event

Response:

Method / Path: PUT /capture/{agent}/prolong

Description: Prolong an immediate capture.

Path params: agent: The agent identifier

Optional (form) params: NONE

Response formats: text/plain

Status codes: 200: OK, Recording prolonged
404: Not Found, No recording found for prolonging
401: Unauthorized, You do not have permission to prolong this immediate capture. Maybe you need to authenticate.
503: Service Unavailable, The agent is not ready to communicate

Notes:

Return value description: OK if event were successfully prolonged

Testing:

Sample: /capture/{agent}/prolong

Testing form (click to reveal)

Method / Path: POST /removeOldScheduledRecordings

Description: This will find and remove any scheduled events before the buffer time to keep performance in the scheduler optimum.

Path params: NONE

Required (form) params: buffer: The amount of seconds before now that a capture has to have stopped capturing. It must be 0 or greater.

Optional (form) params: NONE

Status codes: 200: OK, Removed old scheduled recordings.
400: Bad Request, Unable to parse buffer.
401: Unauthorized, You do not have permission to remove old schedulings. Maybe you need to authenticate.

Notes:

Return value description: No return value

Testing:

Sample: /removeOldScheduledRecordings

Testing form (click to reveal)

Method / Path: DELETE /{id}/recordingStatus

Description: Remove record of a given recording

Path params: id: The ID of a given recording

Optional (query) params: NONE

Status codes: 200: OK, {id} removed
400: Bad Request, {id} is empty
404: Not Found, Recording with {id} could not be found

Testing:

Sample: /{id}/recordingStatus

Testing form (click to reveal)

Method / Path: POST /capture/{agent}

Description: Create an immediate event

Path params: agent: The agent identifier

Optional (form) params: workflowDefinitionId: The workflow definition id to use

Status codes: 201: Created, Recording started
404: Not Found, There is no such agent
409: Conflict, The agent is already recording
401: Unauthorized, You do not have permission to start this immediate capture. Maybe you need to authenticate.
503: Service Unavailable, The agent is not ready to communicate

Notes:

Return value description: If events were successfully generated, status CREATED is returned

Testing:

Sample: /capture/{agent}

Testing form (click to reveal)

Method / Path: DELETE /capture/{agent}

Description: Stops an immediate capture.

Path params: agent: The agent identifier

Optional (query) params: NONE

Response formats: text/plain

Status codes: 200: OK, Recording stopped
304: Not Modified, The recording was already stopped
404: Not Found, There is no such agent
401: Unauthorized, You do not have permission to stop this immediate capture. Maybe you need to authenticate.
503: Service Unavailable, The agent is not ready to communicate

Notes:

Return value description: OK if event were successfully stopped

Testing:

Sample: /capture/{agent}

Testing form (click to reveal)

Method / Path: PUT /{id}

Description: Updates specified event

Path params: id: ID of event to be updated

Optional (form) params: start(Default value=0): Updated start date for event
end(Default value=0): Updated end date for event
agent: Updated agent for event
users: Updated comma separated list of user ids (speakers/lecturers) for the event
mediaPackage: Updated media package for event
wfproperties: Workflow configuration properties
agentparameters: Updated Capture Agent properties

Status codes: 200: OK, Event was successfully updated
404: Not Found, Event with specified ID does not exist
409: Conflict, Unable to update event, conflicting events found (ConflicsFound)
409: Conflict, Unable to update event, event locked by a transaction (TransactionLock)
403: Forbidden, Event with specified ID cannot be updated
401: Unauthorized, You do not have permission to update the event. Maybe you need to authenticate.
400: Bad Request, Data is missing or invalid

Notes:

Return value description: Status OK is returned if event was successfully updated, NOT FOUND if specified event does not exist or BAD REQUEST if data is missing or invalid

Testing:

Sample: /{id}

Testing form (click to reveal)

Method / Path: PUT /{id}/recordingStatus

Description: Set the status of a given recording, registering it if it is new

Path params: id: The ID of a given recording

Required (form) params: state: The state of the recording. Must be one of the following: unknown, capturing, capture_finished, capture_error, manifest, manifest_error, manifest_finished, compressing, compressing_error, uploading, upload_finished, upload_error.

Optional (form) params: NONE

Status codes: 200: OK, {id} set to {state}
400: Bad Request, {id} or state {state} is empty or the {state} is not known
404: Not Found, Recording with {id} could not be found

Testing:

Sample: /{id}/recordingStatus

Testing form (click to reveal)

Scheduler Service REST Documentation

General Notes

Table of Contents

Read methods

Write methods