Assets

Definition

An Asset is a file that can be Reviewed. While typically a .pdf, Red Marker also supports .doc, .docx and many other common file types.

Create an Asset

Creating an Asset involves a two-part process.

Step 1 - Create the Asset resource

Create an Asset with the intended file's details; file name, file size, and mimetype. The API will respond with validation errors if anything is invalid, or create the Asset resource if successful. Upon successful creation, upload the actual file itself in Step 2.

Request

POST /v2/assets HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "type": "assets",
    "attributes": {
      "title": "Marketing Brochure",
      "filename": "marketing_brochure.pdf",
      "filesize": 1363148,
      "mimetype": "application/pdf"
    }
  }
}

Response

HTTP/1.1 201 Created
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "assets",
    "id": "37",
    "attributes": {
      "title": "Marketing Brochure",
      "filename": "marketing_brochure.pdf",
      "filesize": 1363148,
      "mimetype": "application/pdf",
      "status": "pending-upload",
      "createdAt": "2019-07-17T00:00:00+00:00",
      "updatedAt": "2019-07-17T00:00:00+00:00"
    },
    "relationships": {
      "owner": {
        "data": {
          "type": "companies",
          "id": "1"
        }
      },
      "creator": {
        "data": {
          "type": "users",
          "id": "1"
        }
      }
    },
    "links": {
      "self": "http://api.redmarker.ai/v2/assets/37",
      "upload": "http://api.redmarker.ai/v2/assets/37/upload"
    }
  }
}

Step 2 - Upload the file to the Asset

In the response for Step 1, an upload link is returned. Upload the file to this link as a multipart form request.

Red Marker accepts PDF, Word (docx), PowerPoint (pptx), Images (jpg, png) and Email (eml) files. All documents are converted to PDF on upload to Red Marker.

JSON:API Non-compliant

The following does not conform specifically to JSON:API due to it not supporting multipart/form-data uploads, however the response will be in JSON:API format.

Request

File field

The file data should be set under the asset key in the request.

(multipart form upload to URL defined in data.links.upload from above response)

Example JavaScript

const asset = getAsset() // method to retrieve an Asset record
const data = new FormData()
data.append('asset', file) // where file is of the File class, selected by the user
const config = {
  headers: {
      'Content-Type': 'multipart/form-data', 
      Accept: 'application/vnd.api+json',
  },
}

axios.post(asset.links.upload, data, config) //asset.links.upload is the Asset's Upload Link from a Create response

Response

HTTP/1.1 201 Created
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "assets",
    "id": "37",
    "attributes": {
      "title": "Marketing Brochure",
      "filename": "marketing_brochure.pdf",
      "filesize": 1363148,
      "mimetype": "application/pdf",
      "status": "processing",
      "createdAt": "2019-07-17T00:00:00+00:00",
      "updatedAt": "2019-07-17T00:00:00+00:00"
    },
    "relationships": {
      "owner": {
        "data": {
          "type": "companies",
          "id": "1"
        }
      },
      "creator": {
        "data": {
          "type": "users",
          "id": "1"
        }
      }
    },
    "links": {
      "self": "http://api.redmarker.ai/v2/assets/37"
    }
  }
}

Note how the status changes to processing after upload, and the upload link is no longer returned.

Step 3 - Asset Processing

Assets, once uploaded, go through a processing stage where we extract text, images, etc from the uploaded document.

This is an asynchronous process that can take some time depending on the size of the Asset, so if the processing of an Asset is important to your requirements, you will need to query the Asset and check it's status attribute.

Request

GET /v2/assets/37 HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "assets",
    "id": "37",
    "attributes": {
      "title": "Marketing Brochure",
      "filename": "marketing_brochure.pdf",
      "filesize": 1363148,
      "mimetype": "application/pdf",
      "status": "ready",
      "createdAt": "2019-07-17T00:00:00+00:00",
      "updatedAt": "2019-07-17T00:00:00+00:00"
    },
    "relationships": {
      "owner": {
        "data": {
          "type": "companies",
          "id": "1"
        }
      },
      "creator": {
        "data": {
          "type": "users",
          "id": "1"
        }
      }
    },
    "links": {
      "self": "http://api.redmarker.ai/v2/assets/37"
    }
  }
}

Status success

When the data.attributes.status changes to ready, it indicates that the Asset has been processed and can be used to create a Review.

Status failed

If the data.attributes.status changes to failed, it indicates that the Asset has failed processing and can not be used to start a Review.