# API Endpoint Reference Tenovos offers a REST API for partner and customer integrations. This API provides a RESTful endpoint, token-based authorization, HTTP methods for operations, and JSON-formatted payloads. Use this API to incorporate Tenovos functionality into your own application. This API is up-versioned when a breaking change is introduced such as - a change in the format of the response data for one or more calls - a change in the request or response type (i.e. changing an integer to a float) - removing any part of the API. This API is not up-versioned for non-breaking changes such as - new endpoints - new response parameters - new optional request parameters Version: 1.0 License: Tenovos Active Story Management ## Servers ``` https://enterprise.services.tenovos.io/content-store-v1 ``` ``` https://enterprise-2.services.tenovos.io/content-store-v1 ``` ``` https://enterprise3.services.tenovos.io/content-store-v1 ``` ``` https://enterprise-4.services.tenovos.io/content-store-v1 ``` ## Security ### bearerAuth Type: http Scheme: bearer Bearer Format: JWT ### BasicAuth Type: http Scheme: basic ### ApiKeyAuth Type: apiKey In: header Name: X-API-Key ## Download OpenAPI description [API Endpoint Reference](https://api.tenovos.com/_bundle/openapi/v1.yaml) ## Action Operations Invoke the Action API to retrieve information about invoked Actions. ### Get details about an invoked Action. - [GET /action/{id}](https://api.tenovos.com/openapi/v1/action-operations/getaction.md): Retrieve an Action by specifying an Object ID or File ID in the request path. The user requesting the Action must have view access to the Action in order to retrieve the Action. ## Asset Operations Invoke the Asset API to create, retrieve, manipulate, and share Assets. This API also provides operations to manage Asset relationships and download Asset content. ### Create an Asset. - [POST /asset](https://api.tenovos.com/openapi/v1/asset-operations/createasset.md): Use this service to perform one of the following operations: 1) Create a new Asset 2) Create a new Version of an existing Asset 3) Create a new Metadata-only Asset Once the new Asset or Asset Version is created, a new Object ID is returned to identify the new Asset / Asset Version. When a new Asset is created, the Asset is considered a metadata-only Asset until a corresponding content file is uploaded. The Asset's content file size must be less than or equal to 5GB. After invoking the Create Asset service, the response shall include a signed URL to upload the content file. The upload should be performed using a PUT request with the file content attached as binary data in the request body. After creating an asset greater than 100MB, multiple presigned urls will be returned. You must upload file chunks of 100MB to each one. You must call the /asset/complete endpoint to complete or cancel a multi-part file upload, otherwise the file will not be available to Tenovos. The user submitting the request to create an Asset must have the Upload Security Role Privilege and be granted access to at least one Security Template to assign to the new Asset. ### Bulk edit one or more Assets. - [PATCH /asset](https://api.tenovos.com/openapi/v1/asset-operations/editassets.md): Perform metadata edits and/or reassign Security Templates to one or more Assets. Assets are identified by Object ID. If multiple Assets are specified, the same metadata and/or security edits will be applied to all Assets in the request. Each Metadata Attribute is identified by a Metadata Definition ID. The user performing the bulk edit must have the Edit Metadata permission granted on each Asset being edited. ### Get a single Asset. - [GET /asset/{id}](https://api.tenovos.com/openapi/v1/asset-operations/getasset.md): Retrieve an Asset by specifying an Object ID or File ID in the request path. The user requesting the Asset must have view access to the Asset in order to retrieve the Asset. ### Update a single Asset. - [PATCH /asset/{id}](https://api.tenovos.com/openapi/v1/asset-operations/updateasset.md): Update the metadata attributes and/or the Security Template assignments for an Asset identified by Object ID. The Object ID must be specified in the request path. The user submitting the request must have edit access to the Asset. ### Get the content file download link of an Asset. - [GET /asset/{id}/content](https://api.tenovos.com/openapi/v1/asset-operations/getassetcontent.md): Retrieve a presigned URL to the Asset's source file by Object ID. The user requesting the Asset's source file must have download access to the Asset. ### Soft Delete or Un-delete an Asset. - [POST /asset/{id}/delete](https://api.tenovos.com/openapi/v1/asset-operations/deleteasset.md): Soft delete or un-delete an Asset. An Asset that has been soft-deleted can be later purged from the recycle bin. A soft-deleted Asset cannot be edited or downloaded. The user attempting to soft delete or un-delete an Asset must be granted the Delete Security Template permission on the Asset. ### Get latest version of an Asset. - [GET /asset/{id}/latest](https://api.tenovos.com/openapi/v1/asset-operations/getlatestversion.md): Retrieve latest version of an Asset by specifying an Object ID in the request path. The user requesting the Asset must have view access to the Asset in order to retrieve the Asset. ### Retrieve Asset relationships associated with an Asset. - [GET /asset/{id}/link](https://api.tenovos.com/openapi/v1/asset-operations/getassetrelationship.md): Retrieve all Asset relationships associated with an Asset specified by Object ID. In a relationship, the Asset can be a primary or secondary (related) Asset. For example, in a parent / derivative relationship, the primary Asset would be the parent, while the secondary Asset would be the derivative. Both the Object ID and relationship type for each Asset will be returned. Relationships will be retrieved where the Asset is a primary or secondary Asset. The user requesting the Asset relationships must have View access to both the primary Asset and the secondary Assets in order to retrieve the relationships. ### Create a relationship between Assets. - [POST /asset/{id}/link](https://api.tenovos.com/openapi/v1/asset-operations/createrelationship.md): Create a bidirectional relationship between a primary Asset and one or more secondary Assets. Asset relationships allow a user to quickly navigate from one Asset to another related Asset. The user attempting to create a relationship using Asset must be granted the Relationship Security Template permission on the Asset. ### Remove a relationship between Assets. - [PATCH /asset/{id}/link](https://api.tenovos.com/openapi/v1/asset-operations/removerelationship.md): Remove a relationship between a primary Asset and one or more secondary Assets. Specify the primary Asset Object ID as a path parameter. Specify the secondary Asset Object IDs and Link Types as an array in the request body. The user requesting the Asset relationships must have view access to both the primary Asset and the related Assets in order to relationships and the related Assets. ### Get the version history of an Asset. - [GET /asset/{id}/version](https://api.tenovos.com/openapi/v1/asset-operations/getversions.md): Retrieve a list of all versions of an Asset by specifying an Object ID or Original File ID in the request path. The user requesting the Asset must have view access to the Asset in order to retrieve the Asset version history. ### Complete Upload. - [POST /asset/complete](https://api.tenovos.com/openapi/v1/asset-operations/finishupload.md): Complete/Cancel multipart upload once all parts are uploaded. This endpoint must be called after creating asset when the file is sent in chunks of 100MB each. For files 100MB or less in size this operation is not needed. ### Assign an image or PDF to be the new preview for one or more Assets. - [POST /asset/content/preview](https://api.tenovos.com/openapi/v1/asset-operations/replacepreview.md): Generate a request to upload an image or PDF file to be the new preview for one or more Assets. Supported preview image formats include: GIF, JPG, PNG, and TIFF. If a PDF file is uploaded to be the preview for a document Asset, then the PDF will also be displayed in the Asset Detail page as the multi-page PDF preview. After submitting the request to replace an Asset preview, The user replacing the Asset previews must be granted the Replace Mezzanine and Upload User Role Permissions and View Security Template Permission on the Assets being updated. For Federated Assets, if user provides optional contentPaths key in the request body, then files referenced in the contentPaths > properties are used as renditions. ### Exposes Content. - [POST /asset/expose](https://api.tenovos.com/openapi/v1/asset-operations/getasseturl.md): Exposes Asset's pre-signed urls with expiration time given in seconds Asset being exposed needs to have a Security Template with Download permission and and User must have role with Download privilege. ### Share a selection of Assets. - [POST /asset/share](https://api.tenovos.com/openapi/v1/asset-operations/shareassets.md): Share a selection of Assets to a user specified by Email address. The user sharing the Assets must be granted the Download Security Template permission on the Assets being shared. ### Share or download transformation of an Assets. - [POST /asset/transform](https://api.tenovos.com/openapi/v1/asset-operations/gettransformation.md): Transform asset and download or share transformation with an email. If email is available then this API will share link (send email) of transformed file. Note: Access to this API Service is currently limited. Contact Tenovos Customer Support to inquire further about access to this API Service if needed. ## Authentication Operations Invoke the Authentication API to generate, refresh, and revoke access tokens. An access token is required to perform any authorized API operation. ### Request/Refresh an access token. - [POST /auth/token](https://api.tenovos.com/openapi/v1/authentication-operations/getauthtoken.md): Use this operation to request an access token to perform other API operations that require authorization. The authentication response includes an accessToken which is used as the AccessToken request header when performing any authenticated operation. This operation will also accept the previous authentication response as the request payload to return a refreshed access token. The access token expires after 1 hour and must be refreshed after expiration, using the included refreshToken. The refresh token can be used for up to 30 days to request new access tokens, or until the refresh token is revoked. Once the refresh token expires or is revoked, the user credentials must be provided again to generate a new access token and refresh token. ### Expire an access token. - [DELETE /auth/token](https://api.tenovos.com/openapi/v1/authentication-operations/expiretoken.md): Expire an access token before the token's expiration date and revoke access to the system. Access tokens normally expire within an hour. This operation expires an access token upon request so that the token may no longer be used for future operations. The Request Body must be a JSON object. The following parameters are required to expire the access token: { "endpointUrl": "URL", "clientId": "string", "userPoolId": "string", "username": "string", "password": "string", "session": { "accessToken": "string", "refreshToken": "string", "authorization": "string" } } ### Impersonate a given user. (deprecated) - [POST /auth/impersonate](https://api.tenovos.com/openapi/v1/authentication-operations/impersonate.md): Use this operation to request an access token to perform other API operations that require authorization. The authentication response includes an accessToken which is used as the AccessToken request header when performing any authenticated operation. This operation will also accept the previous authentication response as the request payload to return a refreshed access token. The access token expires after 1 hour and must be refreshed after expiration, using the included refreshToken. The refresh token can be used for up to 30 days to request new access tokens, or until the refresh token is revoked. Once the refresh token expires or is revoked, the user credentials must be provided again to generate a new access token and refresh token. ## Collection Operations Invoke the Collection API to create, retrieve, edit, and delete Collections. Collections are used to group and catalog related Assets for quick access and consumption. Collections can be configured as: - private: Visible only to the user who created the Collection. - secured: Visible to shared users with permission. When retrieving the Assets within a Collection, the requesting user will only see the Assets that the user has access to view. For example, a librarian may see all Assets within a Collection, but a general consumer user may only see a portion of those Assets, due to limited security access. ### Create a Collection. - [POST /collection](https://api.tenovos.com/openapi/v1/collection-operations/createcollection.md): Create a collection and add assets to it. Assets in the collection are identified by FileID therefore collectionDocument contains File ID The user should have View permission on assets to be added to the collection. ### Get a single Collection and assigned Assets. - [GET /collection/{id}](https://api.tenovos.com/openapi/v1/collection-operations/getcollection.md): Retrieve a single Collection specified by Collection ID. The retrieved Collection may be either a secured Collection or a private Collection created by the User. The Collection will include the list of Assets assigned to the Collection, referenced by Asset File ID. The User retrieving the Collection must have the Collection Security Role Privilege. ### Delete a Collection. - [DELETE /collection/{id}](https://api.tenovos.com/openapi/v1/collection-operations/deletecollection.md): User can delete the collection, but the Assets assigned to the Collection will remain and dissociate from this Collection. The User submitting the request to delete a private Collection must have the Collection and Delete Security Role Privilege. Secured Collections may only be deleted by Users with the Purge Security Role Privilege. ### Update a Collection. - [PATCH /collection/{id}](https://api.tenovos.com/openapi/v1/collection-operations/updatecollection.md): Update a Collection's attributes or assigned Assets. The list of existing assets is replaced with assets provided in the call. Assets in the collection are referenced by Asset FileID therefore the collectionDocument must contain asset's FileID. The User editing the Collection must have the Collection Security Role Privilege. The User must have View access to the Assets that are being added to or removed from the Collection. ### Share all accessible Assets in a Collection. - [POST /collection/{id}/share](https://api.tenovos.com/openapi/v1/collection-operations/sharecollection.md): Share the zip file of all accessible Assets in a collection and send to the specified emails in share users list. User can also send the custom share message along with request. The user sharing the Assets must be granted the Download and Share Security Template permission on the Assets being shared. ## Customer Operations Invoke the Customer API to retrieve Customer account profile information. ### Get a parent Customer. - [GET /customer](https://api.tenovos.com/openapi/v1/customer-operations/getcustomer.md): Retrieve the parent Customer profile information of a current user. ## Metadata Operations Invoke the Metadata API to retrieve Metadata Template to be applied to Assets during Asset creation. A Metadata Template defines a set of Metadata Attributes of varying types, including Text, Date, Controlled Vocabulary, Tabular, and Cascading Attributes. When a Metadata Template is assigned to a new Asset, the corresponding Metadata Attributes will be available for population on the Asset. ### Retrieve all Metadata Templates available to the current User. - [GET /metadata/template](https://api.tenovos.com/openapi/v1/metadata-operations/getmetadatatemplates.md): Retrieve all metadata templates available to the requesting user The user submitting the request must have administrator rights to view metadata templates. ### Get Metadata Template by ID. - [GET /metadata/template/{id}](https://api.tenovos.com/openapi/v1/metadata-operations/getmetadatatemplate.md): Retrieve the metadata template and its attributes list by template ID The user submitting the request to metadata template must have the Metadata Template Management security role privilege. In response, it will contain the metadata groups template have and each group metadata attributes list. ### Retrieve all Controlled Vocabularies available to the current User. - [GET /metadata/vocabulary](https://api.tenovos.com/openapi/v1/metadata-operations/getallcontrolledvocab.md): Retrieve all the controlled vocabularies available to the current user. In response, it will contain the list of metadata key/value pair and metadata definition attributes like id, name, type and search fields etc. ### Create a Controlled Vocabulary. - [POST /metadata/vocabulary](https://api.tenovos.com/openapi/v1/metadata-operations/createcontrolledvocab.md): Create a Controlled Vocabulary. User must have permission to create a controlled vocabulary. In response, it will contain the object of metadata definition attributes like id, name, type and search fields etc. ### Get Controlled Vocabulary by ID. - [GET /metadata/vocabulary/{id}](https://api.tenovos.com/openapi/v1/metadata-operations/getcontrolledvocab.md): Retrieve the Controlled Vocabulary and its attributes by Controlled Vocabulary Id In response, it will contain the list of metadata key/value pair and metadata definition attributes like id, name, type and search fields etc. ### Remove a Controlled Vocabulary. - [DELETE /metadata/vocabulary/{id}](https://api.tenovos.com/openapi/v1/metadata-operations/deletecontrolledvocab.md): Delete a Controlled Vocabulary. ### Update a Controlled Vocabulary. - [PATCH /metadata/vocabulary/{id}](https://api.tenovos.com/openapi/v1/metadata-operations/updatecontrolledvocab.md): Update a Controlled Vocabulary. User must have permission to update a controlled vocabulary. In response, it will contain the object of metadata definition attributes like id, name, type and search fields etc. ### Apply the metadata definition changes. - [POST /metadata/apply](https://api.tenovos.com/openapi/v1/metadata-operations/applymetadatachanges.md): Apply the metadata definition changes. Use this operation after making any modification in metadata. In response, it will contain the object of metadata definition attributes like id, name, type and search fields etc. ## Search Operations Search for Collections by Collection name. Perform Asset searches using keywords or Attribute-specific search terms using the Keyword Search endpoint. Perform a scan on all assets based on search criteria using a cursor to page through the entire result set of assets. ### Scan assets by paging through an entire search result set. - [POST /asset/scan](https://api.tenovos.com/openapi/v1/search-operations/scanassets.md): Provides the ability to scan a search result set of assets using a cursor to fetch the next set of results pages on the limit (page size) passed. ### Search for Collections. Return a list of Collections. - [POST /search/collection](https://api.tenovos.com/openapi/v1/search-operations/searchcollections.md): Retrieve the collection list against the list of search terms/keywords. By default AND operation will be applied between the search terms. By default 50 collections will return, you can also set search offset by setting from attribute, for example for first page set from to zero and after that you set 50, 100, 150 and so on. ### Perform a Keyword Search. Return a list of Assets. - [POST /search/keyword](https://api.tenovos.com/openapi/v1/search-operations/search.md): To Retrieve the Assets list there is two types of searches available, Simple Keyword Search: Requesting user can get list of Assets against search terms/keywords list. For example ["keyword1", "keyword2"] Facet Search: Requesting user can get list of Assets against Facet value list. For example ["Facet: facet_value"] Targeted Search: Requesting user can target keyword searches against Filename, Asset ID, Metadata, or Content (extracted text from documents) by passing the optional property of keywordSearchField. Requesting user can apply the combination of both searches and if there is no keyword/facet in requesting body it will apply wildcard search. By default AND operation will be applied with search terms and/or facets. By default, up to 50 Assets will return from the search.You can also set search offset by setting the from property. For example, for the first page, set from to zero. After that set from to 50, 100, 150, etc. ## Security Operations Invoke the Metadata API to retrieve Security Template information to be applied to Assets during Asset creation or edit. ### Retrieve a list of Security Templates available to the current User. - [GET /security/template](https://api.tenovos.com/openapi/v1/security-operations/getsecuritytemplates.md): User will get the list of Security Templates available to him. The user submitting the request must have administrator rights to view Security Templates. In response user will get a list, containing template names and their corresponding template id. ### Retrieve a list of Security Groups. - [GET /security/groups](https://api.tenovos.com/openapi/v1/security-operations/getsecuritygroups.md): User will get the list of Security Groups available in the system. The user submitting the request must have administrator rights to User Management. In response user will get a list, containing group names and their corresponding group id. ## User Operations Invoke the User API to retrieve User profile information. ### Get the current User's Profile. - [GET /user](https://api.tenovos.com/openapi/v1/user-operations/getcurrentuser.md): Use this endpoint to get the user profile information for the account that you've authenticated against the Tenovos API with. This is useful when needing to check which groups you are in which may restrict the API calls you can make. ### Create a new User in system. - [POST /user](https://api.tenovos.com/openapi/v1/user-operations/createuser.md): Use this endpoint to create a new user account in the system. You must have User Management role privilege and Security Template Management role privilege in order to create a user and assign groups. This endpoint can be used to create local or federated users. ### Get User Profile by ID. - [GET /user/{id}](https://api.tenovos.com/openapi/v1/user-operations/getuser.md): Current user will get its profile information in response. User will also get ID of a role assign to him and a list of group IDs from which it belongs to. ### Update User attributes. - [PATCH /user/{id}](https://api.tenovos.com/openapi/v1/user-operations/updateuser.md): Update User Profile attributes such as First Name, Last Name, Friendly Name, Email, Company, Country, Contact, Phone, and User Role. The user role can be updated by sending either role id or role name. ### Add User to Security Group. - [PATCH /user/{id}/add-to-group](https://api.tenovos.com/openapi/v1/user-operations/addusertogroup.md): Assign a Security Group to a User Profile. ### Remove User from Security Group. - [PATCH /user/{id}/remove-from-group](https://api.tenovos.com/openapi/v1/user-operations/deletegroupfromuser.md): Remove an assigned Security Group from a User Profile. ### Search User Profiles by Text. - [GET /user/search/{searchText}](https://api.tenovos.com/openapi/v1/user-operations/getuserbytext.md): User will get a list of User Profiles matching the searchText in response. Provided searchText will be matched against the user attributes case insensitively - First Name, Last Name, Friendly Name, Email, Phone, Company, Contact, Country, Group Names, and Role Name. User will only see the list of users that are part of the user groups that it belongs to. ## Proof Operations ### Get workflow templates. - [GET /workflow-templates](https://api.tenovos.com/openapi/v1/proof-operations/getprooftemplate.md): Get active workflow templates. ### Get Proof Status. - [GET /proof/{id}/status](https://api.tenovos.com/openapi/v1/proof-operations/getproofstatus.md): Get Proof status and decision status ### Create a Proofing User. - [POST /proofing/user](https://api.tenovos.com/openapi/v1/proof-operations/createproofuser.md): Creates a Proofing User account. Must be a Story Orchestration customer and have available user licenses. ### Get Reviewer URL. - [POST /proof/{id}/reviewer-url](https://api.tenovos.com/openapi/v1/proof-operations/getreviewerurl.md): Get proof Reviewer URL. ## Cart Operations ### Create a Cart. - [POST /cart](https://api.tenovos.com/openapi/v1/cart-operations/createcart.md): Create a cart and add assets to it. Assets in the collection are identified by FileID therefore collectionDocument contains File ID