Change the state of a registered app

Change the state of a registered app _This endpoint requires the role: portal_administrator_

List user tokens

List User Tokens Note: This view only works with Basic Authentication on purpose - i.e. username and password are required for every request. This view cannot be used from Help > REST API Reference (Swagger UI). Returns two lists, one with the tokens the user created and another with the tokens the user can use. If the user has administration role, he will also receive another key called "tokens" in the response, with all the system tokens. _This endpoint require logged in user but no particular roles. This view supports only Basic Authentication._

Create new tokens

Endpoint to create new tokens Note: This view only works with Basic Authentication on purpose - i.e. username and password are required for every request. This view cannot be used from Help > REST API Reference (Swagger UI). WARNING: When creating a new token using this endpoint, the key will be in the answer, in it will be the only time that the full token will be available, later we don't fully show the token anymore. If the user has no administrator role, he will not be able to create tokens for other than himself, so in this case, the "assignee" should be himself. _This endpoint require logged in user but no particular roles. This view supports only Basic Authentication._

Update created tokens

Request to update created tokens (just name and description) Note: This view only works with Basic Authentication on purpose - i.e. username and password are required for every request. This view cannot be used from Help > REST API Reference (Swagger UI). If the user has no administrator role, he will not be able to edit tokens which are not assigned/created to/by him. _This endpoint require logged in user but no particular roles. This view supports only Basic Authentication._

Remove a token

Request to remove a token This view cannot be used from Help > REST API Reference (Swagger UI). If the user has no administrator role,he will not be able to delete tokens which are not assigned/created to/by him. _This endpoint require logged in user but no particular roles. This view supports only Basic Authentication._

Update created token with token id

Request to update created tokens (just name and description) Note: This view only works with Basic Authentication on purpose - i.e. username and password are required for every request. This view cannot be used from Help > REST API Reference (Swagger UI). If the user has no administrator role, he will not be able to edit tokens which are not assigned/created to/by him. _This endpoint require logged in user but no particular roles. This view supports only Basic Authentication._

Remove a token with token id

Request to remove a token This view cannot be used from Help > REST API Reference (Swagger UI). If the user has no administrator role,he will not be able to delete tokens which are not assigned/created to/by him. _This endpoint require logged in user but no particular roles. This view supports only Basic Authentication._

List collections

List collections _This endpoint requires the role: portal_api_collections_read_

Create a collection

Create collection. The input can be sent as JSON or as form data. _This endpoint requires the role: portal_api_collections_write_

Search for collections

Search for collections _This endpoint requires the role: portal_api_collections_read_

Add content to a collection

Add content to a collection Items can either be listed explicitly, or they could be given as a search id with a possible ignore list for excluding specific items from that search. Only one of selected_objects or search_id can be given. The actual addition of content will be performed in the background after the call has returned. The supplied body will determine what a collection the content will be added to. Example Body [ {"id": "VX-1"} ] _This endpoint requires the role: portal_api_collections_content_add_

Get an individual collection

Get an individual collection _This endpoint requires the role: portal_api_collections_read_

Delete collection

Delete collection _This endpoint requires the role: portal_api_collections_delete_

Get all acl entries for a given collection

Get all acl entries for a given collection. All query parameters can be supplied as simple string or a comma separated list _This endpoint requires the role: portal_api_collections_acl_read_

Given a list of ACL objects, enforce the acl on the collection

Given a list of ACL objects, enforce the acl on the collection. Example body: [ { "source_name": "base", "source": "USER", "permission": "WRITE", "priority": "DEFAULT" }, { "source_name": "BaseGroup", "source": "GROUP", "permission": "READ", "priority": "DEFAULT" } ] _This endpoint requires the role: portal_api_collections_acl_write_

Delete acl entry for collection

Delete acl entry for collection. All query parameters can be supplied as simple string or a comma separated list. _This endpoint requires the role: portal_api_collections_acl_delete_

View the acl entry for collection

Given a collection_id and a acl_id, view the acl entry for collection. _This endpoint requires the role: portal_api_collections_acl_read_

Delete acl entry for collection

Given a collection_id and a acl_id, delete acl entry for collection. _This endpoint requires the role: portal_api_collections_acl_delete_

Get the content of a collection

Get the content of a collection _This endpoint requires the role: portal_api_collections_read_

Move items or collections

Move items or collections from one collection to another. Example - move collection CMO-2 from collection CMO-3 to collection CMO-1: PUT /API/v2/collections/CMO-1/content/ {"collection_ids": ["CMO-2"], "from_collection_id": "CMO-3"} If the moved collection or item has no current parent collection, "from_collection_id" should be omitted. For the special case of a collection with multiple parents, "from_collection_id" can be a list of IDs: "from_collection_id": ["CMO-3", "CMO-42", "CMO-100"] _This endpoint requires the role: portal_api_collections_write_

Remove content from a collection

Remove content from a collection Items can either be listed explicitly, or they could be given as a search id with a possible ignore list for excluding specific items from that search. Only one of selected_objects or search_id can be given. The actual removal of the content will be performed in the background after the call has returned. _This endpoint requires the role: portal_api_collections_content_remove_

Get the collections metadata

Get the collections metadata _This endpoint requires the role: portal_api_collections_metadata_read_

Rename a collection

Given a body containing a new collection name, rename the collection Example body: { "new_collection_name": "NewCollectionName" } _This endpoint requires the role: portal_api_collections_rename_

Get all comments on an asset

Get all comments on an asset. _This endpoint supports authentication with `security_key` and requires the role: portal_api_comments_read_

Add a new comment to an asset

Add a new comment to an asset. Comment data can be sent in as JSON, XML or form parameters, for example: {"comment":"Comment posted with API"} Custom metadata cannot be sent in through this end-point, such can be added separately with PATCH on `/API/v2/comments/{asset_type}/{asset_id}/{comment_path}/` Returns the UUID path, a list of UUIDs, of the new comment, for example: {"uuid_path":["d22c64fb-e698-4056-b91e-9fa1bbfce624", "f841298b-d3de-4f41-a84f-4cef662e5025"]} _This endpoint supports authentication with `security_key` and requires the role: portal_api_comments_write_

Get the number of comments on an asset

Get the number of comments on an asset. _This endpoint supports authentication with `security_key` and requires the role: portal_api_comments_read_

Get details of a comment

Get details of a comment and its replies. _This endpoint supports authentication with `security_key` and requires the role: portal_api_comments_read_

Update comment details

Update comment details On success returns with status 204 and an empty body. User doing the request must either be admin, or the user who created the comment. Patch data can be sent in as form parameters, or as JSON/XML, for example to set a comment as removed: { "is_removed": true } Or to modify comment test: { "text": "This is the new comment text." } Some of the comment fields like "end_tc", "removed_datetime", "replies", "start_tc", "text_modified_datetime", "user_email", "user_username", and "uuid_path", are not modifiable. Custom metadata fields are supported and should be referenced by their full field name, for example adding a Language-field with the value FINNISH, and a Description, to a comment: { "portal_mf257027": "fi", "portal_mf619153": "A description for this comment" } Please note that this API is limited to one value per metadata field. For more complex custom metadata, the Vidispine metadata APIs should be used. _This endpoint supports authentication with `security_key` and requires the role: portal_api_comments_write_

Delete a comment

Delete a comment and all its replies. Note: Comments removed with this end-point are not recoverable. _This endpoint supports authentication with `security_key` and requires the role: portal_api_comments_delete_

Return the size of system databases and tables over time

Return the size of system databases and tables over time. (BETA) Example response: { "history": { "tables": { "t_auditlog": { "2020-05-14": 56991744, "name": "AuditTrail", "2020-05-13": 56991744 }, "t_transferlog": { "2020-05-14": 229376, "name": "Transferlog", "2020-05-13": 229376 }, "t_changelog": { "2020-05-14": 172032, "name": "Changelog", "2020-05-13": 172032 }, "t_joblog": { "2020-05-14": 3497984, "name": "Joblog", "2020-05-13": 3497984 } }, "databases": { "activiti": { "2020-05-14": 9402904, "name": "Activiti", "2020-05-13": 9402904 }, "vidispine": { "2020-05-14": 261323288, "name": "Vidispine", "2020-05-13": 261323288 }, "portal": { "2020-05-14": 291502616, "name": "Portal", "2020-05-13": 291486232 } }, "dates": [ "2020-05-13", "2020-05-14" ] } } This endpoint is in "beta" state, meaning backwards incompatible changes may be introduced in future releases. _This endpoint requires the role: portal_administrator_

Returns a JSON object of the current database purging configuration

Returns a JSON object of the current database purging configuration (BETA) Example response: { "changeLog": { "purgingTime": 1, "forcePurgingTime": 1, "purgingTimeSelector": "Days" }, "job": { "purgingTime": 1, "purgingDirectory": "job_purging/folder/path", "purgingTimeSelector": "Days" "purgingCompress": true, "purgingBatch": 1 }, "auditTrail": { "purgingTime": 1, "forcePurgingTime": 1, "purgingDirectory": "auditTrail_purging/folder/path", "purgingTimeSelector": "Days" "purgingCompress": true, "purgingBatch": 1 }, "transferLog": { "purgingTime": 1, "forcePurgingTime": 1, "purgingDirectory": "transferLog_purging/folder/path", "purgingTimeSelector": "Days" "purgingCompress": true, "purgingBatch": 1 } } This endpoint is in "beta" state, meaning backwards incompatible changes may be introduced in future releases. _This endpoint requires the role: portal_administrator_

Set database purging configuration with a JSON object

Set database purging configuration with a JSON object. (BETA) Example body and response: { "changeLog": { "purgingTime": 1, "forcePurgingTime": 1, "purgingTimeSelector": "Days" }, "job": { "purgingTime": 1, "purgingDirectory": "job_purging/folder/path", "purgingTimeSelector": "Days" "purgingCompress": true, "purgingBatch": 1 }, "auditTrail": { "purgingTime": 1, "forcePurgingTime": 1, "purgingDirectory": "auditTrail_purging/folder/path", "purgingTimeSelector": "Days" "purgingCompress": true, "purgingBatch": 1 }, "transferLog": { "purgingTime": 1, "forcePurgingTime": 1, "purgingDirectory": "transferLog_purging/folder/path", "purgingTimeSelector": "Days" "purgingCompress": true, "purgingBatch": 1 } } Parameter documentation: purgingTime * The frequency of purging entries * type: integer * required: false forcePurgingTime * The frequency of purging entries even if in ongoing state * type: integer * required: false purgingTimeSelector * The time unit for purgingTime and forcePurgingTime * Valid choices are: 'Minutes', 'Hours', 'Days', 'Weeks', 'Months', 'Years'. * type: string * enum: ['Minutes', 'Hours', 'Days', 'Weeks', 'Months', 'Years'] * required: false purgingDirectory * The directory can be a full URI, such as a S3 or FTP location. * type: string * required: false purgingCompress * Store purged entries in compressed form * type: boolean * required: false purgingBatch * The number of entries to process each time, default is 10000 * If this many number of entries do not exist, purging will pause * type: integer * required: false This endpoint is in "beta" state, meaning backwards incompatible changes may be introduced in future releases. _This endpoint requires the role: portal_administrator_

Deletes all current database purging configuration

Deletes all current database purging configuration. (BETA) Example response(empty JSON object): {} This endpoint is in "beta" state, meaning backwards incompatible changes may be introduced in future releases. _This endpoint requires the role: portal_administrator_

Return the current size of system databases and their tables

Return the current size of system databases and their tables. (BETA) Example response: { "databases": [ { "name": "Portal", "key": "portal", "date": "2020-06-05T00:00:00Z", "entry_type": "db", "size": 382867992 }, { "name": "Vidispine", "key": "vidispine", "date": "2020-06-05T00:00:00Z", "entry_type": "db", "size": 268638744 }, { "name": "Activiti", "key": "activiti", "date": "2020-06-05T00:00:00Z", "entry_type": "db", "size": 9402904 } ], "portal_tables": [ { "relation": "django_celery_results_taskresult", "total_size": 330768384 }, { "relation": "celery_results_taskresult", "total_size": 27729920 } ], "vidispine_tables": [ { "relation": "t_auditlog", "total_size": 132530176 }, { "relation": "t_metadataentry", "total_size": 10928128 } ], "activiti_tables": [ { "relation": "act_ge_bytearray", "total_size": 245760 }, { "relation": "act_ru_identitylink", "total_size": 131072 } ] } This endpoint is in "beta" state, meaning backwards incompatible changes may be introduced in future releases. _This endpoint requires the role: portal_administrator_

Retrieve a list of files

Retrieve a list of files. _This endpoint requires the role: portal_api_files_read_

Notify portal about new files

Notify portal about new files Returns the newly created file id. _This endpoint requires the role: portal_api_files_write_

List all Groups

List all Groups Requester User should have at least one of the following roles: * portal_api_groups_list_own: To be able to list groups belonging to the user * portal_api_groups_list_all: To be able to list all groups _This endpoint require logged in user but no particular roles_

Create custom portal roles

Create custom portal roles Given a json object, setup a VS group with special metadata to be used as a portal_role Body should be a json: { "implies": null, "name": "portal_custom_role", "label": "My super awesome role", "children": [ { "implies": null, "name": "portal_custom_role_read", "label": "My super awesome role Read", "children": [] }, { "implies": "portal_custom_role_read", "name": "portal_custom_role_render", "label": "My super awesome role Render", "children": [] }, { "implies": "portal_custom_role_read", "name": "portal_custom_role_write", "label": "My super awesome role Write", "children": [] } ] } _This endpoint requires the role: portal_administrator_

Get the entire portal roles tree

Get the entire portal roles tree _This endpoint requires the role: portal_administrator_

Search suggestions for a particular user group query

Returns search suggestions for a particular user group query. This API is designed to for example be used when presenting the user with a list of suggestions in a free-text search field. _This endpoint requires the role: portal_administrator_

Get full roles tree of a group

Returns the full roles tree with access values based on a specified group. _This endpoint requires the role: portal_administrator_

Set roles to a specified group

Set roles to a specified group. Body should be a dictionary where the key is the name of the role: { "portal_system_export_location_read": ["True"], "portal_system_export_location_create": ["True"], "portal_system_export_location_write": ["True"], } _This endpoint requires the role: portal_administrator_

Delete a custom portal role

Delete a custom portal role Given a portal role name, delete the group/role in vidispine. Takes optional query parameter "traverse" which, if set to "true" will also delete any children _This endpoint requires the role: portal_administrator_

Get a suggested migration for a group

Based on a group name will return a suggested migration. Will go through all the vidispine roles belonging to the group and map them with the new Portal roles _This endpoint requires the role: portal_administrator_

Move a specific custom role for a group

Move a specific custom role (in the tree structure) Given a portal role name, set this group as a child group of another group Takes optional query parameter "parent" which, if set, will set this group as the child of the "parent". If "parent" in empty the group will become a root group. _This endpoint requires the role: portal_administrator_

Update an existing custom portal role

Update an existing custom portal role Body should be a json where the key is the name of the attribute to update. If a attribute is not in the list, the key will not be updated Full example body: { "label": "New Label", "implies": "portal_custom_role_read", "children": [] } The above json will set the label to "New Label". It will imply the role "portal_custom_role_read". it will remove all/any children nodes (but it will not delete them from the system) _This endpoint requires the role: portal_administrator_

Get search suggestions for a group

Returns search suggestions for a particular user group query. This API is designed to for example be used when presenting the user with a list of suggestions in a free-text search field. _This endpoint requires the role: portal_administrator_

Get health-check of the system

Return the result of a health-check of the system _This endpoint requires the role: portal_administrator_

Get simple version of health-check of the system

A simple version of the health check, suitable for testing if portal is running from a frontend proxy Returns a 200 status if healthy and 503 otherwise. _This endpoint does not require any authentication_

List the accessible formats for the logged user

Retrieves a list of the accessible formats for the logged user. _This endpoint require logged in user but no particular roles_

Create a placeholder with metadata

Creates a placeholder with metadata (if supplied) (BETA) Example body to create a placeholder with metadata { "metadata": { "group_name": "Film", "fields": [ { "name": "title", "value": "testTitle" }, { "name": "portal_mf201890", "value": "3" } ], "groups": [ { "name": "Actor", "mode": "add", "ref_uuid": "8a94f136-fdbb-4248-a16c-b2073141c586" }, { "name": "Broadcast Date", "mode": "add", "fields": [ { "name": "portal_mf11039", "value": "Channel 1" }, { "name": "portal_mf144943", "value": "2018-11-15T15:33:12.123456+10:00" } ] } ] } } This endpoint is in "beta" state, meaning backwards incompatible changes may be introduced in future releases. _This endpoint requires the role: portal_api_items_create_

Add items to the recycle bin

Add items to the recycle bin. If always_eager is supplied, bypass the recycle bin and just perform the delete _This endpoint requires the role: portal_api_items_delete_

Batch update the metadata of a list of items

Batch update the metadata of a list of items. Items can either be listed explicitly, or they could be given as a collection or search id with a possible ignore list for excluding specific items from that search or collection. Only one of item_ids, collection_id or search_id can be given. The actual update of the item metadata will be performed in the background after the call has returned. Example of a request document to update 3 fields in the top level of the item metadata, and add a new Broadcast Date subgroup instance: ``` { "metadata": { "group_name": "Demo", "fields": [ { "name": "portal_mf899660", "value": "1" }, { "name": "portal_mf876225", "value": ["many1", "many2"] }, { "name": "portal_mf133029", "value": "Test description" } ], "groups": [ { "name": "Broadcast Date", "mode": "add", "fields": [ { "name": "portal_mf11039", "value": "Channel 1" }, { "name": "portal_mf144943", "value": "2018-11-15T15:33:12.123456+10:00" } ] } ] } } ``` _This endpoint requires the role: portal_api_items_metadata_write_

Get DASH manifest for an item

Get DASH manifest for an item (BETA) The response is always in XML format. This endpoint is in "beta" state, meaning backwards incompatible changes may be introduced in future releases. _This endpoint supports authentication with `security_key` and requires the role: portal_api_items_read_

Get one segment of media of a specific shape for DASH playback

Get one segment of media of a specific shape for DASH playback (BETA) The manifest from dash_manifest -endpoint points to shapes via this endpoint. This endpoint is in "beta" state, meaning backwards incompatible changes may be introduced in future releases. _This endpoint supports authentication with `security_key` and requires the role: portal_api_items_read_

Get media item information for PPro Panel

Get media item information for PPro Panel: Path to the original and proxy file for VIDEO items. (BETA) Returned shapes are selected based on Proxy Workflow system settings. For other types of items (audio, image, data) this will only return the Vidispine original shape, since such media do not support proxy workflows. The returned list contains information for each ID passed in, in the same order. For example: GET /API/v2/items/nle_data/?items=VX-42,VX-123456 { "items": [ { "id": "VX-42", "files": { "original": { "shape_name": "original", "path": "/Volumes/media1/squirrel.mp4", "accessible": true }, "proxy": { "shape_name": "lowres", "path": "/Volumes/media1/squirrel_lowres.mp4", "accessible": true } } }, { "id": "VX-123456", "detail": "Item not found or you do not have access to it" } ] } This endpoint is in "beta" state, meaning backwards incompatible changes may be introduced in future releases. _This endpoint requires the role: portal_nle_open_

Recover items from the recycle bin

Recover items from the recycle bin _This endpoint requires the role: portal_api_items_recover_

Delete a relation between two items

Delete a relation between two items. _This endpoint requires the role: portal_api_items_relations_delete_

Get information about an item

Returns information about an item (BETA) This endpoint is in "beta" state, meaning backwards incompatible changes may be introduced in future releases. _This endpoint requires the role: portal_api_items_read_

Get all acl entries for a given item

Get all acl entries for a given item. All query parameters can be supplied as simple string or a CSV _This endpoint requires the role: portal_api_items_acl_read_

Enforce the acl on the item for a list of ACL objects

Given a list of ACL objects, enforce the acl on the item. Example body: [ { "source_name": "base", "source": "USER", "permission": "WRITE", "priority": "DEFAULT" }, { "source_name": "BaseGroup", "source": "GROUP", "permission": "READ", "priority": "DEFAULT" } ] _This endpoint requires the role: portal_api_items_acl_write_

View the acl entry for an item

Given a item_id and a acl_id, view the acl entry for an item. _This endpoint requires the role: portal_api_items_acl_read_

Update the acl entry for an item

Given an item_id and acl_id, update the acl entry for an item. Note that the updated acl entry will receive a new ID. The body contains the following parameters: - source: type of source one of the following options: [USER, GROUP] - source_name: name of the source - permission: permission level one of the following options: [NONE, OWNER, READ, WRITE, DELETE, ALL] Example body: { "source": "USER", "source_name": "UserName", "permission": "READ", "id": "VX-1", "priority": "DEFAULT", } _This endpoint requires the role: portal_api_items_acl_write_

Delete an acl entry

Given an item_id and acl_id, deletes the acl entry. _This endpoint requires the role: portal_api_items_acl_delete_

Get item formats and files

Returns information about all the formats and files for an item (BETA) This endpoint is in "beta" state, meaning backwards incompatible changes may be introduced in future releases. _This endpoint requires the role: portal_api_items_formats_read_

Deletes all formats on an item

Return an item with files to placeholder Deletes all formats on the item, making the item a placeholder. Disassociates all files them from this item, but does not delete the files. Resets all media related system metadata on the item. By default also deletes all thumbnails, this is optional _This endpoint requires the role: portal_api_items_formats_delete_

Get history for an item

Returns history for an item. _This endpoint requires the role: portal_api_items_history_

Import to an existing item

Import to an existing item. This call takes either a file_id or a uri. If you supply a uri, the file will be copied during the ingest process. _This endpoint requires the role: portal_api_items_write_

Get lock status on item

Get lock status on item _This endpoint requires the role: portal_api_items_lock_read_

Create a lock on item

Create a lock on item. _This endpoint requires the role: portal_api_items_lock_write_

Delete a lock on item

Delete a lock on item. _This endpoint requires the role: portal_api_items_lock_delete_

Promote supplied version to latest version of an item

Promote supplied version to latest version of an item. _This endpoint requires the role: portal_api_items_write_

Get all merged acl entries for an item

Get all merged acl entries for a given item. All query parameters can be supplied as simple string or a CSV _This endpoint requires the role: portal_api_items_acl_read_

Get metadata for an item

Get metadata for an item _This endpoint requires the role: portal_api_items_metadata_read_

Update metadata for an item

This endpoint receives an item Metadata document and updates the metadata of an item. For instance, the following document will update the value of the 'portal_mf201890' field and adds a referenced Actor element. Note that it uses a ref_uuid instead of metadata values. { "metadata": { "group_name": "Film", "fields": [ { "name": "portal_mf201890", "value": "3" } ], "groups": [ { "name": "Actor", "mode": "add", "ref_uuid": "8a94f136-fdbb-4248-a16c-b2073141c586" } ] } } The following will remove a referenced subgroup from the metadata: { "metadata": { "group_name": "Film", "groups": [ { "name": "Actor", "mode": "remove", "uuid": "5a2f0f78-ad4c-4e0d-af37-f6ad65cfc420" } ] } } _This endpoint requires the role: portal_api_items_metadata_write_

Get information about all the posters for an item

Returns information about all the posters for an item _This endpoint requires the role: portal_api_items_posters_read_

Delete a poster for an item

Deletes a poster for an item. (BETA) Example body: { "resource_id": "VX-1", "version": 1, "timecode": { "vidispine": "560@60" } } This endpoint is in "beta" state, meaning backwards incompatible changes may be introduced in future releases. _This endpoint requires the role: portal_api_items_posters_write_

Get preview data for an item

Get preview data for an item _This endpoint requires the role: portal_api_items_read_

List all relations of an item

List all relations of an item. _This endpoint requires the role: portal_api_items_relations_read_

Get the amount of relations on an asset

Get the amount of relations on an asset sorted by relation type. This will also include collections. _This endpoint requires the role: portal_api_items_relations_read_

Create a new relation between two items

Create a new relation between two items. Creates a relation from item_id (parent) to target_item_id (child). _This endpoint requires the role: portal_api_items_relations_write_

Get information about media items

Get information about media items used in a sequence. (BETA) This endpoint is in "beta" state, meaning backwards incompatible changes may be introduced in future releases. _This endpoint requires the role: portal_api_items_sequence_read_

Get a list of shape tags

Get a list of shape tags that can be used in rendering the given sequence item. (BETA) Note: Currently this only supports video formats, and ignores the given item_id. Example return value: { "shapetags": [ "lowres", "square", "highres" ] } This endpoint is in "beta" state, meaning backwards incompatible changes may be introduced in future releases. _This endpoint requires the role: portal_api_items_sequence_render_

Render a sequence item to a new item

Render a sequence item to a new item. (BETA) Request must contain a **tag** -parameter, specifying which format is used as the original format on the newly created item: { "tag": "lowres" } Optionally the request can contain **metadata**, including a **ingestprofile** parameter to select transcode profile for the new item: { "tag": "lowres", "metadata": { "ingestprofilegroup": "Admin", "name": "Film", "fields": [ { "name": "portal_mf268857", "field_type": "date", "value": "2020-09-14T00:00:00+00:00" }, { "name": "title", "field_type": "text", "value": "New Item Title" } ] } } If "ingestprofilegroup" is not defined, user's default will be used. For explicit "Keep Private" (no ingest profile used) "ingestprofilegroup" must be null. This endpoint is in "beta" state, meaning backwards incompatible changes may be introduced in future releases. _This endpoint requires the role: portal_api_items_sequence_render_

Start a shape deduction job for a specific shape

Start a shape deduction job for a specific shape _This endpoint requires the role: portal_api_items_formats_refresh_

List all storages for a shape

List all storages for shape that it does not exist on. _This endpoint requires the role: portal_api_items_formats_read_

Delete all files for a shape

Given a item and shape, delete all files for that shape on given storage. If no files for the shape are left after this operation, the shape itself will be deleted. _This endpoint requires the role: portal_api_items_formats_delete_

Copy a shape to a specified storage for an item

Given a specific item and shape on a storage, copy the shape to a specified storage. Example body: { "destination_storage": "VX-1" } _This endpoint requires the role: portal_api_items_formats_copy_

Move a file associated with a shape for an item

Given a specific item and shape on a storage, move the file associated with the shape Example body: { "destination_storage": "VX-1", "filename": "/srv/media1/squirrel.mov" } _This endpoint requires the role: portal_api_items_formats_move_

Rename a file associated with a shape in one storage for an item

Given a specific item and shape, rename the file associated with the shape in one storage. Example body: { "filename": "/srv/media1/squirrel.mov" } _This endpoint requires the role: portal_api_items_formats_rename_

Get information about an SubClip

Returns information about an SubClip _This endpoint requires the role: portal_api_items_read_

Get information about all the thumbnails for an item

Returns information about all the thumbnails for an item _This endpoint requires the role: portal_api_items_thumbnails_read_

Create thumbnail for an item

Create thumbnail for an item. Example body: { "timecode": {"vidispine": "900@PAL"} } _This endpoint requires the role: portal_api_items_thumbnails_write_

Get the title for an item

Get the title for an item _This endpoint requires the role: portal_api_items_read_

Set title of an item

Set title of an item. Example input: { "title": "The most awesome title ever" } Request with the same as current title value will not make any changes on the item. _This endpoint requires the role: portal_api_items_metadata_title_write_

Get metadata of a SubClip

Get metadata of a SubClip. _This endpoint requires the role: portal_api_items_metadata_read_

List all the versions for an item

List all the versions for an item _This endpoint requires the role: portal_api_items_read_

Get mediabin entries

This endpoint returns all of requesting users mediabin entries. This endpoint utilizes the search api. http://doc.cantemo.com/latest/DevelopmentGuide/rest/search.html _This endpoint require logged in user but no particular roles_

Create a new mediabin entry

Given a list of entries endpoint will create new mediabin entries for user. The valid types are: 'collection', 'item', 'subclip' if the type is subclip parent_id is required. The format of json payload should be as follows: { "entries": [ { "id": "XX-X", "type": "collection" }, { "id": "XX-X", "type": "item" }, { "id": "UUID", "type": "subclip", "parent_id": "XX-X" } ] } _This endpoint require logged in user but no particular roles_

Update mediabin entries

Given a list of entries endpoint will update or create new mediabin entries for user. The valid types are: 'collection', 'item', 'subclip' if the type is subclip parent_id is required. The format of json payload should be as follows: { "entries": [ { "id": "XX-X", "type": "collection" }, { "id": "XX-X", "type": "item" }, { "id": "UUID", "type": "subclip", "parent_id": "XX-X" } ] } _This endpoint require logged in user but no particular roles_

Delete mediabin entries

Given a list of Media Bin entries removes them from the users Bin. The valid types are: 'collection', 'item', 'subclip' The format of json payload should be as follows: { "entries": [ { "id": "XX-X", "type": "collection" }, { "id": "XX-X", "type": "item" }, { "id": "UUID", "type": "subclip", "parent_id": "XX-X" } ] } _This endpoint require logged in user but no particular roles_

Get metadata elements

Get metadata elements _This endpoint requires the role: portal_api_metadata_elements_read_

Get a weak reference metadata element

Get a weak reference metadata element including metadata values. The name-argument is currently ignored. _This endpoint requires the role: portal_api_metadata_elements_read_

Return a list of metadata fields

Get all top level nodes in hierarchy for particular field

Return all top level nodes in hierarchy for particular field. _This endpoint requires one of the roles: portal_api_items_metadata_read, portal_api_collections_metadata_read_

Create a new node in hierarchy for field

Create a new node in hierarchy for field. _This endpoint requires the role: portal_api_metadata_schema_write_

Get all information about node for particular field

Return all information about node for particular field. _This endpoint requires one of the roles: portal_api_items_metadata_read, portal_api_collections_metadata_read_

Create a new node in hierarchy for field

Create a new node in hierarchy for field. _This endpoint requires the role: portal_api_metadata_schema_write_

Delete a node from hierarchy field

Delete a node from hierarchy field. _This endpoint requires the role: portal_api_metadata_schema_write_

Get all children of the node in hierarchy for particular field

Return all children of the node in hierarchy for particular field. _This endpoint requires one of the roles: portal_api_items_metadata_read, portal_api_collections_metadata_read_

Get a metadata field

Return a metadata field

List metadata choices

Return a JSON containing the total amount of choices and a list of all of the choices for a given field, as known in portal's database _This endpoint requires the role: portal_api_metadata_schema_read_

Create new choices for the given field

Given a list of object, create new choices for the given field. If the object's "key" value already exists, it will overwrite the existing value. If no position is given, the new choice will be added to the end of the list. A simple example body: [{ key: "new-key", value: "New Value", position: "0" }] _This endpoint requires the role: portal_api_metadata_schema_write_

Delete all choices for a dropdown or lookup field

Delete all choices for a dropdown or lookup field _This endpoint requires the role: portal_api_metadata_schema_delete_

Update a value and position of a specific choice

Given a object, update the value and position of a specific choice for the given field. Both value and position are optional but at least one must be supplied A simple example body: { value: "New Value", position: 1 } _This endpoint requires the role: portal_api_metadata_schema_write_

Delete the specific choice for the given field

Delete the specific choice for the given field. _This endpoint requires the role: portal_api_metadata_schema_delete_

Get list of the tags

Returns a list of the tags values for a given field. _This endpoint requires the role: portal_api_metadata_schema_read_

List the possible field types available

Lists the possible field types available _This endpoint requires the role: portal_api_metadata_schema_read_

Get a list of metadata groups

Retrieve a list of metadata groups. _This endpoint requires the role: portal_api_metadata_schema_read_

Get a metadata field group from Vidispine

Returns a metadata field group from Vidispine _This endpoint requires the role: portal_api_metadata_schema_read_

Get all allowed choices based on the currently selected metadata values

Returns all allowed choices based on the currently selected metadata values, for fields with type radio, checkbox and dropdown. Choices for lookup-fields are not returned by this API. However the selected values for those must be included in the input. This is always done per metadata group - if there are subgroups, separate requests are needed for those. Example input when key "a-daughter-of-her-people" is selected for the field portal_title: { "fields": [ { "name": "portal_title", "keys": ["a-daughter-of-her-people"] } ] } Fields that do not have a value set should be excluded from the input data. Also this request is not necessary when no data is set on an item, response for {"fields":[]} is always an empty list. The output includes all valid keys for each field that are set and have a condition and are not of type "lookup". I.e. below output assumes portal_kind, portal_year etc are of type radio, checkbox or dropdown. Also note: "portal_actresses" is not mentioned in the "fields" result, this means that "portal_actresses" does not have any restrictions based on the conditions. I.e. a field that is not included in the result should not be limited. "portal_editors" is included with an empty list. This means that "portal_editors" choices should be empty - i.e. user cannot select any value for that field. { "fields": [ { "keys": [ "movie" ], "name": "portal_kind" }, { "keys": [ "1933" ], "name": "portal_year" }, { "keys": [], "name": "portal_editors" }, { "keys": [ "galeen-henrik", "roland-george-i" ], "name": "portal_directors" }, { "keys": [ "a-daughter-of-her-people" ], "name": "portal_title" }, { "keys": [ "adalbert-max", "basenko-ben", "deutsch-ernst", "dorf-morris", "green-joseph-i", "haskel-leonhard", "mestel-jacob", "otto-paul-i", "rosenberg-michael-i", "shneyer-chaim", "vallentin-hermann" ], "name": "portal_actors" } ] } _This endpoint requires one of the roles: portal_api_items_metadata_read, portal_api_collections_metadata_read_

Get a list of all metadata conditions

Get a list of all metadata conditions on a metadata group. _This endpoint requires one of the roles: portal_api_items_metadata_read, portal_api_collections_metadata_read_

Bulk create conditions on a metadata group

Bulk create conditions on a metadata group. Similar to the `PUT /API/v2/metadata-schema/groups/{name}/conditions/{external_id}`-endpoint, but optimized for performance: * Up to 1000 conditions can be created at once * Only allows creation of new conditions, trying to update an existing one is an error The input should be a list of conditions with `external_id` included: [ { "fields": [ { "keys": ["1990"], "field_name": "portal_year" }, { "keys": ["tong-ken", "ma-steve-i"], "field_name": "portal_actors" } ], "external_id": "The Rising Son (1990)" }, { "fields": [ { "keys": ["martin-noah-i", "wexler-johnny"], "field_name": "portal_actors" }, { "keys": ["2011"], "field_name": "portal_year" } ], "external_id": "Evenings Under the Influence (2011)" } ] See documentation of `PUT /API/v2/metadata-schema/groups/{name}/conditions/{external_id}` for more information about conditions. _This endpoint requires portal_api_metadata_schema_write and one of the roles: portal_api_items_metadata_read, portal_api_collections_metadata_read_

Delete all conditions on a metadata group

Delete all conditions on a metadata group _This endpoint requires portal_api_metadata_schema_write and one of the roles: portal_api_items_metadata_read, portal_api_collections_metadata_read_

Access single metadata condition details

Access single metadata condition details. For example the following condition: * affects the metadata group "Movie" * has an external identifier "The Rising Son (1990)": this is not relevant for the Portal UI, only for administrating the condition * defines that whenever user selects "1990" as value for the metadata field "portal_year", the possible values for the field "portal_actors" are "tong-ken" and "ma-steve-i". This is the key, display value would be e.g. "Tong, Ken" In JSON format: { "fields": [ { "keys": [ "1990" ], "field_name": "portal_year" }, { "keys": [ "tong-ken", "ma-steve-i" ], "field_name": "portal_actors" } ], "external_id": "The Rising Son (1990)", "metadata_group": "Movie" } _This endpoint requires one of the roles: portal_api_items_metadata_read, portal_api_collections_metadata_read_

Update or create a metadata condition

Update or create a metadata condition. Example of a valid request body that: * has an external identifier "The Rising Son (1990)": this is not relevant for the Portal UI, only for administrating the condition * defines that whenever user selects "1990" as value for the metadata field "portal_year", the possible values for the field "portal_actors" are "tong-ken" and "ma-steve-i". This is the key, display value would be e.g. "Tong, Ken" In JSON format: { "fields": [ { "keys": [ "1990" ], "field_name": "portal_year" }, { "keys": [ "tong-ken", "ma-steve-i" ], "field_name": "portal_actors" } ] } _This endpoint requires portal_api_metadata_schema_write and one of the roles: portal_api_items_metadata_read, portal_api_collections_metadata_read_

Delete a metadata condition

Delete a metadata condition. _This endpoint requires portal_api_metadata_schema_write and one of the roles: portal_api_items_metadata_read, portal_api_collections_metadata_read_

Create lookup choices for metadata schema groups

End-point for querying valid lookup field values based on user entry into this field (query) and values of other fields. Returns both key and display value for the choices. Returns a maximum on 1000 choices. If more choices are available for this field, returned data includes more_choices_exist as "true", and a query_string value should be used to filter down the list. "fields" parameter is required and must be a list - if user has not yet entered values to any conditional fields in the form it should be an empty list. Example input when key user has entered "ma" into the lookup field (portal_actors here - assumed to be a lookup), and "the-thousand-plane-raid" is selected for the field portal_title. POST /API/v2/metadata-schema/groups/Movie/portal_actors/lookup_choices/ { "fields": [ { "name": "portal_title", "keys": ["the-thousand-plane-raid"] } ], "query_string": "ma" } Example output: { "field_name": "portal_actors", "metadata_group": "Movie", "choices": [ { "value": "MacLeod, Gavin", "key": "macleod-gavin" }, { "value": "Marshal, Gary (I)", "key": "marshal-gary-i" }, { "value": "McLaughlin, Mac", "key": "mclaughlin-mac" }, { "value": "Thomas, Scott (I)", "key": "thomas-scott-i" }, ], "more_choices_exist": false } _This endpoint requires one of the roles: portal_api_items_metadata_read, portal_api_collections_metadata_read_

Calculate metadata differences

Calculates differences between multiple metadata documents adds the differ flag to the fields that differs and then returns the summary metadata document Body should be a list of metadata documents: [ { "group_name": "Film", "metadata": {"fields": [{"value": "1"}]} }, { "group_name": "Film", "metadata": {"fields": [{"value": "2"}]} } ] _This endpoint requires the role: portal_api_metadata_schema_read_

Update metadata calculation

Calculates differences between multiple metadata documents adds the differ flag to the fields that differs and then returns the summary metadata document _This endpoint requires the role: portal_api_metadata_schema_read_

Get metadata to populate metadataforms

Returns metadata to populate metadataforms with js component cntmo.prtl.Metadata.renderMetadataForm _This endpoint requires the role: portal_api_metadata_schema_read_

Update metadata to populate metadataforms

Returns metadata to populate metadataforms with js component cntmo.prtl.Metadata.renderMetadataForm _This endpoint requires the role: portal_api_metadata_schema_read_

List metadata schema for migration

Retrieves a JSON format file with all the MetaData Schemas, including fields, metadata groups, choices, conditions, hierarchical fields, etc. The response has a key called "errors", which could retrieve a few non-critical errors (errors that don'e raise exceptions) which could still be important for the user to know. This operation is expensive and can take a while to be completed. _This endpoint requires the role: portal_administrator_

Update metadata schema for migration

Gets a JSON file/data with a full schema representation(like in the GET of this same View) from a Portal instance and loads it in the current instance. This operation is expensive and can take a while to be completed _This endpoint requires the role: portal_administrator_

Get the ExtraData for a metadata group or field

Get the ExtraData for a metadata group or field _This endpoint requires the role: portal_api_metadata_schema_read_

List notifications

List the notifications for the current user _This endpoint require logged in user but no particular roles_

Create a notification

Create a notification in Portal Note this endpoint will not respect the notification settings for the recipient users. The body can contain the following parameters: - thumbnail_url: url that will be used as the thumbnail for the notification - message: the message of the notification, if not specified it will be generated based other data. - message_url: url that will be used when clicking on the notifications message in the UI. - status: a string with one of the following options: [SUCCESSFUL, WARNING, FAILED] - type: specify a custom type or one of the following options: [SYSTEM_JOB, ARCHIVE_JOB, SYSTEM_HEALTH_CHANGES] - target_id: If the notification is regarding a specific target it can be specified here, e.g item id. - target_title: If the notification is regarding a specific target the title can be specified here. - target_url: If the notification is regarding a specific target the url can be specified here. - job_id: If the notification is regarding a job, the job ID can be specified here. - job_type: If the notification is regarding a job, the job type can be specified here. - recipients: Specify users or groups the notification should be sent to. See example below. - notifications: Optional parameter that have the same rules as mentioned above, expect recipient. Example body: { "thumbnail_url": "/url/to/image.png", "message": "Here's a message", "status": "FAILED", "type": "custom", "target_id": "VX-1", "target_title": "title for asset", "job_id": "VX-3", "job_type": "transcode", "notifications": [ { "thumbnail_url": "/url/to/image.png", "message": "Here's a child notification", "status": "FAILED", "type": "custom" } ], "recipients": { "users": ["user1", "user2"], "groups": ["Admin", "group2"] } } _This endpoint requires the role: portal_api_notifications_post_

Deletes all notifications

Deletes all the notifications for the current user _This endpoint require logged in user but no particular roles_

Get total number of unread notifications

Get all total number of unread notifications for the current user _This endpoint require logged in user but no particular roles_

Mark all the notifications as read

Mark all the notifications for the current user as read _This endpoint require logged in user but no particular roles_

Get a notification

Get a notification _This endpoint require logged in user but no particular roles_

Delete a notification

Delete a notification If the specified notification is the last child of a bulk notification the bulk notification itself will also be deleted _This endpoint require logged in user but no particular roles_

Mark a notification as read

Mark a notification as read _This endpoint require logged in user but no particular roles_

Get a ping

Returns a ping _This endpoint does not require any authentication_

Update reindex information

Sync item, collection of file information from Vidispine to Elastic via a reindex Full example body: ``` { "items": ["VX-1"], "collections": ["VX-3"], "files": ["VX-90"] } ``` If the supplied items have any subclips, the subclips will be index together with the parent item. This also means that if you want to reindex subclips via this API you have to reindex the parent item. Most actions in Portal will sync the data from Vidispine into Elastic automatically, however this API can be used when a specific workflow does not trigger this sync. Note that this does not reindex the asset in Vidispine _This endpoint requires the role: portal_administrator_

List ACL entries for saved search

Get all acl entries for a given saved search. All query parameters can be supplied as simple string or a CSV _This endpoint requires the role: portal_api_search_saved_search_acl_

Create ACL for saved search

Given a list of ACL objects, enforce the acl on the saved search. Example body: [ { "source_name": "base", "source": "USER", "permission": "WRITE", "priority": "DEFAULT" }, { "source_name": "BaseGroup", "source": "GROUP", "permission": "READ", "priority": "DEFAULT" } ] _This endpoint requires the role: portal_api_search_saved_search_acl_

Delete ACL entry for saved search

Delete acl entry for saved search. All query parameters can be supplied as simple string or a CSV _This endpoint requires the role: portal_api_search_saved_search_acl_

Read ACL entry for saved search

Given a saved search id and a acl id, view the acl entry for the saved search. _This endpoint requires the role: portal_api_search_saved_search_acl_

Delete ACL entry for saved search

Given a saved search id and a acl id, delete acl entry for the saved search. _This endpoint requires the role: portal_api_search_saved_search_acl_

Update search

Perform a search using the request body For extensive documentation about this API endpoint, please see the Portal Developer's documentation. A simple example body: { "query": "squirrel", "filter": { "operator": "AND", "terms": [ { "name": "portal_deleted", "missing": true } ] } } A more complex example body: { "fields": [ "id", "vidispine_id", "mediaType", "title", "portal_mf201890", "portal_mf257027", "portal_mf551902", "portal_mf268857", "created" ], "filter": { "operator": "AND", "terms": [ {"name": "portal_deleted", "missing": true}, {"name": "portal_mf201890", "value": "1"}, {"name": "metadata_main_group", "value": "Film"} ], "groups": [{ "name": "Subgroup", "filter": { "operator": "AND", "terms": [ {"name": "portal_mf771345", "value": "sv"}, {"name": "portal_mf642112", "value": "5"} ], "groups": [{ "name": "SubSubGroup", "filter": { "operator": "NOT", "terms": [ {"name": "portal_mf112753", "value": "The Matrix"} ] } }] } }], "filters": [ { "operator": "OR", "filters": [ { "operator": "AND", "terms": [ {"name": "portal_mf268857", "value": "2016-12-30"}, {"name": "portal_mf551902", "value": "12"} ] }, { "operator": "AND", "terms": [ {"name": "portal_mf268857", "range": {"max": "2016-12-29"}}, {"name": "portal_mf551902", "value": "15"} ] } ] } ] }, "sort": [ {"name": "portal_mf268857", "order": "desc"}, {"name": "title", "order": "asc"} ] } _This endpoint requires the role: portal_api_search_perform_search_

List search aggregations

Returns a dict that contains all aggregations in the system _This endpoint requires one of the roles: portal_api_search_perform_search, portal_api_search_saved_search_read_

Create batch metadata update for search

Provide a view when doing batch metadata update on the combined search page Perform a metadata batch update given a metadata group name and a form containing field names and values. :param slug: Name of metadata group This end-point only supports form data (multipart/form-data), not JSON. An example querydict for metadata batch update { '?csrfmiddlewaretoken': ['YbpY9YVsRYNPWvJ8F1Ps7Xtz5cVmWyFAF3XFKkwxNJZVY7vQCNwsw77NQHctkAup'], 'batch_update_mode': ['replace'], 'action': ['Update'], 'value': ['MyMetadataGroup'], 'label': ['MyMetadataGroup'], 'metadatagroup': ['MyMetadataGroup'], 'portal_mf314262_0': ['123'], 'portal_mf314262_1': ['string'], 'portal_mf314262_checkbox': ['on'], 'item_ids': ['VX-1936', 'VX-1931'] } _This endpoint requires the role: portal_api_items_metadata_write_

List search histories

List the search histories for the current user. - name: page_size description: Specifies the amount of transfers by page in the response type: integer paramType: query defaultValue: 100 - name: offset description: Specifies the offset on the pagination in the response type: integer paramType: query defaultValue: 0 _This endpoint requires the role: portal_api_search_perform_search_

List documents for search history

Returns search history criteria document without performing the search _This endpoint requires the role: portal_api_search_perform_search_

Read navigational link for item in search

Based on the current search and item this will return a link to the next or previous item that it should be navigated to from the item page when clicking the previous and next button. Note that it will filter out collections, and a collection only search is not valid. This call returns data on the format: { index: "1", search_url: "/search/", current_page: 1, search_total: 199, navigation: { next_item: { url: "/item/VX-322/", index: 2, id: "VX-322", item_type: "item" }, prev_item: { url: "/item/VX-324/", index: 0, id: "VX-324", item_type: "item" } }, search_id: "1" } _This endpoint requires the role: portal_api_search_perform_search_

List saved searches

Returns all the saved searches for the current user. - name: page_size description: Specifies the amount of saved searches to fetch type: integer paramType: query defaultValue: 100 - name: offset description: Specifies the offset on the pagination in the response type: integer paramType: query defaultValue: 1 _This endpoint requires the role: portal_api_search_saved_search_read_

Create a saved search

Creates a saved search with the given criteria document For extensive documentation about the search document used in this API endpoint, please see the Portal Developer's documentation. Return value contains the full document, the saved search name, and the ID of the saved search, for example `"id": "VX-103"`. In addition to the regular search document, Saved Search documents can contain information for the UI to load the search filters to the search form. An additional parameter "category" is used for this. Example body for a saved search: { "document": { "category": "Film", "filter": { "operator": "AND", "terms": [ { "name": "portal_deleted", "missing": true }, { "category": "usermetadata", "name": "portal_mf201890", "value": "1" }, { "category": "filemetadata", "name": "portal_itemtype", "value_in": [ "video", "audio" ] } ] }, "sort": [ {"name": "title", "order": "desc"} ] }, "name": "Video or audio, season is 1" } * This matches items where metadata field Season (portal_mf201890) = 1, and type is video or audio * Results are sorted by Title, descending order * `"category": "user"` for the filter on `portal_mf201890` defines that this is shown in the User Metadata section of the search form. * `"category": "filemetadata"` for the `portal_itemtype` filter defines that this is shown in the File Metadata section of the search form. * The high-level `"category": "Film"` defines the metadata group used for user metadata filters Please check search documents created with the Portal UI for more concrete examples, and to match the way the User Interface generates for example date range filters. Note: Complex search documents cannot be rendered by the Portal search form, and their filters can only be shown and modified with the REST APIs. _This endpoint requires the role: portal_api_search_saved_search_write_

Gets saved search by id

Gets saved search by its id and perform a search _This endpoint requires the role: portal_api_search_saved_search_read_

Update name and saved search criteria document

Update name and saved search criteria document for an existing saved search For extensive documentation about the search document used in this API endpoint, please see the Portal Developer's documentation. Return value contains the full document, the saved search name, and the ID of the saved search, for example `"id": "VX-103"`. In addition to the regular search document, Saved Search documents can contain information for the UI to load the search filters to the search form. An additional parameter "category" is used for this. Example body for a saved search: { "document": { "category": "Film", "filter": { "operator": "AND", "terms": [ { "name": "portal_deleted", "missing": true }, { "category": "usermetadata", "name": "portal_mf201890", "value": "1" }, { "category": "filemetadata", "name": "portal_itemtype", "value_in": [ "video", "audio" ] } ] }, "sort": [ {"name": "title", "order": "desc"} ] }, "name": "Video or audio, season is 1" } * This matches items where metadata field Season (portal_mf201890) = 1, and type is video or audio * Results are sorted by Title, descending order * `"category": "usermetadata"` for the filter on `portal_mf201890` defines that this is shown in the User Metadata section of the search form. * `"category": "filemetadata"` for the `portal_itemtype` filter defines that this is shown in the File Metadata section of the search form. * The high-level `"category": "Film"` defines the metadata group used for user metadata filters Please check search documents created with the Portal UI for more concrete examples, and to match the way the User Interface generates for example date range filters. Note: Complex search documents cannot be rendered by the Portal search form, and their filters can only be shown and modified with the REST APIs. _This endpoint requires the role: portal_api_search_saved_search_write_

Delete a saved search

Deletes a saved search _This endpoint requires the role: portal_api_search_saved_search_delete_

List search suggestions

Returns search suggestions for a particular query. This API is designed to for example be used when presenting the user with a list of suggestions in a free-text search field. _This endpoint requires the role: portal_api_search_perform_search_

List documents for saved search

Returns saved search criteria document without performing the search _This endpoint requires the role: portal_api_search_perform_search_

List shares

Lists all the shares that a user can see, in a paginated response. If the user has 'portal_api_manage_sharing', all shares are visible. Required roles: portal_api_sharing_items or portal_api_sharing_collections Search and sorting by fields is supported. But there are 2 special filter fields for this view: - recipient_email: an email of a recipient. So if specified, it will retrieve the shares that a specific recipient has access to. - user: an user username. If specified, it will retrieve the shares that a specific user has created. They can be used as any other filtering on the api, so, for example: - GET /API/v2/shares/?search=an@email.com&search_fields=recipient_email - GET /API/v2/shares/?search=anusername&search_fields=user Example response: { "shares": [ { "id": 4, "user": "admin", "datetime_created": "2019-03-13T08:03:06.716575Z", "expiration_date": "2020-12-02T00:00:00Z", "subject": "a subject", "message": "a message", "recipients_count": 1, "download_formats": [ "original", "format1" ], "urls": { "details": "...", "links": "...", "objects": "..." } }, ... ], "total": 50 } _This endpoint requires one of the roles: portal_api_sharing_items, portal_api_sharing_collections_

Create a new share

Creates a new Share. Parameters: - expiration_date: a valid ISO8601 datetime, specifying the share expiration date - subject: a subject for the email being sent to the share recipients - message: a message for the email being sent to the share recipients - password (optional): a password to access the share - download_formats: a list of formats the the recipients can download At least one of the following parameters should be specified to indicate what to share, and multiple of them can be used together: - items_ids: a list containing ids of items to be shared - collections_ids: a list containing ids of collections to be shared - search_id: the id of a search history that the user has access to, to share the items and collections contained in that search at the moment the share is created. ignore_list and ignore_collections_ids can also be indicated, where ignore_list should be a list of ids of items to skip from the share, and ignore_collections_ids a list of collections ids to skip from the share. Example body: { "expiration_date": "2020-12-02T12:00:00", "subject": "a subject", "message": "a message", "password": "123456", "download_formats": ["original", "lowres"], "items_ids": ["VX-1111", "VX-2222"] } _This endpoint requires one of the roles: portal_api_sharing_items, portal_api_sharing_collections_

Read shared link content

This is an sharing-authenticated share link content. Lists all the assets for a share in a paginated response. If the share has a password, a custom header needs to be added, as follows: - Header name: 'Authorization' - Header Value: 'Share ' + the share password Example response: { "objects": [ { "id": "VX-246", "type": "item", "title": "With G2 Group", "urls": { "thumbnails": ["/APInoauth/thumbnail/VX-1/VX-246;version=1/0?hash=b03b2e47...582eb8ca"], "share_content": "/API/v2/shares/4bd6f09d89224574b4d7d506ffb3c4c2/content/", "details": "/API/v2/shares/4bd6f09d89224574b4d7d506ffb3c4c2/content/item/VX-246/" } }, ... ], "total": 25 } parameters: - name: unique_key description: The share link unique key type: integer paramType: path - name: assets_type description: An optional item|collection choice to filter content for only that type type: string paramType: query _This endpoint is authenticated with the `unique_key` in the URL, and optionally with a Share password header_

Get shared collection content

This is an sharing-authenticated shared collection content. Lists (with pagination) all the assets contained on a collection or a sub-collection which belongs to a share. The results are sorted by asset type and asset id. If the share has a password, a custom header needs to be added, as follows: - Header name: 'Authorization' - Header Value: 'Share ' + the share password Example response: { "objects": [ { "id": "VX-125", "type": "collection", "urls": { "thumbnails": [ ... ], "share_content": "/API/v2/shares/link/1a...b83/", "details": "/API/v2/shares/link/1a...b83/collection/VX-125/" }, "name": "sub2" }, { "id": "VX-116", "type": "item", "title": "12.jpg", "urls": { "thumbnails": [], "share_content": "/API/v2/shares/link/1a...b83/", "details": "/API/v2/shares/link/1a...b83/item/VX-116/" } }... ], "total": 25 } _This endpoint is authenticated with the `unique_key` in the URL, and optionally with a Share password header_

Read shared item content

This is an sharing-authenticated shared item content. Lists all details of an item shared by an user. If the share has a password, a custom header needs to be added, as follows: - Header name: 'Authorization' - Header Value: 'Share ' + the share password Note: The comments and downloads urls will be valid for a period of 2 hours after the response is generated. Also, if the sharer user has no roles for accessing these resources, that keys will be missing from the URLS section. Example response: { "id": "VX-1250", "type": "item", "version": "latest", "title": "Zig Zag.mp4", "urls": { "preview": "/API/v2/sh..." "download_formats": [ { "format": "lowres", "url": "/API/v2/shares/99c3aa5cd7..." }, { "format": "original", "url": "/API/v2/shares/99c3aa5cd7..." } ], "comments": "/API/v2/comments/item/VX-1250/?security_key=99c3aa5cd7...", "thumbnails": ["/APInoauth/thumbnail/VX-1/VX-..."] "details": "/API/v2/shares/99c3aa5cd7...", "share_content": "/API/v2/shares/..." } } _This endpoint is authenticated with the `unique_key` in the URL, and optionally with a Share password header_

List shared item shape downloads

This is an sharing-authenticated share item format download. It gets the item file for the specified shape id. If the share has a password, a custom header needs to be added, as follows: - Header name: 'Authorization' - Header Value: 'Share ' + the share password _This endpoint is authenticated with the `unique_key` in the URL, and optionally with a Share password header_

Read share details

Retrieves details for a specific share. Example response: { "id": 4, "user": "admin", "datetime_created": "2019-03-13T08:03:06.716575Z", "expiration_date": "2020-12-02T00:00:00Z", "subject": "a subject", "message": "a message", "recipients_count": 1, "download_formats": [ "original", "format1" ], "urls": { "details": "...", "links": "...", "objects": "..." } } _This endpoint requires one of the roles: portal_api_sharing_items, portal_api_sharing_collections_

Deletes a specified share

Deletes a specified share. _This endpoint requires one of the roles: portal_api_sharing_items, portal_api_sharing_collections_

List all share links

For a specific share, lists all the share links in a paginated format. Search and sorting by fields is supported. Example response: { "links": [ { "datetime_created": "2019-03-04T15:11:28.733603Z", "recipient_email": "lalsd@asd.com", "expiration_date": null, "disabled": false, "email_sent": false, "urls": { "content": "...", "delete": "... "share": "... } }, ... ], "total": 20 } _This endpoint requires one of the roles: portal_api_sharing_items, portal_api_sharing_collections_

Create share links

For a specific share, assigns recipients, creates share-links for them, and sends the share links by email. Parameters: - recipients_emails: a list with the recipients emails - expiration_date: (optional) a valid ISO8601 datetime, specifying the links expiration date. If not specified, the expiration date will be the share expiration. Example body: { "recipients_emails": ["some@example.com", "some2@example2.com"] } _This endpoint requires one of the roles: portal_api_sharing_items, portal_api_sharing_collections_

Delete a specified share link

Deletes a specified share_link. _This endpoint requires one of the roles: portal_api_sharing_items, portal_api_sharing_collections_

List shared objects

Retrieves a paginated list of objects (collections and items) shared by the specified share. Example response: { "objects": [ { "id": "VX-3485", "type": "item", "title": "VX-3485" }, ... ], "total": 1 } _This endpoint requires one of the roles: portal_api_sharing_items, portal_api_sharing_collections_

Get a list of storages

Get a list of storages _This endpoint requires the role: portal_api_storages_

Get a storage

Get storage _This endpoint requires the role: portal_api_storages_

Retrieve a list of files

Retrieve a list of files. _This endpoint requires the role: portal_api_files_read_

Create storage content

Notify portal about new files Returns the newly created file id. _This endpoint requires the role: portal_api_files_write_

Get the active language

Get the active language for the user _This endpoint require logged in user but no particular roles_

Get a list of available (translatable) languages

Get a list of available (translatable) languages to the system _This endpoint require logged in user but no particular roles_

Get details of a background task

Get details of a background task. _This endpoint requires the role: portal_administrator_

List transfers

List the current status of the Transfers in Portal _This endpoint requires the role: portal_administrator_

Create transfer

To Register a Transfer in Portal The body should contain the following parameters: - service: a string with the Transfer Service Identifier - origin: a string with the description of the source which triggered the transfer - service_transfer_id: a string with the identifier of the transfer on the specified service - type: a string with one of the following options: [UPLOAD, COPY, MOVE, DOWNLOAD, EXPORT] - state: a string with one of the following options: [READY, STARTED, FAILED, ABORTED, FINISHED] - started_datetime: a valid ISO formatted datetime specifying the creation date of the transfer - finished_datetime: a valid ISO formatted datetime specifying the finished date of the transfer - bytes_to_transfer: an integer with the file size in bytes - filename: a string with the name of the file for the Transfer - reference_url: an optional string with an URL for getting more details on the transfer on the admin UI - reference_label: an optional string with a label to show on the admin UI for the reference - progress: an integer number between 0 and 100 specifying the transfer progress percentage - extra_data: an optional valid JSON string containing useful information for keeping track of the Transfer - details: an optional string providing additional information on the Transfer. Example body: { "service": "Example Service", "origin": "API", "service_transfer_id": "as-asd-12", "type": "UPLOAD", "state": "READY", "started_datetime": "2019-01-01T12:30:00+00:00", "finished_datetime": "", "bytes_to_transfer": "50", "filename": "myfilename.mov", "reference_url": "", "reference_label": "", "progress": "0", "extra_data": "{}", "details": "" } _This endpoint requires the role: portal_api_transfers_write_

Get the state of a Transfer

Get the state of a Transfer. This endpoint accepts 2 URL formats: - /API/v2/transfers/{transfer_id}/ In which the transfer_id is the ID of the transfer in Portal Database - /API/v2/transfers/{transfer_service}/{service_transfer_id}/ In which the transfer_service is the Transfer Service set on creation and the service_transfer_id is the ID of the transfer for that service (also specified when created) _This endpoint requires the role: portal_api_transfers_read_

Update a Transfer

It updates a Transfer. This endpoint accepts 2 URL formats: - /API/v2/transfers/{transfer_id}/ In which the transfer_id is the ID of the transfer in Portal Database - /API/v2/transfers/{transfer_service}/{service_transfer_id}/ In which the transfer_service is the Transfer Service set on creation and the service_transfer_id is the ID of the transfer for that service (also specified when created) All the request parameters in this view are optional, and the previous values will stay if no new value is specified for a Transfer attribute - origin: a string with the description of the source which triggered the transfer - type: a string with one of the following options: [UPLOAD, COPY, MOVE, DOWNLOAD, EXPORT] - state: a string with one of the following options: [READY, STARTED, FAILED, ABORTED, FINISHED] - started_datetime: a valid ISO formatted datetime specifying the creation date of the transfer - finished_datetime: a valid ISO formatted datetime specifying the finished date of the transfer - bytes_to_transfer: an integer with the file size in bytes - filename: a string with the name of the file for the Transfer - reference_url: an optional string with an URL for getting more details on the transfer on the admin UI - reference_label: an optional string with a label to show on the admin UI for the reference - progress: an integer number between 0 and 100 specifying the transfer progress percentage - extra_data: an optional valid JSON string containing useful information for keeping track of the Transfer - details: an optional string providing additional information on the Transfer. Example body: { "origin": "API", "type": "UPLOAD", "state": "READY", "started_datetime": "2019-01-01T12:30:00+00:00", "finished_datetime": "", "bytes_to_transfer": "50", "filename": "myfilename.mov", "reference_url": "", "reference_label": "", "progress": "0", "extra_data": "{}", "details": "" } _This endpoint requires the role: portal_api_transfers_write_

Get the state of a Transfer - 2

Get the state of a Transfer. This endpoint accepts 2 URL formats: - /API/v2/transfers/{transfer_id}/ In which the transfer_id is the ID of the transfer in Portal Database - /API/v2/transfers/{transfer_service}/{service_transfer_id}/ In which the transfer_service is the Transfer Service set on creation and the service_transfer_id is the ID of the transfer for that service (also specified when created) _This endpoint requires the role: portal_api_transfers_read_

Update a transfer - 2

It updates a Transfer. This endpoint accepts 2 URL formats: - /API/v2/transfers/{transfer_id}/ In which the transfer_id is the ID of the transfer in Portal Database - /API/v2/transfers/{transfer_service}/{service_transfer_id}/ In which the transfer_service is the Transfer Service set on creation and the service_transfer_id is the ID of the transfer for that service (also specified when created) All the request parameters in this view are optional, and the previous values will stay if no new value is specified for a Transfer attribute - origin: a string with the description of the source which triggered the transfer - type: a string with one of the following options: [UPLOAD, COPY, MOVE, DOWNLOAD, EXPORT] - state: a string with one of the following options: [READY, STARTED, FAILED, ABORTED, FINISHED] - started_datetime: a valid ISO formatted datetime specifying the creation date of the transfer - finished_datetime: a valid ISO formatted datetime specifying the finished date of the transfer - bytes_to_transfer: an integer with the file size in bytes - filename: a string with the name of the file for the Transfer - reference_url: an optional string with an URL for getting more details on the transfer on the admin UI - reference_label: an optional string with a label to show on the admin UI for the reference - progress: an integer number between 0 and 100 specifying the transfer progress percentage - extra_data: an optional valid JSON string containing useful information for keeping track of the Transfer - details: an optional string providing additional information on the Transfer. Example body: { "origin": "API", "type": "UPLOAD", "state": "READY", "started_datetime": "2019-01-01T12:30:00+00:00", "finished_datetime": "", "bytes_to_transfer": "50", "filename": "myfilename.mov", "reference_url": "", "reference_label": "", "progress": "0", "extra_data": "{}", "details": "" } _This endpoint requires the role: portal_api_transfers_write_

Get transfer settings

Get the transfer settings for the current user. If the user does not have a default group or the group has not set up transfer settings it will return the global system transfer settings _This endpoint require logged in user but no particular roles_

Get system transfer settings

Get the system transfer settings. _This endpoint requires the role: portal_administrator_

Get transfer settings for a specified group

Get the transfer settings for a specified group. _This endpoint requires the role: portal_administrator_

Update transfer settings for a specified group

Update transfer settings for a specified group The body can contain the following parameters: - storage_mappings: a dict containing windows and mac mappings for a specified storage. See example body - upload_storage: storage ID of the storage that will be used for transfer for the group - max_bandwidth: max transfer bandwidth in MB/s - max_parallel_transfers: max amount of parallel transfers - allow_overwrite_bandwidth: is the user allowed to overwrite bandwidth setting - allow_overwrite_parallel_transfers: is the user allowed to overwrite parallel transfers Example body: { "storage_mappings": { 'VX-1': {'windows': '/Windows/media1', 'mac': '/Mac/media1'}, 'VX-2': {'windows': '', 'mac': ''} }, "max_bandwidth": 91, "max_parallel_transfers": 94, "allow_overwrite_bandwidth": true, "allow_overwrite_parallel_transfers": true, "upload_storage": "VX-1" } _This endpoint requires the role: portal_administrator_

List usage report

Returns all the usage records from the system _This endpoint requires the role: portal_administrator_

Export usage report in CSV format

Create a downloadable CSV from a JSON input. The body can contain the following parameters: - object_name: any valid unique object key, - app_id: a valid portal app id, - month: integer between 1 - 12 - year: integer - users: boolean - whether to include detailed reports - group: an array of valid system group names Example Body: { "0": { "app_id": "com.cantemo.portal.core.search", "month": "2", "year": "2019", "users": 1 }, "1": { "app_id": "com.cantemo.portal.annotationtool", "month": "2", "year": "2019", "users": 0 }, "2": { "app_id": "com.cantemo.portal.core.search", "month": "2", "year": "2018", "users": 1 }, "group": ["Admin", "test"] } _This endpoint requires the role: portal_administrator_

Export usage report in PDF format

Create a downloadable PDF from a JSON input. The body can contain the following parameters: - object_name: any valid unique object key, - app_id: a valid portal app id, - month: integer between 1 - 12 - year: integer - users: boolean - whether to include detailed reports - group: an array of valid system group names Example Body: { "0": { "app_id": "com.cantemo.portal.core.search", "month": "2", "year": "2019", "users": 1 }, "1": { "app_id": "com.cantemo.portal.annotationtool", "month": "2", "year": "2019", "users": 0 }, "2": { "app_id": "com.cantemo.portal.core.search", "month": "2", "year": "2018", "users": 1 }, "group": ["Admin", "test"] } _This endpoint requires the role: portal_administrator_

List grouped usage records

Returns all the usage records from the system grouped by date and app_id. Get all the usage records from the system grouped by date and app_id. Example Response: { "usage_data": [ { "app_active_users": "50", "app_id": "com.cantemo.portal.annotationtool", "app_name": "Annotation Tool", "month": "2019-10-01 00:00:00" }, ... ], "total": 2 } _This endpoint requires the role: portal_administrator_

Get usage report data for a specified app

Returns usage report data for a specified app _This endpoint requires the role: portal_administrator_

Get usage report data

Returns usage report data for a specified app _This endpoint requires the role: portal_administrator_

List users

List and Search for Users Requester User should have at least one of the following roles: * portal_api_users_list_own: To be able to list/search for users belonging to the same groups as him. * portal_api_users_list_all: To be able to list/search all users in Portal _This endpoint require logged in user but no particular roles_

Get user details

Retrieves user details, based on the username Requester User should have at least one of the following roles: * portal_api_users_list_own: To be able to list/search for users belonging to the same groups as him. * portal_api_users_list_all: To be able to list/search all users in Portal _This endpoint require logged in user but no particular roles_

Get the version information

This resource returns the version information for the system _This endpoint requires the role: portal_api_system_version_

Get detailed information about the current user

Get detailed information about the current user. _This endpoint require logged in user but no particular roles_