Skip to main content

Enriching Content with the Context API

This topic describes the asynchronous workflow for enriching a document or an image using the Context API: uploading the file, submitting an enrichment job, polling until the job completes, and retrieving the results.

For the full technical reference, see Context API Reference. For scripts you can run without modification, see Code Samples. For the full endpoint documentation, see Endpoints.

Prerequisites​

Workflow overview​

The following diagram shows the sequence of the enrichment workflow. The client requests a presigned URL, uploads the file, submits a processing job with the actions to apply, then polls for results until the job is no longer in progress.

Step 1: Get a presigned URL​

Request a presigned upload URL and an objectKey for your file. The presigned URL lets you upload the file to storage without direct access credentials, and the objectKey uniquely identifies the file in storage. Specify the MIME type of the file in the contentType query parameter.

curl -X GET \
  "https://knowledge-enrichment.ai.app.hyland.com/latest/api/context-enrichment/files/upload/presigned-url?contentType=application/pdf" \
  -H "Authorization: Bearer <your-token>"

Response (HTTP 200 OK):

{
  "presignedUrl": "https://<storage-endpoint>/contents/abc123.pdf?<signature>",
  "objectKey": "testing/fae61283-571c-403a-b33f-c8d982158da9/documents/report.pdf"
}
FieldTypeRequiredDescription
presignedUrlstringYesThe temporary upload URL, valid for 15 minutes. Use it to upload the file in Step 2.
objectKeystringYesThe unique identifier for the file in storage. Use it in the POST /content/process request in Step 3.

Save both values.

Step 2: Upload the file​

Upload the file to storage. Send the file as binary data in the request body of a PUT request. Set the Content-Type header to match the MIME type you specified in the contentType parameter in Step 1. Do not include the Authorization header for this request.

curl -X PUT \
  "<presignedUrl>" \
  -H "Content-Type: application/pdf" \
  --data-binary @report.pdf

A successful upload returns HTTP 200 with an empty body.

tip

Use an HTTP tool such as Bruno to step through the API calls interactively while you explore the available actions and response formats.

Step 3: Submit a processing job​

Send a POST /content/process request with the objectKey from Step 1 to identify the file, and the actions you want to apply. The endpoint returns HTTP 200 OK immediately with a processingId for polling.

curl -X POST \
  "https://knowledge-enrichment.ai.app.hyland.com/latest/api/context-enrichment/content/process" \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "context.api/v2",
    "objectKeys": [
      { "path": "testing/fae61283-571c-403a-b33f-c8d982158da9/documents/report.pdf" }
    ],
    "actions": {
      "textSummarization": { "maxWordCount": 150 },
      "textClassification": {
        "classes": ["Report", "Contract", "Invoice", "Other"]
      }
    }
  }'

Request body:

FieldTypeRequiredDescription
versionstringYesAPI version identifier. Supports context.api/v2.
objectKeysarrayYesArray of objects containing the path property with the objectKey value from Step 1. You can include multiple object keys to process multiple files.
actionsobjectYesThe enrichment actions to apply. For available actions, see Context API Reference.

Each text and image action also accepts an optional model field that chooses the AI model running it. When omitted, the action runs on its default model (see Model Selection for more information).

Response (HTTP 200 OK):

{
  "processingId": "a3f9c821-4e3b-47e9-9b0c-1e7e29f87a12"
}
FieldTypeRequiredDescription
processingIdstringYesThe unique identifier for the processing job. Use it to poll for results.

Save the processingId for the next step.

Step 4: Poll for results​

The Context API processes jobs asynchronously. Poll GET /content/process/{processingId}/results until inProgress is false. Poll every 2–5 seconds.

curl -X GET \
  "https://knowledge-enrichment.ai.app.hyland.com/latest/api/context-enrichment/content/process/a3f9c821-4e3b-47e9-9b0c-1e7e29f87a12/results" \
  -H "Authorization: Bearer <your-token>"

While the job is in progress, the endpoint returns HTTP 202 Accepted:

{
  "id": "a3f9c821-4e3b-47e9-9b0c-1e7e29f87a12",
  "timestamp": "2025-08-25T13:06:00.8286903+00:00",
  "status": "PROCESSING",
  "inProgress": true
}

When the job is complete, the endpoint returns HTTP 200 OK:

{
  "id": "a3f9c821-4e3b-47e9-9b0c-1e7e29f87a12",
  "timestamp": "2025-08-25T13:06:00.8286903+00:00",
  "status": "SUCCESS",
  "inProgress": false,
  "results": [
    {
      "objectKey": "testing/fae61283-571c-403a-b33f-c8d982158da9/documents/report.pdf",
      "textSummary": {
        "isSuccess": true,
        "result": "This is a concise summary of the document content."
      },
      "textClassification": {
        "isSuccess": true,
        "result": "Report"
      }
    }
  ]
}

Job status values:

StatusMeaning
PROCESSINGJob is running.
SUCCESSAll actions completed successfully.
PARTIAL_FAILUREThe job completed, but one or more actions failed. Review the error fields in the individual results.
FAILUREThe job failed entirely. No results are available.

For examples of processing errors, see Processing errors.

note

SUCCESS, PARTIAL_FAILURE, and FAILURE are all terminal states. Stop polling when inProgress is false.

Content Lake input​

You can enrich a document that the Data Curation API already ingested into the Content Lake. Reference the document by documentId instead of uploading it, which means you can skip Step 1 and Step 2.

curl -X POST \
  "https://knowledge-enrichment.ai.app.hyland.com/latest/api/context-enrichment/content/process" \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "context.api/v2",
    "objectKeys": [
      { "documentId": "09694a47-f2fa-48d1-b345-b5a94e47f04f" }
    ],
    "actions": {
      "textSummarization": {}
    }
  }'
caution

Do not mix path and documentId entries in the same request.

Applying multiple actions​

You can request multiple actions in one call. The API processes each action independently, so a failure in one action does not prevent the others from completing.

For the parameters and response schema of each action, see Actions reference.

The following request applies four actions to one file:

{
  "version": "context.api/v2",
  "objectKeys": [{ "path": "documents/report.pdf" }],
  "actions": {
    "textSummarization": { "maxWordCount": 100 },
    "textClassification": { "classes": ["Report", "Contract", "Invoice"] },
    "namedEntityRecognitionText": {},
    "textEmbeddings": {}
  }
}

Next steps​