Upload documents, trigger parsing, and manage other assessment operations.
Request upload URL
curl -X POST https://api.example.com/api/assessments/550e8400-e29b-41d4-a716-446655440000/documents \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"fileName": "financial-statements.pdf",
"mimeType": "application/pdf",
"fileSize": 2457600
}'
Endpoint
POST /api/assessments/:id/documents
Path parameters
Request body
Name of the file to upload.Maximum length: 255 characters.
MIME type of the file.Currently only application/pdf is supported. Maximum length: 50 characters.
File size in bytes.Maximum: 26,214,400 bytes (25 MB).
Response
Pre-signed S3 URL for uploading the file. Valid for 15 minutes.
Unique document identifier (UUID). Use this to trigger parsing after upload.
Upload workflow
Request upload URL
POST to /api/assessments/:id/documents with file metadata.
Upload file to S3
PUT the file to the presignedUrl using the exact mimeType from your request.curl -X PUT "$PRESIGNED_URL" \
-H "Content-Type: application/pdf" \
--data-binary @financial-statements.pdf
Trigger parsing
POST to /api/assessments/:id/documents/:documentId/parse to start AI document analysis.
The presigned URL expires after 15 minutes. If upload fails, request a new URL.
Trigger document parsing
curl -X POST https://api.example.com/api/assessments/550e8400-e29b-41d4-a716-446655440000/documents/abc123/parse \
-H "Authorization: Bearer YOUR_TOKEN"
Endpoint
POST /api/assessments/:id/documents/:documentId/parse
Starts an asynchronous job to parse the uploaded document using AWS Bedrock AI models.
Path parameters
Document ID returned from the upload URL request.
Response
Returns a job ID (string) to poll for completion status.
Job polling
Use GET /api/jobs/:id to check the parsing status:
PENDING - Job is queuedPROCESSING - AI is analyzing the documentCOMPLETED - Parsing finished successfullyFAILED - Parsing failed (check error field)
Poll every 2-5 seconds until the job reaches a terminal state.
When parsing starts, the assessment status automatically changes to ANALYZING.
curl -X POST https://api.example.com/api/assessments/550e8400-e29b-41d4-a716-446655440000/comments \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"content": "Reviewed financial statements - revenue projections look strong."
}'
Endpoint
POST /api/assessments/:id/comments
Path parameters
Request body
Comment text.Maximum length: 2000 characters.
Response
Assessment ID this comment belongs to.
ID of the user who created the comment.
ISO 8601 timestamp of creation.
curl -X GET https://api.example.com/api/assessments/550e8400-e29b-41d4-a716-446655440000/comments \
-H "Authorization: Bearer YOUR_TOKEN"
Endpoint
GET /api/assessments/:id/comments
Retrieve all comments for an assessment, ordered chronologically.
Path parameters
Response
Returns an array of comment objects with user information.
ISO 8601 creation timestamp.
User information.
Author’s email address.
Example response
[
{
"id": "comment-uuid-1",
"assessmentId": "550e8400-e29b-41d4-a716-446655440000",
"userId": "auth0|123456789",
"content": "Reviewed financial statements - revenue projections look strong.",
"createdAt": "2026-03-04T12:00:00.000Z",
"user": {
"email": "[email protected]"
}
},
{
"id": "comment-uuid-2",
"assessmentId": "550e8400-e29b-41d4-a716-446655440000",
"userId": "auth0|987654321",
"content": "Flagged climate risks for further investigation.",
"createdAt": "2026-03-04T14:30:00.000Z",
"user": {
"email": "[email protected]"
}
}
]
