Core Concepts

Content Processing

The Content Processing endpoints allow you to preprocess input materials — documents or URLs — before running an assessment. This is useful for extracting and reviewing text content ahead of time, validating that documents are readable, and preparing materials for assessment.

Content processing is asynchronous: you submit a file or URL, receive a job UUID, then poll for status until processing is complete. Once complete, you can retrieve the extracted text content.

Use these endpoints to:

• Extract text from uploaded documents (PDF, DOCX, etc.)
• Extract text content from web pages via URL
• Check processing status for individual or multiple jobs
• Retrieve the extracted text for review or display
• Re-process content that may have changed (e.g., updated web pages)
• Delete processed content when no longer needed

Submit File for Processing

Code
POST /api/v1/content-processing/file

Content-Type: multipart/form-data

Request Parameters

Parameter	Type	Required	Description
file	File	Yes	The document file to process

Supported file types are validated server-side. Common supported formats include PDF, DOCX, DOC, TXT, and other document types.

Example Request

Code
curl --request POST \
  --url /api/v1/content-processing/file \
  --header 'Content-Type: multipart/form-data' \
  --header 'KEYCLOAK_SUBJECT: your-partner-uuid' \
  --form 'file=@document.pdf'

Response

Status: 202 Accepted with a Location header pointing to the status endpoint.

Code
{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "sourceType": "FILE",
  "sourceUrl": null,
  "fileName": "document.pdf",
  "status": "PENDING",
  "error": null,
  "createdAt": "2026-04-24T10:00:00",
  "completedAt": null,
  "fetchedAt": null
}

Submit URL for Processing

Code
POST /api/v1/content-processing/url

Content-Type: application/json

Request Body

Code
{
  "url": "https://example.com/privacy-policy"
}

Field	Type	Required	Description
url	string	Yes	The URL of the web page to process

Example Request

Code
curl --request POST \
  --url /api/v1/content-processing/url \
  --header 'Content-Type: application/json' \
  --header 'KEYCLOAK_SUBJECT: your-partner-uuid' \
  --data '{"url": "https://example.com/privacy-policy"}'

Response

Status: 202 Accepted with a Location header pointing to the status endpoint.

Code
{
  "uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "sourceType": "URL",
  "sourceUrl": "https://example.com/privacy-policy",
  "fileName": "https_example.com_privacy-policy.html",
  "status": "PENDING",
  "error": null,
  "createdAt": "2026-04-24T10:00:00",
  "completedAt": null,
  "fetchedAt": null
}

Check Processing Status

Code
GET /api/v1/content-processing/{uuid}/status

Request Parameters

Parameter	Type	Required	Description
uuid	string (path)	Yes	The UUID of the content processing job

Example Request

Code
curl --request GET \
  --url /api/v1/content-processing/a1b2c3d4-e5f6-7890-abcd-ef1234567890/status \
  --header 'KEYCLOAK_SUBJECT: your-partner-uuid'

Response

Status: 200 OK (while processing) or 303 See Other (when completed, with Location header pointing to the content endpoint).

Code
{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "sourceType": "FILE",
  "sourceUrl": null,
  "fileName": "document.pdf",
  "status": "RUNNING",
  "error": null,
  "createdAt": "2026-04-24T10:00:00",
  "completedAt": null,
  "fetchedAt": null
}

Batch Status Check

Check the status of multiple content processing jobs in a single request.

Code
POST /api/v1/content-processing/status/batch

Content-Type: application/json

Request Body

Code
{
  "uuids": [
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "b2c3d4e5-f6a7-8901-bcde-f12345678901"
  ]
}

Field	Type	Required	Description
uuids	string array	Yes	List of content processing job UUIDs to check

Example Request

Code
curl --request POST \
  --url /api/v1/content-processing/status/batch \
  --header 'Content-Type: application/json' \
  --header 'KEYCLOAK_SUBJECT: your-partner-uuid' \
  --data '{"uuids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890", "b2c3d4e5-f6a7-8901-bcde-f12345678901"]}'

Response

Status: 200 OK

Returns an array of status objects, one per requested UUID:

Code
[
  {
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "sourceType": "FILE",
    "sourceUrl": null,
    "fileName": "document.pdf",
    "status": "COMPLETED",
    "error": null,
    "createdAt": "2026-04-24T10:00:00",
    "completedAt": "2026-04-24T10:00:15",
    "fetchedAt": null
  },
  {
    "uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "sourceType": "URL",
    "sourceUrl": "https://example.com/privacy-policy",
    "fileName": "https_example.com_privacy-policy.html",
    "status": "RUNNING",
    "error": null,
    "createdAt": "2026-04-24T10:00:00",
    "completedAt": null,
    "fetchedAt": null
  }
]

Get Processed Content

Retrieve the extracted text content from a completed processing job.

Code
GET /api/v1/content-processing/{uuid}/content

Produces: text/plain

Request Parameters

Parameter	Type	Required	Description
uuid	string (path)	Yes	The UUID of the completed content processing job

Example Request

Code
curl --request GET \
  --url /api/v1/content-processing/a1b2c3d4-e5f6-7890-abcd-ef1234567890/content \
  --header 'KEYCLOAK_SUBJECT: your-partner-uuid'

Response

Status: 200 OK

Returns the extracted text content as plain text (text/plain).

Code
This is the extracted text content from the processed document.
It contains all readable text from the original file or web page,
preserving the logical reading order.

Refresh Content

Re-process a previously submitted content processing job. This is useful when the source material has changed (e.g., an updated web page) and you need to extract the latest content.

Code
POST /api/v1/content-processing/{uuid}/refresh

Request Parameters

Parameter	Type	Required	Description
uuid	string (path)	Yes	The UUID of the content processing job to refresh

Example Request

Code
curl --request POST \
  --url /api/v1/content-processing/b2c3d4e5-f6a7-8901-bcde-f12345678901/refresh \
  --header 'KEYCLOAK_SUBJECT: your-partner-uuid'

Response

Status: 202 Accepted with a Location header pointing to the status endpoint.

Code
{
  "uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "sourceType": "URL",
  "sourceUrl": "https://example.com/privacy-policy",
  "fileName": "https_example.com_privacy-policy.html",
  "status": "PENDING",
  "error": null,
  "createdAt": "2026-04-24T10:00:00",
  "completedAt": null,
  "fetchedAt": null
}

Delete Content Processing Job

Delete a content processing job and its associated data. This can also be used to cancel an in-progress job.

Code
DELETE /api/v1/content-processing/{uuid}

Request Parameters

Parameter	Type	Required	Description
uuid	string (path)	Yes	The UUID of the content processing job to delete

Example Request

Code
curl --request DELETE \
  --url /api/v1/content-processing/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  --header 'KEYCLOAK_SUBJECT: your-partner-uuid'

Response

Status: 200 OK with an empty response body.

Response Fields

All content processing endpoints return or use the following response structure:

Field	Type	Description
uuid	string	Unique identifier for the content processing job
sourceType	string	Type of source: FILE or URL
sourceUrl	string	The original URL (only for URL-type jobs, null for files)
fileName	string	Name of the processed file (original filename for uploads, generated name for URLs)
status	string	Current processing status: PENDING, RUNNING, COMPLETED, FAILED, or CANCELLED
error	string	Error message if processing failed, null otherwise
createdAt	string (datetime)	Timestamp when the job was created
completedAt	string (datetime)	Timestamp when processing completed, null if not yet complete
fetchedAt	string (datetime)	For URL sources, timestamp when the content was last fetched from the URL

Integration Workflow

A typical integration flow using content processing with assessments:

1. Submit materials — Upload documents via /content-processing/file or submit URLs via /content-processing/url
2. Monitor status — Poll individual jobs via /content-processing/{uuid}/status or use batch status via /content-processing/status/batch
3. Review content — Once completed, retrieve extracted text via /content-processing/{uuid}/content to display to users for review
4. Run assessment — Submit the original documents or URLs to the /assessments endpoint for compliance evaluation
5. Manage lifecycle — Refresh outdated content or delete jobs that are no longer needed