Core Concepts

Assessment Process

Copy page

The Assessment endpoint is the core functionality of the Compliance Service API. It allows you to evaluate specific input data (documents or URLs) against selected compliance criteria within a framework using a Large Language Model (LLM)-based assessment engine.

The assessment process is asynchronous, allowing you to start an assessment, poll for its status, and retrieve results when completed. This approach is ideal for processing large documents or multiple criteria.

Use these endpoints to:

• Start an automated compliance assessment on uploaded documents or URLs
• Monitor the progress of ongoing assessments
• Retrieve structured assessment results with justifications and source citations
• Cancel ongoing assessments if needed

Start Assessment

Code
 
POST /api/v1/assessments

Content-Type: multipart/form-data

Request Parameters

Parameter	Type	Required	Description
configuration	JSON object	Yes	Configuration specifying the assessment details
documents	File array	No*	Multipart files to be assessed
urls	String array	No*	URLs to be assessed

Assessment Configuration Structure

Code
 
{
  "expertId": "string (required)",
  "frameworkCodeName": "string (required)",
  "criteriaCodeNames": ["string"] (optional),
  "assessmentProcessId": "string (optional)"
}

Field	Type	Required	Description
expertId	string	Yes	The ID of the expert who carries out the assessment
frameworkCodeName	string	Yes	The code name of the framework to which the criteria belong
criteriaCodeNames	string array	No	List of criterion code names to assess. If not provided, all criteria in the framework will be assessed
assessmentProcessId	string	No	The ID of the assessment process, used to group assessment responses together. If not provided, a new UUID will be generated

Example Request

This example shows a curl request with both documents and urls. You can send either one; make sure not to omit both.

Code
 
curl -X POST "https://compliance-assessment.precognox.com/api/v1/assessments" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F 'configuration={"expertId":"expert_123","frameworkCodeName":"ISO_27001","criteriaCodeNames":["AC_01","AC_02"]};type=application/json' \
  -F "documents=@document1.pdf" \
  -F 'urls=["https://example.com/privacy-policy"];type=application/json'

Response

The endpoint returns 202 Accepted with a Location header pointing to the status polling endpoint.

Code
 
{
  "assessmentProcessId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "PENDING",
  "completion": 0.0,
  "responses": []
}

Response Fields

Field	Type	Description
assessmentProcessId	string	Unique identifier for the assessment process
status	string	Current status: PENDING, RUNNING, COMPLETED, FAILED, or CANCELLED
completion	float	Progress percentage (0.0 to 1.0)
responses	array	Empty on initial request; populated when checking status

Check Assessment Status

Code
 
GET /api/v1/assessments/{assessmentProcessId}/status

Request Parameters

Parameter	Type	Required	Description
assessmentProcessId	string (path)	Yes	The assessment process ID returned from the start endpoint

Example Request

Code
 
curl X GET "https://compliance-assessment.precognox.com/api/v1/assessments/550e8400-e29b-41d4-a716-446655440000/status" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \

Response

Status: 200 OK (while processing) or 303 See Other (when completed)

Code
 
{
  "assessmentProcessId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "RUNNING",
  "completion": 0.5,
  "responses": []
}

When the status is COMPLETED, the response will be 303 See Other with a Location header pointing to the results endpoint.

Get Assessment Results

Code
 
GET /api/v1/assessments/{assessmentProcessId}/result

Request Parameters

Parameter	Type	Required	Description
assessmentProcessId	string (path)	Yes	The assessment process ID

Example Request

Code
 
curl X GET "https://compliance-assessment.precognox.com/api/v1/assessments/550e8400-e29b-41d4-a716-446655440000/result" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \

Example Response

Returns a list of assessment results (one per criterion assessed):

Code
 
[
  {
    "id": 123,
    "assessmentProcessId": "550e8400-e29b-41d4-a716-446655440000",
    "inputTokens": 1475,
    "outputTokens": 362,
    "processingTimeMs": 1340,
    "expertId": "expert_123",
    "fileNames": ["document1.pdf"],
    "urls": ["https://example.com/privacy-policy"],
    "frameworkCodeName": "ISO_27001",
    "criterionCodeName": "AC_01",
    "category": "SUFFICIENTLY_REGULATED",
    "rationale": "The privacy policy outlines data subject rights clearly, but lacks contact details for data access requests.",
    "citations": [
      {
        "fileName": "document1.pdf",
        "content": "Users have the right to access their personal data at any time",
        "heading": "Section 4.2",
        "startIndex": 0,
        "endIndex": 62
      },
      {
        "fileName": "privacy-policy.html",
        "content": "We process personal data in accordance with GDPR requirements",
        "heading": "Introduction paragraph",
        "startIndex": 0,
        "endIndex": 61
      }
    ]
  }
]

Response Fields

Each assessment result in the array contains:

Field	Type	Description
id	integer	Unique identifier of the assessment result
assessmentProcessId	string	Unique identifier for the assessment process
inputTokens	integer	Number of tokens used for LLM input
outputTokens	integer	Number of tokens used for LLM output
processingTimeMs	long	Total time taken to complete this criterion's assessment, in milliseconds
expertId	string	Identifier of the expert who initiated the assessment
fileNames	string array	List of input file names used during the assessment
urls	string array	List of URLs used during the assessment
frameworkCodeName	string	Identifier of the framework used for assessment
criterionCodeName	string	Identifier of the specific criterion assessed
category	string	Assessment outcome (see Assessment Categories below)
rationale	string	Human-readable explanation provided by the AI
citations	array	Source citations from the analyzed materials

Assessment Categories

The assessment can result in one of the following categories:

• SUFFICIENTLY_REGULATED - The assessed material adequately meets the compliance criterion
• NOT_SUFFICIENTLY_REGULATED - The assessed material does not adequately meet the compliance criterion
• MISSING - The required information for the criterion is not present in the assessed material

Citation Structure

Citations provide traceability to source materials:

Field	Type	Description
fileName	string	Name of the source material (file name or URL)
content	string	Relevant excerpt from the source material
heading	string	The heading or section of the reference within the source material
startIndex	integer	The starting character index of the quoted text in the source
endIndex	integer	The ending character index of the quoted text in the source

Cancel Assessment

Code
 
DELETE /api/v1/assessments/{assessmentProcessId}

Cancels an ongoing assessment process.

Request Parameters

Parameter	Type	Required	Description
assessmentProcessId	string (path)	Yes	The assessment process ID to cancel

Example Request

Code
 
curl X DELETE "https://compliance-assessment.precognox.com/api/v1/assessments/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \

Response

Status: 200 OK

Code
 
{
  "assessmentProcessId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "CANCELLED",
  "completion": 0.3,
  "responses": []
}

Submit Assessment Feedback

After the assessment result is displayed, users can provide feedback on the AI's decision. This step is a critical component of the human-in-the-loop process, ensuring that automated decisions remain transparent, accountable, and continuously improving.

Submit Feedback

Code
 
POST /api/v1/assessmentFeedback

Content-Type: application/json

Request Body

Code
 
{
  "assessmentResponseId": 123,
  "expertId": "expert_789", 
  "rationalFeedback": "MFA is only mentioned, not enforced. Therefore, the assessment should be downgraded.",
  "categoryFeedback": "NOT_SUFFICIENTLY_REGULATED"
}

Request Fields

Field	Type	Required	Description
assessmentResponseId	integer	Yes	ID of the assessment response being reviewed
expertId	string	Yes	Identifier of the expert submitting the feedback
rationalFeedback	string	Yes	Detailed rationale justifying agreement or disagreement with the AI assessment
categoryFeedback	string	Yes	Suggested correct assessment category (if different from AI assessment)

Example Request

Code
 
curl X POST "https://compliance-assessment.precognox.com/api/v1/assessmentFeedback" \
  --header 'Content-Type: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ \
  --data '{
    "assessmentResponseId": 123,
    "expertId": "expert_789",
    "rationalFeedback": "MFA is only mentioned, not enforced. Therefore, the assessment should be downgraded.",
    "categoryFeedback": "NOT_SUFFICIENTLY_REGULATED"
  }'

Response

The endpoint returns HTTP 200 OK on successful feedback submission.

Why This Matters

This feedback mechanism is designed to integrate human expertise into the compliance evaluation loop. It enhances:

• Trust by giving users control and visibility over AI decisions
• Adaptability through domain-specific refinement and learning
• Auditability by capturing the rationale behind expert decisions
• Quality through continuous improvement of the assessment model

By combining AI-driven automation with structured human input, the Compliance Assessment Service supports a scalable and explainable approach to regulatory evaluations.

Legacy Endpoint (Deprecated)

Code
 
POST /api/v1/assessment

This legacy endpoint performs synchronous assessment (blocking until completion) and accepts only a single criterion:

• Uses assessmentConfiguration parameter instead of configuration
• Uses criterionCodeName (string) instead of criteriaCodeNames (array)
• Returns results immediately in a single response (not asynchronous)
• Does not support progress monitoring or cancellation

Migration Path:

• Replace POST /api/v1/assessment with POST /api/v1/assessments
• Change parameter name from assessmentConfiguration to configuration
• Replace criterionCodeName with criteriaCodeNames: ["AC_01"]
• Implement polling logic for status checking
• Handle the response as an array of results

Error Handling

The API returns standard HTTP status codes:

• 200 OK - Successful status check, result retrieval, cancellation, or feedback submission
• 202 Accepted - Assessment process started successfully
• 303 See Other - Assessment completed, follow Location header for results
• 400 Bad Request - Invalid request parameters or missing required fields
• 401 Unauthorized - Invalid or missing authentication
• 404 Not Found - Assessment process not found
• 409 Conflict - Assessment processing error or system conflict

Error responses include descriptive messages to help troubleshoot issues.