Document operations

Auto-generate your docs

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
  }'

const assessmentId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(
  `https://api.example.com/api/assessments/${assessmentId}/documents`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      fileName: 'financial-statements.pdf',
      mimeType: 'application/pdf',
      fileSize: 2457600
    })
  }
);

const { presignedUrl, documentId } = await response.json();

Endpoint

POST /api/assessments/:id/documents

Path parameters

string

required

Assessment ID (UUID).

Request body

string

required

Name of the file to upload.Maximum length: 255 characters.

string

required

MIME type of the file.Currently only application/pdf is supported. Maximum length: 50 characters.

number

required

File size in bytes.Maximum: 26,214,400 bytes (25 MB).

Response

string

Pre-signed S3 URL for uploading the file. Valid for 15 minutes.

string

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"

const assessmentId = '550e8400-e29b-41d4-a716-446655440000';
const documentId = 'abc123';

const response = await fetch(
  `https://api.example.com/api/assessments/${assessmentId}/documents/${documentId}/parse`,
  {
    method: 'POST',
    headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
  }
);

const jobId = await response.json();

// Poll job status
const pollJob = async (jobId) => {
  const jobResponse = await fetch(
    `https://api.example.com/api/jobs/${jobId}`,
    { headers: { 'Authorization': 'Bearer YOUR_TOKEN' } }
  );
  const job = await jobResponse.json();
  
  if (job.status === 'COMPLETED') {
    console.log('Parsing complete:', job.result);
  } else if (job.status === 'FAILED') {
    console.error('Parsing failed:', job.error);
  } else {
    // Still processing, poll again
    setTimeout(() => pollJob(jobId), 2000);
  }
};

pollJob(jobId);

Endpoint

POST /api/assessments/:id/documents/:documentId/parse Starts an asynchronous job to parse the uploaded document using AWS Bedrock AI models.

Path parameters

string

required

Assessment ID (UUID).

string

required

Document ID returned from the upload URL request.

Response

Returns a job ID (string) to poll for completion status.

"job-uuid-here"

Job polling

Use GET /api/jobs/:id to check the parsing status:

PENDING - Job is queued
PROCESSING - AI is analyzing the document
COMPLETED - Parsing finished successfully
FAILED - 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.

Add comment

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."
  }'

const assessmentId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(
  `https://api.example.com/api/assessments/${assessmentId}/comments`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      content: 'Reviewed financial statements - revenue projections look strong.'
    })
  }
);

const comment = await response.json();

Endpoint

POST /api/assessments/:id/comments

Path parameters

string

required

Assessment ID (UUID).

Request body

string

required

Comment text.Maximum length: 2000 characters.

Response

string

Comment ID (UUID).

string

Assessment ID this comment belongs to.

string

ID of the user who created the comment.

string

Comment text.

string

ISO 8601 timestamp of creation.

Get comments

curl -X GET https://api.example.com/api/assessments/550e8400-e29b-41d4-a716-446655440000/comments \
  -H "Authorization: Bearer YOUR_TOKEN"

const assessmentId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(
  `https://api.example.com/api/assessments/${assessmentId}/comments`,
  {
    headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
  }
);

const comments = await response.json();

Endpoint

GET /api/assessments/:id/comments Retrieve all comments for an assessment, ordered chronologically.

Path parameters

string

required

Assessment ID (UUID).

Response

Returns an array of comment objects with user information.

array

Show Comment properties

string

Comment ID (UUID).

string

Assessment ID.

string

Comment author ID.

string

Comment text.

string

ISO 8601 creation timestamp.

object

User information.

Show User properties

string

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": "analyst@example.com"
    }
  },
  {
    "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": "reviewer@example.com"
    }
  }
]

Authentication

Assessments

Jobs

Prompts

Admin

Request upload URL

Endpoint

Path parameters

Request body

Response

Upload workflow

Trigger document parsing

Endpoint

Path parameters

Response

Job polling

Add comment

Endpoint

Path parameters

Request body

Response

Get comments

Endpoint

Path parameters

Response

Example response

​Request upload URL

​Endpoint

​Path parameters

​Request body

​Response

​Upload workflow

​Trigger document parsing

​Endpoint

​Path parameters

​Response

​Job polling

​Add comment

​Endpoint

​Path parameters

​Request body

​Response

​Get comments

​Endpoint

​Path parameters

​Response

​Example response

Request upload URL

Endpoint

Path parameters

Request body

Response

Upload workflow

Trigger document parsing

Endpoint

Path parameters

Response

Job polling

Add comment

Endpoint

Path parameters

Request body

Response

Get comments

Endpoint

Path parameters

Response

Example response