ForensAssess API v1

All endpoints are JSON over HTTPS. Base URL: https://api.forensassess.com. Generate a key at /account/api-keys.

Authentication

Send your API key in the Authorization header as a Bearer token:

Authorization: Bearer vx_...

Errors & rate limits

Errors return a JSON body { "error": "...", "detail": {...}? }. Rate limit headers: X-RateLimit-Remaining on every response, Retry-After on 429.

Status	Meaning
400	Validation error. `detail` shows which fields.
401	Missing or invalid API key.
403	Key lacks the required scope.
412	BAA required before uploading PHI.
429	Rate limited; retry after the indicated seconds.
5xx	Server error. Retry with exponential backoff.

POST/api/v1/uploads

Create an upload URL

Returns a 15-minute presigned S3 PUT URL plus the storage key you will pass to the service endpoint.

Request body

{
  "type": "object",
  "properties": {
    "filename": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    },
    "contentType": {
      "type": "string"
    },
    "service": {
      "type": "string",
      "enum": [
        "records",
        "cite",
        "counter",
        "depo"
      ]
    }
  },
  "required": [
    "filename",
    "contentType",
    "service"
  ],
  "additionalProperties": false
}

Response

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "format": "uri"
    },
    "key": {
      "type": "string"
    }
  },
  "required": [
    "url",
    "key"
  ],
  "additionalProperties": false
}

Examples

curl -X POST https://api.forensassess.com/api/v1/uploads \
  -H "Authorization: Bearer $FORENSASSESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename":"smith_records.pdf","contentType":"application/pdf","service":"records"}'

Node.js

const r = await fetch('https://api.forensassess.com/api/v1/uploads', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.FORENSASSESS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "filename": "smith_records.pdf",
    "contentType": "application/pdf",
    "service": "records"
  }),
});
const data = await r.json();

Python

import os, requests
r = requests.post(
    'https://api.forensassess.com/api/v1/uploads',
    headers={'Authorization': f"Bearer {os.environ['FORENSASSESS_API_KEY']}"},
    json={"filename":"smith_records.pdf","contentType":"application/pdf","service":"records"}
)
print(r.json())

Sample response

{
  "url": "https://s3.amazonaws.com/...",
  "key": "user_X/records/1716998400000-smith_records.pdf"
}

POST/api/v1/recordsscope: records

Run RecordsLens

Generate a chronological medical-records narrative from a previously uploaded PDF.

Request body

{
  "type": "object",
  "properties": {
    "inputKey": {
      "type": "string"
    },
    "units": {
      "type": "integer",
      "exclusiveMinimum": true,
      "minimum": 0
    },
    "inputBytes": {
      "type": "integer",
      "minimum": 0
    }
  },
  "required": [
    "inputKey",
    "units"
  ],
  "additionalProperties": false
}

Response

{
  "type": "object",
  "properties": {
    "jobId": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "paid",
        "running",
        "succeeded",
        "failed"
      ]
    },
    "amountCents": {
      "type": "number"
    },
    "units": {
      "type": "number"
    }
  },
  "required": [
    "jobId",
    "status",
    "amountCents"
  ],
  "additionalProperties": false
}

Examples

curl -X POST https://api.forensassess.com/api/v1/records \
  -H "Authorization: Bearer $FORENSASSESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inputKey":"user_X/records/...pdf","units":1247}'

Node.js

const r = await fetch('https://api.forensassess.com/api/v1/records', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.FORENSASSESS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "inputKey": "user_X/records/...pdf",
    "units": 1247
  }),
});
const data = await r.json();

Python

import os, requests
r = requests.post(
    'https://api.forensassess.com/api/v1/records',
    headers={'Authorization': f"Bearer {os.environ['FORENSASSESS_API_KEY']}"},
    json={"inputKey":"user_X/records/...pdf","units":1247}
)
print(r.json())

Sample response

{
  "jobId": "cuid_a8f",
  "status": "paid",
  "amountCents": 9976,
  "units": 1247
}

POST/api/v1/citescope: cite

Run CiteCheck

Audit every citation in a document against PubMed, Crossref, and CDC NVSS.

Request body

{
  "type": "object",
  "properties": {
    "inputKey": {
      "type": "string"
    },
    "inputBytes": {
      "type": "integer",
      "minimum": 0
    }
  },
  "required": [
    "inputKey"
  ],
  "additionalProperties": false
}

Response

{
  "type": "object",
  "properties": {
    "jobId": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "paid",
        "running",
        "succeeded",
        "failed"
      ]
    },
    "amountCents": {
      "type": "number"
    },
    "units": {
      "type": "number"
    }
  },
  "required": [
    "jobId",
    "status",
    "amountCents"
  ],
  "additionalProperties": false
}

Examples

curl -X POST https://api.forensassess.com/api/v1/cite \
  -H "Authorization: Bearer $FORENSASSESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inputKey":"user_X/cite/...docx"}'

Node.js

const r = await fetch('https://api.forensassess.com/api/v1/cite', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.FORENSASSESS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "inputKey": "user_X/cite/...docx"
  }),
});
const data = await r.json();

Python

import os, requests
r = requests.post(
    'https://api.forensassess.com/api/v1/cite',
    headers={'Authorization': f"Bearer {os.environ['FORENSASSESS_API_KEY']}"},
    json={"inputKey":"user_X/cite/...docx"}
)
print(r.json())

Sample response

{
  "jobId": "cuid_c3d",
  "status": "paid",
  "amountCents": 2900
}

POST/api/v1/counterscope: counter

Run CounterPoint

Generate a structured weakness analysis of an opposing expert report.

Request body

{
  "type": "object",
  "properties": {
    "inputKey": {
      "type": "string"
    },
    "inputBytes": {
      "type": "integer",
      "minimum": 0
    }
  },
  "required": [
    "inputKey"
  ],
  "additionalProperties": false
}

Response

{
  "type": "object",
  "properties": {
    "jobId": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "paid",
        "running",
        "succeeded",
        "failed"
      ]
    },
    "amountCents": {
      "type": "number"
    },
    "units": {
      "type": "number"
    }
  },
  "required": [
    "jobId",
    "status",
    "amountCents"
  ],
  "additionalProperties": false
}

Examples

curl -X POST https://api.forensassess.com/api/v1/counter \
  -H "Authorization: Bearer $FORENSASSESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inputKey":"user_X/counter/...pdf"}'

Node.js

const r = await fetch('https://api.forensassess.com/api/v1/counter', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.FORENSASSESS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "inputKey": "user_X/counter/...pdf"
  }),
});
const data = await r.json();

Python

import os, requests
r = requests.post(
    'https://api.forensassess.com/api/v1/counter',
    headers={'Authorization': f"Bearer {os.environ['FORENSASSESS_API_KEY']}"},
    json={"inputKey":"user_X/counter/...pdf"}
)
print(r.json())

Sample response

{
  "jobId": "cuid_d4e",
  "status": "paid",
  "amountCents": 15000
}

POST/api/v1/deposcope: depo

Run DepoSummary

Generate a deposition transcript summary with key admissions, contradictions, and cross-examination strategy. Tiered pricing by transcript page count: $50 (1-100), $99 (101-250), $199 (251+).

Request body

{
  "type": "object",
  "properties": {
    "inputKey": {
      "type": "string"
    },
    "inputBytes": {
      "type": "integer",
      "minimum": 0
    }
  },
  "required": [
    "inputKey"
  ],
  "additionalProperties": false
}

Response

{
  "type": "object",
  "properties": {
    "jobId": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "paid",
        "running",
        "succeeded",
        "failed"
      ]
    },
    "amountCents": {
      "type": "number"
    },
    "units": {
      "type": "number"
    }
  },
  "required": [
    "jobId",
    "status",
    "amountCents"
  ],
  "additionalProperties": false
}

Examples

curl -X POST https://api.forensassess.com/api/v1/depo \
  -H "Authorization: Bearer $FORENSASSESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inputKey":"user_X/depo/...pdf"}'

Node.js

const r = await fetch('https://api.forensassess.com/api/v1/depo', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.FORENSASSESS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "inputKey": "user_X/depo/...pdf"
  }),
});
const data = await r.json();

Python

import os, requests
r = requests.post(
    'https://api.forensassess.com/api/v1/depo',
    headers={'Authorization': f"Bearer {os.environ['FORENSASSESS_API_KEY']}"},
    json={"inputKey":"user_X/depo/...pdf"}
)
print(r.json())

Sample response

{
  "jobId": "cuid_e5f",
  "status": "paid",
  "amountCents": 5000
}

GET/api/v1/jobs/:id

Get job status & download URL

Returns the current status and, when finished, a 10-minute presigned download URL.

Response

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "service": {
      "type": "string",
      "enum": [
        "records",
        "cite",
        "counter",
        "depo"
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "paid",
        "running",
        "succeeded",
        "failed"
      ]
    },
    "units": {
      "type": "number"
    },
    "amountCents": {
      "type": "number"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "finishedAt": {
      "type": "string",
      "format": "date-time",
      "nullable": true
    },
    "downloadUrl": {
      "type": "string",
      "format": "uri",
      "nullable": true
    },
    "errorMessage": {
      "type": "string",
      "nullable": true
    }
  },
  "required": [
    "id",
    "service",
    "status",
    "units",
    "amountCents",
    "createdAt",
    "finishedAt",
    "downloadUrl",
    "errorMessage"
  ],
  "additionalProperties": false
}

Examples

curl -X GET https://api.forensassess.com/api/v1/jobs/JOB_ID \
  -H "Authorization: Bearer $FORENSASSESS_API_KEY"

Node.js

const r = await fetch('https://api.forensassess.com/api/v1/jobs/JOB_ID', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.FORENSASSESS_API_KEY}`,
  },
});
const data = await r.json();

Python

import os, requests
r = requests.get(
    'https://api.forensassess.com/api/v1/jobs/JOB_ID',
    headers={'Authorization': f"Bearer {os.environ['FORENSASSESS_API_KEY']}"},
    
)
print(r.json())

Sample response

{
  "id": "cuid_a8f",
  "service": "records",
  "status": "succeeded",
  "units": 1247,
  "amountCents": 9976,
  "createdAt": "2026-05-29T14:00:00Z",
  "finishedAt": "2026-05-29T14:06:41Z",
  "downloadUrl": "https://s3.amazonaws.com/...",
  "errorMessage": null
}