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
Table of Contents
- GET /createMediaPackage
- POST /addAttachment
- POST /addAttachment
- POST /addCatalog
- POST /addCatalog
- POST /addDCCatalog
- POST /addMediaPackage/{wdID}
- POST /addMediaPackage
- POST /addPartialTrack
- POST /addPartialTrack
- POST /addTrack
- POST /addTrack
- POST /addZippedMediaPackage
- POST /addZippedMediaPackage/{workflowDefinitionId}
- PUT /createMediaPackageWithID/{id}
- POST /discardMediaPackage
- POST /ingest
- POST /ingest/{wdID}
- POST /schedule/{wdID}
- POST /schedule
Read methods
| Method / Path: | GET /createMediaPackage |
|---|---|
| Description: | Create an empty media package |
| Path params: | NONE |
| Optional (query) params: | NONE |
| Response formats: | text/xml |
| Status codes: |
200: OK, Returns media package 500: Internal Server Error, NONE |
| Testing: |
Sample:
/createMediaPackage
/ingest/createMediaPackage
|
Write methods
| Method / Path: | POST /addAttachment |
|---|---|
| Description: | Add an attachment to a given media package using an input stream |
| Path params: | NONE |
| Required (form) params: |
flavor: The kind of attachment
mediaPackage: The media package as XML |
| Body (upload) param: | The attachment file |
| Optional (form) params: | tags: The tags of the attachment |
| Response formats: | text/xml |
| Status codes: |
200: OK, Returns augmented media package 400: Bad Request, Media package not valid 500: Internal Server Error, NONE |
| Testing: |
Sample:
/addAttachment
Testing form (click to reveal)
|
| Method / Path: | POST /addAttachment |
|---|---|
| Description: | Add an attachment to a given media package using an URL |
| Path params: | NONE |
| Required (form) params: |
url: The location of the attachment
flavor: The kind of attachment mediaPackage: The media package as XML |
| Optional (form) params: | tags: The tags of the attachment |
| Response formats: | text/xml |
| Status codes: |
200: OK, Returns augmented media package 400: Bad Request, Media package not valid 500: Internal Server Error, NONE |
| Testing: |
Sample:
/addAttachment
Testing form (click to reveal)
|
| Method / Path: | POST /addCatalog |
|---|---|
| Description: | Add a metadata catalog to a given media package using an input stream |
| Path params: | NONE |
| Required (form) params: |
flavor: The kind of media catalog
mediaPackage: The media package as XML |
| Body (upload) param: | The metadata catalog file |
| Optional (form) params: | tags: The tags of the attachment |
| Response formats: | text/xml |
| Status codes: |
200: OK, Returns augmented media package 400: Bad Request, Media package not valid 500: Internal Server Error, NONE |
| Testing: |
Sample:
/addCatalog
Testing form (click to reveal)
|
| Method / Path: | POST /addCatalog |
|---|---|
| Description: | Add a metadata catalog to a given media package using an URL |
| Path params: | NONE |
| Required (form) params: |
url: The location of the catalog
flavor: The kind of catalog mediaPackage: The media package as XML |
| Optional (form) params: | tags: The tags of the catalog |
| Response formats: | text/xml |
| Status codes: |
200: OK, Returns augmented media package 400: Bad Request, Media package not valid 500: Internal Server Error, NONE |
| Testing: |
Sample:
/addCatalog
Testing form (click to reveal)
|
| Method / Path: | POST /addDCCatalog |
|---|---|
| Description: | Add a dublincore episode catalog to a given media package using an url |
| Path params: | NONE |
| Required (form) params: |
mediaPackage: The media package as XML
dublinCore: DublinCore catalog as XML |
| Optional (form) params: | flavor(Default value=dublincore/episode): DublinCore Flavor |
| Response formats: | text/xml |
| Status codes: |
200: OK, Returns augmented media package 400: Bad Request, Media package not valid 500: Internal Server Error, NONE |
| Testing: |
Sample:
/addDCCatalog
Testing form (click to reveal)
|
| Method / Path: | POST /addMediaPackage/{wdID} |
|---|---|
| Description: | Create and ingest media package from media tracks with additional Dublin Core metadata. It is mandatory to set a title for the recording. This can be done with the 'title' form field or by supplying a DC catalog with a title included. The identifier of the newly created media package will be taken from the identifier field or the episode DublinCore catalog (deprecated*). If no identifier is set, a newa randumm UUIDv4 will be generated. This endpoint is not meant to be used by capture agents for scheduled recordings. It's primary use is for manual ingests with command line tools like cURL. Multiple tracks can be ingested by using multiple form fields. It's important, however, to always set the flavor of the next media file before sending the media file itself. (*) The special treatment of the identifier field is deprecated any may be removed in future versions without further notice in favor of a random UUID generation to ensure uniqueness of identifiers.Example cURL command:Ingest one video file:
curl -i -u admin:opencast http://localhost:8080/ingest/addMediaPackage/fast \
-F creator='John Doe' -F title='Test Recording' \
-F 'flavor=presentation/source' -F 'BODY=@test-recording.mp4'
Ingest two video files:
curl -i -u admin:opencast http://localhost:8080/ingest/addMediaPackage/fast \
-F creator='John Doe' -F title='Test Recording' \
-F 'flavor=presentation/source' -F 'BODY=@test-recording-vga.mp4' \
-F 'flavor=presenter/source' -F 'BODY=@test-recording-camera.mp4'
|
| Path params: | wdID: Workflow definition id |
| Required (form) params: | flavor: The kind of media track. This has to be specified prior to each media track |
| Body (upload) param: | The media track file |
| Optional (form) params: |
abstract:
Episode metadata value accessRights: Episode metadata value available: Episode metadata value contributor: Episode metadata value coverage: Episode metadata value created: Episode metadata value creator: Episode metadata value date: Episode metadata value description: Episode metadata value extent: Episode metadata value format: Episode metadata value identifier: Episode metadata value isPartOf: Episode metadata value isReferencedBy: Episode metadata value isReplacedBy: Episode metadata value language: Episode metadata value license: Episode metadata value publisher: Episode metadata value relation: Episode metadata value replaces: Episode metadata value rights: Episode metadata value rightsHolder: Episode metadata value source: Episode metadata value spatial: Episode metadata value subject: Episode metadata value temporal: Episode metadata value title: Episode metadata value type: Episode metadata value episodeDCCatalogUri: URL of episode DublinCore Catalog episodeDCCatalog: Episode DublinCore Catalog seriesDCCatalogUri: URL of series DublinCore Catalog seriesDCCatalog: Series DublinCore Catalog acl: Access control list in XACML or JSON form tag: Tag of the next media file mediaUri: URL of a media track file |
| Response formats: | text/xml |
| Status codes: |
200: OK, Ingest successful. Returns workflow instance as XML 400: Bad Request, Ingest failed due to invalid requests. 409: Conflict, Ingest failed. A workflow is currently active on the media package 500: Internal Server Error, Ingest failed. Something went wrong internally. Please have a look at the log files |
| Testing: |
Sample:
/addMediaPackage/{wdID}
Testing form (click to reveal)
|
| Method / Path: | POST /addMediaPackage |
|---|---|
| Description: | Create and ingest media package from media tracks with additional Dublin Core metadata. It is mandatory to set a title for the recording. This can be done with the 'title' form field or by supplying a DC catalog with a title included. The identifier of the newly created media package will be taken from the identifier field or the episode DublinCore catalog (deprecated*). If no identifier is set, a new random UUIDv4 will be generated. This endpoint is not meant to be used by capture agents for scheduled recordings. Its primary use is for manual ingests with command line tools like cURL. Multiple tracks can be ingested by using multiple form fields. It is important to always set the flavor of the next media file before sending the media file itself. (*) The special treatment of the identifier field is deprecated and may be removed in future versions without further notice in favor of a random UUID generation to ensure uniqueness of identifiers.Example cURL command:Ingest one video file:
curl -i -u admin:opencast http://localhost:8080/ingest/addMediaPackage \
-F creator='John Doe' -F title='Test Recording' \
-F 'flavor=presentation/source' -F 'BODY=@test-recording.mp4'
Ingest two video files:
curl -i -u admin:opencast http://localhost:8080/ingest/addMediaPackage \
-F creator='John Doe' -F title='Test Recording' \
-F 'flavor=presentation/source' -F 'BODY=@test-recording-vga.mp4' \
-F 'flavor=presenter/source' -F 'BODY=@test-recording-camera.mp4'
|
| Path params: | NONE |
| Required (form) params: | flavor: The kind of media track. This has to be specified prior to each media track |
| Body (upload) param: | The media track file |
| Optional (form) params: |
abstract:
Episode metadata value accessRights: Episode metadata value available: Episode metadata value contributor: Episode metadata value coverage: Episode metadata value created: Episode metadata value creator: Episode metadata value date: Episode metadata value description: Episode metadata value extent: Episode metadata value format: Episode metadata value identifier: Episode metadata value isPartOf: Episode metadata value isReferencedBy: Episode metadata value isReplacedBy: Episode metadata value language: Episode metadata value license: Episode metadata value publisher: Episode metadata value relation: Episode metadata value replaces: Episode metadata value rights: Episode metadata value rightsHolder: Episode metadata value source: Episode metadata value spatial: Episode metadata value subject: Episode metadata value temporal: Episode metadata value title: Episode metadata value type: Episode metadata value episodeDCCatalogUri: URL of episode DublinCore Catalog episodeDCCatalog: Episode DublinCore Catalog seriesDCCatalogUri: URL of series DublinCore Catalog seriesDCCatalog: Series DublinCore Catalog acl: Access control list in XACML or JSON form tag: Tag of the next media file mediaUri: URL of a media track file |
| Response formats: | text/xml |
| Status codes: |
200: OK, Ingest successful. Returns workflow instance as xml 400: Bad Request, Ingest failed due to invalid requests. 500: Internal Server Error, Ingest failed. Something went wrong internally. Please have a look at the log files |
| Testing: |
Sample:
/addMediaPackage
Testing form (click to reveal)
|
| Method / Path: | POST /addPartialTrack |
|---|---|
| Description: | Add a partial media track to a given media package using an input stream |
| Path params: | NONE |
| Required (form) params: |
flavor: The kind of media track
startTime: The start time in milliseconds mediaPackage: The media package as XML |
| Body (upload) param: | The media track file |
| Optional (form) params: | NONE |
| Response formats: | text/xml |
| Status codes: |
200: OK, Returns augmented media package 400: Bad Request, Media package not valid 500: Internal Server Error, NONE |
| Testing: |
Sample:
/addPartialTrack
Testing form (click to reveal)
|
| Method / Path: | POST /addPartialTrack |
|---|---|
| Description: | Add a partial media track to a given media package using an URL |
| Path params: | NONE |
| Required (form) params: |
url: The location of the media
flavor: The kind of media startTime: The start time in milliseconds mediaPackage: The media package as XML |
| Optional (form) params: | NONE |
| Response formats: | text/xml |
| Status codes: |
200: OK, Returns augmented media package 400: Bad Request, Media package not valid 500: Internal Server Error, NONE |
| Testing: |
Sample:
/addPartialTrack
Testing form (click to reveal)
|
| Method / Path: | POST /addTrack |
|---|---|
| Description: | Add a media track to a given media package using an input stream |
| Path params: | NONE |
| Required (form) params: |
flavor: The kind of media track
mediaPackage: The media package as XML |
| Body (upload) param: | The media track file |
| Optional (form) params: | tags: The tags of the media track |
| Response formats: | text/xml |
| Status codes: |
200: OK, Returns augmented media package 400: Bad Request, Media package not valid 500: Internal Server Error, NONE |
| Testing: |
Sample:
/addTrack
Testing form (click to reveal)
|
| Method / Path: | POST /addTrack |
|---|---|
| Description: | Add a media track to a given media package using an URL |
| Path params: | NONE |
| Required (form) params: |
url: The location of the media
flavor: The kind of media mediaPackage: The media package as XML |
| Optional (form) params: | tags: The tags of the media track |
| Response formats: | text/xml |
| Status codes: |
200: OK, Returns augmented media package 400: Bad Request, Media package not valid 500: Internal Server Error, NONE |
| Testing: |
Sample:
/addTrack
Testing form (click to reveal)
|
| Method / Path: | POST /addZippedMediaPackage |
|---|---|
| Description: | Create media package from a compressed file containing a manifest.xml document and all media tracks, metadata catalogs and attachments |
| Path params: | NONE |
| Body (upload) param: | The compressed (application/zip) media package file |
| Optional (form) params: |
workflowDefinitionId:
The workflow definition ID to run on this mediapackage. This parameter has to be set in the request prior to the zipped mediapackage (This parameter is deprecated. Please use /addZippedMediaPackage/{workflowDefinitionId} instead) workflowInstanceId: The workflow instance ID to associate with this zipped mediapackage. This parameter has to be set in the request prior to the zipped mediapackage (This parameter is deprecated. Please use /addZippedMediaPackage/{workflowDefinitionId} with a path parameter instead) |
| Response formats: | text/xml |
| Status codes: |
200: OK, NONE 400: Bad Request, NONE 404: Not Found, NONE 503: Service Unavailable, NONE |
| Testing: |
Sample:
/addZippedMediaPackage
Testing form (click to reveal)
|
| Method / Path: | POST /addZippedMediaPackage/{workflowDefinitionId} |
|---|---|
| Description: | Create media package from a compressed file containing a manifest.xml document and all media tracks, metadata catalogs and attachments |
| Path params: | workflowDefinitionId: Workflow definition id |
| Body (upload) param: | The compressed (application/zip) media package file |
| Optional (form) params: | workflowInstanceId: The workflow instance ID to associate with this zipped mediapackage |
| Response formats: | text/xml |
| Status codes: |
200: OK, NONE 400: Bad Request, NONE 404: Not Found, NONE 503: Service Unavailable, NONE |
| Testing: |
Sample:
/addZippedMediaPackage/{workflowDefinitionId}
Testing form (click to reveal)
|
| Method / Path: | PUT /createMediaPackageWithID/{id} |
|---|---|
| Description: | Create an empty media package with ID /n Overrides Existing Mediapackage |
| Path params: | id: The Id for the new Mediapackage |
| Optional (form) params: | NONE |
| Response formats: | text/xml |
| Status codes: |
200: OK, Returns media package 500: Internal Server Error, NONE |
| Testing: |
Sample:
/createMediaPackageWithID/{id}
Testing form (click to reveal)
|
| Method / Path: | POST /discardMediaPackage |
|---|---|
| Description: | Discard a media package |
| Path params: | NONE |
| Required (form) params: | mediaPackage: Given media package to be destroyed |
| Optional (form) params: | NONE |
| Status codes: |
200: OK, NONE 500: Internal Server Error, NONE |
| Testing: |
Sample:
/discardMediaPackage
Testing form (click to reveal)
|
| Method / Path: | POST /ingest |
|---|---|
| Description: | Ingest the completed media package into the system In addition to the documented form parameters, workflow parameters are accepted as well. |
| Path params: | NONE |
| Required (form) params: | mediaPackage: The media package |
| Optional (form) params: |
workflowDefinitionId:
Workflow definition id workflowInstanceId: The workflow instance ID to associate this ingest with scheduled events. |
| Response formats: | text/xml |
| Status codes: |
200: OK, Returns the workflow instance 400: Bad Request, Media package not valid |
| Testing: |
Sample:
/ingest
Testing form (click to reveal)
|
| Method / Path: | POST /ingest/{wdID} |
|---|---|
| Description: | Ingest the completed media package into the system and start a specified workflow. In addition to the documented form parameters, workflow parameters are accepted as well. |
| Path params: | wdID: Workflow definition id |
| Required (form) params: | mediaPackage: The media package as XML |
| Optional (form) params: | NONE |
| Response formats: | text/xml |
| Status codes: |
200: OK, Returns the workflow instance 400: Bad Request, Media package not valid |
| Testing: |
Sample:
/ingest/{wdID}
Testing form (click to reveal)
|
| Method / Path: | POST /schedule/{wdID} |
|---|---|
| Description: | Schedule an event based on the given media package |
| Path params: | wdID: Workflow definition id |
| Required (form) params: | mediaPackage: The media package |
| Optional (form) params: | NONE |
| Status codes: |
201: Created, Event scheduled 400: Bad Request, Media package not valid |
| Testing: |
Sample:
/schedule/{wdID}
Testing form (click to reveal)
|
| Method / Path: | POST /schedule |
|---|---|
| Description: | Schedule an event based on the given media package |
| Path params: | NONE |
| Required (form) params: | mediaPackage: The media package |
| Optional (form) params: | NONE |
| Status codes: |
201: Created, Event scheduled 400: Bad Request, Media package not valid |
| Testing: |
Sample:
/schedule
Testing form (click to reveal)
|