PrizmDoc® v14.3 Release - Updated January 14, 2025
PrizmDoc Video / PrizmDoc Video REST API / Media
Media

Media

The Media REST API is used to download and upload videos for viewing in PrizmDoc.

Available URLs

URL Description
GET /api/v1/media/:fileId/video Downloads the video for viewing.
POST /api/v1/media when body is file bytes Uploads the video for viewing.
POST /api/v1/media when body is JSON Creates a File ID for viewing an existing video located on PrizmDoc Server’s storage.

GET /api/v1/media/:fileId/video

Downloads the video for viewing.

Parameter

Field Type Description
fileId String File ID returned from /api/v1/media.

Query Parameter(s)

Field Type Description
AffinityToken String Affinity Token returned on upload (only when PrizmDoc is in cluster mode).

Success 200

Field Type Description
body ReadableStream Byte stream of the video uploaded to /api/v1/media.

Success-Response

HTTP/1.1 200 OK
<video file bytes>

Error 4xx

Name Description
NotFound The fileID specified in the URL path was not found.

Error-Response

HTTP/1.1 404 Not Found
{ }

POST /api/v1/media when body is file bytes

Uploads the video for viewing.

Header

Field Type Description
Content-Type String Mime type of file. Expected to be one of video/mp4, video/webm, video/ogg, application/octet-stream.

Request Body

Field Type Description
Body ArrayBuffer Video file bytes.

Success 200

Field Type Description
fileID String Identifier associated with uploaded file.
affinityToken String Identifier indicating the PrizmDoc Server instance that processed the request (only when running PrizmDoc Server in cluster mode).

Success-Response

HTTP/1.1 200 OK
{
  "fileId": "zgOGNBUIjfRHF2g4SNz1_A"
}

Success-Response with Affinity Token

HTTP/1.1 200 OK
{
  "fileId": "zgOGNBUIjfRHF2g4SNz1_A",
  "affinityToken":"zTfGFeeRXKxPF5o4HgnFFgZ6YU6bcbvMsJdJciYJemo="
}

Error 4xx

Name Description
FeatureNotLicensed The file exceeds evaluation limit of 5MB.
MissingInput Content-Type header is missing.
InvalidInput Content-Type header is not a valid value.

413 FeatureNotLicensed

HTTP/1.1 413 FeatureNotLicensed
{
  "errorCode": "FeatureNotLicensed",
  "errorDetails": {
    "in": "body",
    "at": "length",
    "expected": {
      "lessThanOrEqualTo": 5242880
    }
  }
}

480 MissingInput

HTTP/1.1 480 MissingInput
{
  "errorCode": "MissingInput",
  "errorDetails": {
    "in": "headers",
    "at": "Content-Type",
    "expected": {
      "oneOf": [
        {
          "value": "video/mp4"
        },
        {
          "value": "video/webm"
        },
        {
          "value": "video/ogg"
        },
        {
          "value": "application/octet-stream"
        }
      ]
    }
  }
}

480 InvalidInput

HTTP/1.1 480 InvalidInput
{
  "errorCode": "InvalidInput",
  "errorDetails": {
    "in": "headers",
    "at": "Content-Type",
    "expected": {
      "oneOf": [
        {
          "value": "video/mp4"
        },
        {
          "value": "video/webm"
        },
        {
          "value": "video/ogg"
        },
        {
          "value": "application/octet-stream"
        }
      ]
    }
  }
}

POST /api/v1/media when body is JSON

Creates a File ID for an existing video located on PrizmDoc Server’s storage. This feature is only available for single server configurations in licensed mode and requires the central configuration parameter workFiles.external.file.directory to be set on PrizmDoc server. Please contact info@accusoft.com to obtain a license.

NOTE: If the video file is modified after the creation of the File ID, consequent GET /api/v1/media/:fileId/video requests will download the modified version.

Request Header

Field Type Description
Content-Type String Must be application/json.

Request Body

A JSON object that conforms to the following:

  • type (String) Required. The type of storage. Must be “file”.
  • fileExtension (String) Required. Extension of the video. Supported extensions are .mp4, .ogg, and .webm
  • file (Object) Required. Object containing information of the “file” storage type.
    • path (String) Required. Relative path to the video which should be accessible by the PrizmDoc Server. The video file must be located inside the directory specified in PrizmDoc Server's workFiles.external.file.directory central configuration parameter.

Example:

{
    "type": "file",
    "fileExtension": "mp4",
    "file": {
      "path": "./videos/presentations/video.mp4"
    }
}

Successful Response

Response Header

Field Type Description
Content-Type String application/json.

Response Body

A JSON object with the following properties:

  • fileID (String) Identifier associated with local video.

Example:

HTTP/1.1 200 OK
{
  "fileId": "zgOGNBUIjfRHF2g4SNz1_A"
}

Error Responses

Status Code JSON errorCode Description
413 FeatureNotLicensed The server is not licensed to use the requested feature or API.
480 MissingInput Content-Type or object in body is missing.
480 InvalidInput Unsupported file extension.
480 ExternalContentNotFound The file specified in the path does not exist or is not accessible.
480 IncorrectUsage workFiles.external.file.directory has not been configured in PrizmDoc Server, an absolute path has been provided for the file, or the relative path points outside of the directory specified in workFiles.external.file.directory.

413 FeatureNotLicensed

HTTP/1.1 413 FeatureNotLicensed
{
  "errorCode": "FeatureNotLicensed",
  "errorDetails": "The server's license does not allow the use of the requested feature or API."
}

480 MissingInput

HTTP/1.1 480 MissingInput
{
  "errorCode": "MissingInput",
  "errorDetails": {
   "in": "body",
   "at": "file",
   "expected": {
     "type": "object"
    },
    "when": [
      {
        "otherInput": {
          "in": "body",
          "at": "type",
          "is": {
            "value": "file"
          }
        }
      }
    ]
  }
}

480 InvalidInput

HTTP/1.1 480 InvalidInput
{
  "errorCode": "InvalidInput",
  "errorDetails": {
    "in": "body",
    "at": "fileExtension",
    "expected": {
      "oneOf": [
        {
          "value": "mp4"
        },
        {
          "value": "webm"
        },
        {
          "value": "ogg"
        }
      ]
    }
  }
}

480 ExternalContentNotFound

HTTP/1.1 480 ExternalContentNotFound
{
  "errorCode": "ExternalContentNotFound"
}

480 IncorrectUsage

HTTP/1.1 480 IncorrectUsage
{
  "errorCode": "IncorrectUsage"
}