Reference Documentation

Access token - configuration

External Application Client creation and configuration

For detailed instruction go to official documentation

External Application Client Creation and Configuration To authenticate with context-api, an External Application must be created in Hyland Experience Admin Portal:

🔗 Portal: https://admin.experience.hyland.com/

Steps:

1. Create a Service User via the Identity tab.

• Go to Identity → Service Users
• Click Create Service User
• Fill in required details

2. Register a new External Application:

• Go to External Systems -> click Create External Application
• Select Service Application
• Fill Application name
• Choose created previously Service User
• Select allowed scopes listed in the table below

🔑 Scopes for External Applications

This section describes some required scopes for external applications (more in documentation).

Scope	Description
environment_authorization	Allows authorization checks to be performed at login before APIs are called in the context of an environment. Adds permissions and roles granted to the user in the configured environment and application to the token as claims. An associated environment and application in the subscription must be configured.

---

❗Save and copy the Client ID and Client Secret ❗

📌 Client Secret will be visible only once. Store it securely.

Access token request

To obtain access token for context-api, consumer must send POST request to the following endpoint:

curl -X POST https://auth.iam.experience.hyland.com/idp/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=<client_id>" \
  -d "client_secret=<client_secret>" \
  -d "grant_type=client_credentials" \
  -d "scope=environment_authorization"

Context API - REST API definition and code samples

API Definition can be found here

⚙️ Requirements for actions on processing request

Depending on the selected subset of actions passed in the /process request, additional fields may be required. The table below summarizes all required properties for each supported action:

Action	Input File Type	Additional Requirements	Result Schema
image-description	image	All objectKeys must point to image files	string
image-metadata-generation	image	All objectKeys must be image files kSimilarMetadata must be provided and contain non-empty items	Dictionary<string, object>
text-classification	text	All objectKeys must be text files classes must contain at least 2 distinct non-empty entries	string
text-summarization	text	All objectKeys must be text files	string
image-classification	image	All objectKeys must be image files classes must contain at least 2 distinct non-empty entries	string
image-embeddings	image	All objectKeys must be image files	List<float>
text-embeddings	text	All objectKeys must be text files	List<List<float>>
named-entity-recognition-image	image	All objectKeys must be image files	Dictionary<string, List<string>>
named-entity-recognition-text	text	All objectKeys must be text files	Dictionary<string, List<string>>

---

📤 Notes

• If no classification actions (image-classification, text-classification) are specified, classes must be null or empty.
• If image-metadata-generation is not specified, then kSimilarMetadata must be null or empty.
• All objectKeys must be distinct and use valid formats (e.g. .png, .jpg, .txt).
• If an action is specified with an invalid file format, the request will be rejected with validation errors.

🧾 Results for actions

Different actions may return different types of result objects depending on the performed analysis.
The table below summarizes the output schemas returned by each action:

Action	Result Schema	Description
image-description	string	A short description of the image content
image-metadata-generation	Dictionary<string, object>	Key-value representation of predicted metadata for an image
text-classification	string	Predicted class label based on the text content
text-summarization	string	Generated summary of the text
image-classification	string	Predicted class label based on the image content
image-embeddings	List<float>	Vector representation of the image
text-embeddings	List<List<float>>	Vector representation of the text, typically per sentence
named-entity-recognition-image	Dictionary<string, List<string>>	Detected named entities extracted from image content
named-entity-recognition-text	Dictionary<string, List<string>>	Detected named entities extracted from text content

---

📤 Notes

• All result fields follow the common ProcessingResult<T> structure:

  {
    "isSuccess": true,
    "result": "<T>",
    "error": null
  }

❗ Error Handling

In case error occured for any document processing or action appropriate errors objects are stored in place of action result. Each action tpe error have follows same schema.

Format of a Failed Action

If any action fails, a ProcessingResult<T> will contain IsSuccess: false and Error object instead of the expected result.

{
  "isSuccess": false,
  "result": null,
  "error": {
    "errorType": "UnexpectedError",
    "message": "The given key 'statusCode' was not present in the dictionary."
  }
}

Example get result

{
  "id": "156e4a8a-e9c8-41c0-95f0-7039982236f3",
  "timestamp": "2025-03-24T15:45:14.104323+01:00",
  "results": [
    {
      "objectKey": "testing/documents/fedex.pdf",
      "imageDescription": null,
      "metadata": null,
      "textSummary": {
        "isSuccess": false,
        "result": null,
        "error": {
          "errorType": "UnexpectedError",
          "message": "The given key 'statusCode' was not present in the dictionary."
        }
      },
      "textClassification": {
        "isSuccess": true,
        "result": "invoice",
        "error": null
      },
      "imageClassification": null,
      "textEmbeddings": null,
      "imageEmbeddings": null,
      "generalProcessingErrors": null,
      "namedEntityText": null,
      "namedEntityImage": null
    }
  ],
  "status": "PARTIAL_FAILURE"
}