Context API Usage

This tutorial guides you through the steps required to upload a file, process it, and retrieve the results using the Context API.

Prerequisites

Before using the Context API, ensure you have the following:

Token endpoint for your OAuth instance
Client Id and Client Secret for authentication
API endpoint for the file upload and processing service

Using the API

You can call the Context API by sending HTTP requests directly.

Using an HTTP Request Tool

Once you have acquired and used an access token (see Authentication), you can start making calls to the Context API to upload files to an AWS S3 bucket for your pipeline and download the results. For full reference information on the Context API's endpoints, see Endpoints.

tip

Use an HTTP request tool such as Bruno to simplify the process of making the sequential API calls.

To make calls to the Context API:

Open your preferred HTTP request tool.
Enter a request to create presigned URLs for uploading files to an AWS S3 bucket. This URL allows secure file uploads to the storage bucket without requiring direct access credentials. The objectKey returned in the response uniquely identifies the file in the storage bucket.

Send a GET request to the API endpoint for generating a presigned URL.

Note: The desired content type, for example, image/jpeg, should be specified as a query parameter.
```
  {
  "method": "GET",
  "url": "api/files/upload/presigned-url?contentType=image%2Fjpeg",
  "headers": {
    "accept": "application/json"
  },
  "body": "No body"

}
```
A response similar to the following is displayed. The API returns a presigned URL and an objectKey. The presignedUrl is used to upload the file, and the objectKey is used for subsequent processing.
```
  {
  "status": 200,
  "statusText": "OK",
  "body": {
    "presignedUrl": "https://mock-bucket.s3.amazonaws.com/contents/mock-file-id.jpeg?mock-query-params",
    "objectKey": "contents/mock-file-id.jpeg"
  }
}
```
Upload the file to the storage bucket. The file must be sent as binary data in the request body.

Prepare a binary data for the file as described in the following steps:

Read the file from your local system using a programming language or tool of your choice.
Ensure the file is transmitted as raw binary data in the body of the request. The following is an example in JavaScript:

const fs = require('fs');
const binaryData = fs.readFileSync('path/to/image.jpeg');

Send a PUT request to the presignedUrl with the binary data in the body.

  {
  "method": "PUT",
  "url": "https://mock-bucket.s3.amazonaws.com/contents/mock-file-id.jpeg?mock-query-params",
  "headers": {
    "Accept": "*/*",
    "Content-Type": "image/jpeg"
  },
  "body": "Binary file data"
}

A response similar to the following is displayed:

{
  "status": 200,
  "statusText": "OK",
  "headers": {
    "etag": "\"mock-etag\"",
    "x-amz-server-side-encryption": "AES256",
    "content-length": "0",
    "server": "AmazonS3"
  },
  "body": ""
}

Request the API to process the uploaded file. The objectKey from the presigned URL response is used to identify the file, and the desired processing actions. For example, image-description are specified in the request body.

Send a POST request to the processing endpoint with the objectKey and actions.

  {
  "method": "POST",
  "url": "api/content/process",
  "headers": {
    "Content-Type": "application/json",
    "accept": "application/json"
  },
  "body": {
    "objectKeys": [
      "contents/mock-file-id.jpeg"
    ],
    "actions": [
      "image-description"
    ],
    "maxWordCount": 200
  }
}

A response similar to the following is displayed. The API returns a processing ID that you can use to retrieve the results.

  {
  "status": 200,
  "statusText": "OK",
  "body": "mock-processing-id"
}

Retrieve the results and construct the results URL using the processing-id returned in the previous step.

The following is the URL format:

api/content/process/{processing-id}/results

Replace {processing-id} with the actual processing ID.

Send a GET request to the constructed URL to retrieve the results.

  {
  "method": "GET",
  "url": "api/content/process/mock-processing-id/results",
  "headers": {
    "accept": "*/*"
  },
  "body": "No body"
}

A response similar to the following is displayed, where the API returns the processed data.

{
  "status": 200,
  "statusText": "OK",
  "body": {
    "id": "mock-processing-id",
    "timestamp": "2025-04-04T08:01:56.000Z",
    "results": [
      {
        "objectKey": "contents/mock-file-id.jpeg",
        "imageDescription": {
          "isSuccess": true,
          "result": "The image shows a mock description of the content.",
          "error": null
        }
      }
    ]
  }
}

Prerequisites​

Using the API​

Using an HTTP Request Tool​

Prerequisites

Using the API

Using an HTTP Request Tool