Content Management

Overview

Managing content within the Fastevo Media Protection Platform (Fastevo MP2) allows you to perform various operations such as creating, modifying, deleting content, and managing folders. This can be done using the API by performing requests to the appropriate endpoints.

Getting Media Contents List with Pagination

To retrieve a list of media contents with pagination, you need to perform a GET request to the following endpoint:

GET https://api.fastevo.net/api/v1/projects/mediaProtection/contents

You can include the following query parameters to customize the response: page, limit, orderBy, order, filter, folderPath, status, contentType.

Query Parameters

• page (optional): The page number to retrieve.
• limit (optional): The number of items per page.
• orderBy (optional): The field to order by. Options are title, contentType, status, _id.
• order (optional): The order direction. Options are asc for ascending and desc for descending.
• filter (optional): A string to filter the contents based on title or id.
• folderPath (optional): The folder path to filter the contents. If * is specified, it looks for contents in any folder. If left null or empty, it will look only in the root folder.
• status (optional): Provide one or more status values separated by commas (e.g., status=ready,processing,error).
  If multiple statuses are provided, it will return contents matching any of those statuses (an OR filter).
• contentType (optional): Provide one or more content types separated by commas (e.g., contentType=video,audio).
  If multiple types are provided, it will return contents matching any of those types (an OR filter).

API Response

The API will return a response with a status code of 200 and a JSON body containing the list of media contents along with pagination details.

Example Response

{
  "currentPage": 1,
  "totalPages": 10,
  "totalRecords": 100,
  "subFolders": ["folder1", "folder2"],
  "data": [
    {
      "_id": "string",
      "aspectRatio": "16:9",
      "createdAt": "2023-10-01T12:34:56.789Z",
      "title": "Content title",
      "contentType": "video",
      "durationInSeconds": 120,
      "allowReprocess": true,
      "status": "ready",
      "subtitles": ["en", "es"],
      "watermarkProfile": "TWM1",
      "videoQualities": ["1080p", "720p"],
      "folderPath": "folder1/subfolder1",
      "engageKit": [
        {
          "fileType": "autoSnapshot",
          "signedUrl": "string"
        }
      ],
      "poster": {
        "_id": "posterId",
        "signedUrl": "https://signed.url/to/poster.png",
        "includedInEngageKit": true
      },
      "tags": ["tag1", "tag2"]
    }
  ]
}

Explanation of Response Fields

• currentPage: The current page number.
• totalPages: The total number of pages available.
• totalRecords: The total number of media content records.
• subFolders: An array of subfolder names within the current folder.
• data: An array of media content objects, each containing:
  • _id: The unique identifier of the media content.
  • aspectRatio: The aspect ratio of the media content.
  • createdAt: The timestamp when the content was created, in ISO 8601 format.
  • title: The title of the media content.
  • contentType: The type of the content (e.g., video, audio).
  • durationInSeconds: The duration of the content in seconds.
  • allowReprocess: A boolean indicating whether reprocessing is allowed.
  • status: The current status of the content (for example, "ready").
    Possible values: pendingUpload, queued, processing, deleting, ready, error.
  • progress (optional): A number (0–100) representing the current processing progress. Only present when the status is "processing".
  • subtitles: An array of available subtitle languages.
  • watermarkProfile: The watermark profile applied to the content.
  • videoQualities: An array of available video quality options.
  • folderPath: The folder path where the content is stored.
  • engageKit: An array of engage kit items, each containing fileType and signedUrl.
  • poster: An object containing details about the poster image, including _id, signedUrl, and includedInEngageKit.
  • tags: An array of strings representing tags associated with the content.

Ordering and Filtering

To order the media contents by their creation date, you should query the order on _id. This represents a similar ordering to createdAt since the _id field is generated based on the creation time.

You can also use the filter query parameter to filter the contents based on the title or id. To look in any folder, set folderPath to *.

Additionally, you can filter by status and contentType if needed.

Getting Media Content

To retrieve details of a specific piece of content, you need to perform a GET request to the following endpoint:

GET https://api.fastevo.net/api/v1/projects/mediaProtection/contents/{contentId}

Replace {contentId} with the actual contentId of the media content you wish to retrieve.

API Response

The API will return a response with a status code of 200 and a JSON body containing the content details.

Example Response

{
  "_id": "string",
  "aspectRatio": "16:9",
  "createdAt": "2023-10-01T12:34:56.789Z",
  "title": "New title",
  "contentType": "video",
  "durationInSeconds": 61,
  "allowReprocess": true,
  "status": "ready",
  "subtitles": ["en"],
  "watermarkProfile": "TWM1",
  "videoQualities": ["1080p", "720p", "480p", "360p", "240p"],
  "folderPath": "newFolder/pathToFolder2/subsubfolder/",
  "engageKit": [
    {
      "fileType": "autoSnapshot",
      "signedUrl": "string"
    }
  ],
  "poster": {
    "_id": "posterId",
    "signedUrl": "https://signed.url/to/poster.png",
    "includedInEngageKit": true
  },
  "tags": ["tag1", "tag2"]
}

Explanation of Response Fields

• _id: The unique identifier of the media content.
• aspectRatio: The aspect ratio of the media content.
• createdAt: The timestamp when the content was created, in ISO 8601 format.
• title: The title of the media content.
• contentType: The type of the content (e.g., video, audio).
• durationInSeconds: The duration of the content in seconds.
• allowReprocess: A boolean indicating whether reprocessing is allowed.
• status: The current status of the content (for example, "ready").
  Possible values: pendingUpload, queued, processing, deleting, ready, error.
• progress (optional): A number (0–100) representing the current processing progress. Only present when the status is "processing".
• subtitles: An array of available subtitle languages.
• watermarkProfile: The watermark profile applied to the content.
• videoQualities: An array of available video quality options.
• folderPath: The folder path where the content is stored.
• engageKit: An array of engage kit items, each containing fileType and signedUrl.
• poster: An object containing details about the poster image, including _id, signedUrl, and includedInEngageKit.
• tags: An array of strings representing tags associated with the content.

Downloading Original File

To download the original uploaded file for a specific piece of content, you need to perform a GET request to the following endpoint:

GET https://api.fastevo.net/api/v1/projects/mediaProtection/contents/{contentId}/original

Replace {contentId} with the actual contentId of the media content you wish to download.

Authentication Requirements

• Project setting: originalDownloads.isEnabled must be true.
• Human user: A project owner, organization administrator, or authorized Fastevo system administrator must authenticate with a valid user Bearer token, have 2FA configured, and include a current OTP in the X-OTP-Code header.
• Project API key: Any active API key for the project can use this endpoint without an OTP while the setting is enabled.

Human User Request

curl -X GET "https://api.fastevo.net/api/v1/projects/mediaProtection/contents/{contentId}/original" \
  -H "Authorization: Bearer USER_TOKEN||PROJECT_ID" \
  -H "X-OTP-Code: 123456"

For human users, 2FA is mandatory even if the account did not previously enable it. A request without configured 2FA returns 428 Precondition Required with code OTP_SETUP_REQUIRED; when 2FA is configured but the OTP header is omitted, the response is 428 Precondition Required with code OTP_CODE_REQUIRED. A malformed OTP returns 400, while an incorrect six-digit OTP returns 401.

Project API Key Request

curl -X GET "https://api.fastevo.net/api/v1/projects/mediaProtection/contents/{contentId}/original" \
  -H "Authorization: Bearer PROJECT_API_KEY"

Do not send an OTP with an API key. The project-level setting is the explicit authorization control for automated downloads.

API Response

The API will return a response with a status code of 200 and a JSON body containing a signed URL to download the original file.

Example Response

{
  "location": "https://cdn.fastevo.net/signed-url-to-original-file",
  "fileName": "original-video.mp4",
  "fileSizeInBytes": 104857600,
  "expiresAt": "2024-01-15T12:00:00.000Z",
  "contentStatus": "ready"
}

Explanation of Response Fields

• location: A signed CloudFront URL that allows you to download the original file. This URL expires after one hour.
• fileName: The original name of the uploaded file.
• fileSizeInBytes: The size of the original file in bytes.
• expiresAt: The timestamp when the signed URL will expire, in ISO 8601 format.
• contentStatus: The current status of the content.

Error Responses

Modifying Content Attributes

To modify the attributes of a specific piece of content, you need to perform a PUT request to the following endpoint:

PUT https://api.fastevo.net/api/v1/projects/mediaProtection/contents/{contentId}

Replace {contentId} with the actual contentId of the media content you wish to modify.

The request body can include the following parameters:

• title (optional): The new title for the content.
• folderPath (optional): The new folder path within Fastevo where the content will be stored.
• watermarkProfile (optional): The name of the new watermark profile to apply to the content.
• tags (optional): An array of strings representing the new tags to replace the existing tags associated with the content.

Example Request

{
  "title": "New title",
  "folderPath": "/newFolder",
  "watermarkProfile": "TWM1",
  "tags": ["newTag1", "newTag2"]
}

API Response

After successfully modifying the content, the API will return a response with a status code of 200 and a JSON body indicating success. If no changes are made, the API will return a status code of 204.

Example Success Response

{
  "success": true
}

Deleting Media Content

To delete a specific piece of content, you need to perform a DELETE request to the following endpoint:

DELETE https://api.fastevo.net/api/v1/projects/mediaProtection/contents/{contentId}

Replace {contentId} with the actual contentId of the media content you wish to delete.

Trash Mechanism

• If the content is in pendingUpload or queued status, it will be deleted immediately, as there is no finalized content to preserve.
• For any other status, deleting the content will move it to a “trash” area, where it is retained for 30 days. During this period, content remains secure in case of accidents or unauthorized account access.
• After 30 days (if not restored), the content will be permanently deleted from the system.
• Restoring content from trash or viewing its details in trash requires the use of specific trash endpoints. For more information, refer to Content Trash Documentation.

API Response

• After successfully moving the content to trash (or deleting it if it was in pendingUpload), the API will return a response with:
  • 204 status code for a successful deletion or move to trash.

Creating a Folder

To create a new folder, you need to perform a POST request to the following endpoint:

POST https://api.fastevo.net/api/v1/projects/mediaProtection/contents/folders

The request body should include the folderPath parameter.

Example Request

{
  "folderPath": "/newFolder"
}

API Response

After successfully creating the folder, the API will return a response with a status code of 201 and a JSON body indicating success.

Deleting a Folder

To delete a specific folder, you need to perform a DELETE request to the following endpoint:

DELETE https://api.fastevo.net/api/v1/projects/mediaProtection/contents/folders

The request body should include the folderPath parameter.

Example Request

{
  "folderPath": "/folderToDelete"
}

Important Note

If the folder contains any content, it cannot be deleted unless all content has been deleted or moved to trash. You must first delete or move all content within the folder before attempting to delete the folder itself.

API Response

After successfully deleting the folder, the API will return a response with a status code of 204.