API Documentation

The Revealense external API - create and upload assessments, fetch results and reports, all from your own system.

Getting Started

What this API does

Create an Assessment under an existing Subject Profile, upload a video to it, and retrieve the resulting analysis and reports - all over plain HTTP. See About for the bigger picture.

Submit a video file you already have, uploaded as a whole - each video represents one person. See Core Concepts for how to relate footage of multiple people from the same real session.

Before you start: Projects and Subject Profiles

Every assessment belongs to a Subject Profile - the person being assessed - which in turn belongs to a Project. Both are created through this API, same as everything else - see Projects and Subject Profiles.

Base URL

⚠️ Every base URL and API key shown in this document is a placeholder (https://api.example.com, <YOUR_API_KEY>). Your actual base URL and key are provided separately.

Every request in this documentation is relative to your account's base URL:

https://api.example.com

Replace this with the real base URL for your own environment - everything else below stays the same.

Authentication

Every request carries your API key in a single header, exactly as shown - there's no OAuth flow, no token exchange, no expiry to refresh:

revealense_key: <YOUR_API_KEY>

A missing or invalid key gets a plain 401 Unauthorized. A key that's valid but doesn't have permission for the specific thing you're trying to do gets a 403 Forbidden - see Rate Limits & Errors for the full picture of what can go wrong and why.

Getting a key

API keys are created inside the Revealense web app, under API Keys in the sidebar - visible to whoever on your team has permission to manage them. When you create a key, you choose exactly which actions it's allowed to perform (see the permission shown at the top of every endpoint in this documentation) - a key only ever needs to be as broad as your integration actually requires.

⚠️The raw key value is shown to you exactly once, at creation time. Revealense never stores it in a form it can show you again - if you lose it, revoke it and create a new one.

That same creation response also includes top_level_project_id - the Project id your key can act under. Use it as the parent_project_id for your very first call to Projects.

Scoping a key to one project

By default, a key can act on any Subject Profile anywhere in your account. If you'd rather limit one key to a single project (and everything under it), you can scope it to that project when you create it - useful if different teams or applications on your side should each get their own, narrower key.

Safely retrying a request

A network timeout doesn't tell you whether your request actually went through - retrying it blindly could create a second, real duplicate. Add an Idempotency-Key header (any unique string you generate yourself) to any POST that creates something - Projects, Subject Profiles, Assessments, Associations:

Idempotency-Key: a-unique-string-you-generate-once-per-request

The first request with a given key runs normally. Retry it with the same key and same body, and you get back the exact same response again - no new resource is created. Reusing a key with a different body returns a 422 instead of guessing which one you meant. Leaving the header off entirely works exactly as before - it's optional, not required.

Your first request

Here's the shortest real path from "I have a key" to "I have results" - this is the map, each step covered in full on its own page.

  1. Create a Project (first time only) - Projects. You get back a project_id.
  2. Create a Subject Profile for the person being assessed, under that Project - Subject Profiles. You get back a subject_profile_id.
  3. Create an Assessment for that Subject Profile - Assessments. You get back a conversation_id.
  4. Request an upload URL for that Assessment, then PUT your video file straight to it - also in Assessments.
  5. Tell Revealense the upload is finished. This is what actually starts analysis.
  6. Poll the Assessment's status every so often until it's COMPLETED (analysis of an average-length video typically takes a few minutes).
  7. Discover a report template, then generate a report and fetch its content - Reports.

The flow, visually

sequenceDiagram
    participant You
    participant Revealense
    participant Storage
    You->>Revealense: POST /projects (first time only)
    Revealense-->>You: 201 project_id
    You->>Revealense: POST .../subject-profiles
    Revealense-->>You: 201 subject_profile_id
    You->>Revealense: POST /conversations
    Revealense-->>You: 201 conversation_id
    You->>Revealense: POST .../premade-upload-url
    Revealense-->>You: 200 upload_url
    You->>Storage: PUT video file
    Storage-->>You: 200 OK
    You->>Revealense: POST .../finish-premade-upload
    Revealense-->>You: 202 analysis starts
    You->>Revealense: GET /conversations/id (repeat until COMPLETED)
    Revealense-->>You: status COMPLETED
    You->>Revealense: GET .../report-templates
    Revealense-->>You: template list
    You->>Revealense: POST .../generate-report
    Revealense-->>You: report_id
    You->>Revealense: GET .../languages/EN/content
    Revealense-->>You: the full report text
        

A complete example, start to finish

# 1. Create a Project (first time only - use your key's own top_level_project_id)
curl -X POST https://api.example.com/projects \
  -H "revealense_key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "parent_project_id": 78, "name": "2026 Exit Interviews" }'

# -> { "project_id": 142, "parent_project_id": 78, "name": "2026 Exit Interviews" }

# 2. Create a Subject Profile under that Project
curl -X POST https://api.example.com/projects/142/subject-profiles \
  -H "revealense_key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "first_name": "Jordan", "last_name": "Rivera", "unique_id": "EMP-20451" }'

# -> { "subject_profile_id": 4821, "person_id": 5102, "project_id": 142 }

# 3. Create an Assessment for that Subject Profile
curl -X POST https://api.example.com/subject-profiles/4821/conversations \
  -H "revealense_key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Exit interview - J. Rivera" }'

# -> { "conversation_id": 9931, "subject_profile_id": 4821, "upload_encryption_key": "..." }

# 4. Get a one-time upload URL for that Assessment
curl -X POST https://api.example.com/conversations/9931/premade-upload-url \
  -H "revealense_key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{}'

# -> { "upload_url": "https://storage.googleapis.com/....(a real signed URL)" }

# 5. Upload the actual video file to that URL
curl -X PUT "<the upload_url from step 4>" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @interview.mp4

# 6. Tell Revealense the upload is finished - this starts analysis
curl -X POST https://api.example.com/conversations/9931/finish-premade-upload \
  -H "revealense_key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{}'

# 7. Poll status until it's COMPLETED
curl https://api.example.com/conversations/9931 \
  -H "revealense_key: <YOUR_API_KEY>"

# -> { "conversation_id": 9931, "status": "ANALYZING", "progress_percent": 40, ... }
# ... wait, poll again ...
# -> { "conversation_id": 9931, "status": "COMPLETED", "progress_percent": 100, ... }

Core Concepts

How the main pieces fit together, from your API Key down to a finished Report, with the two real side-relationships (Subject Associations and session-grouped Assessments) branching off:

graph TD
    K[API Key] --> P[Project]
    P --> SP[Subject Profile]
    SP --> C[Conversation / Assessment]
    C --> R[Report]
    SP -. Subject Association .- SP2[Subject Profile]
    C -. same session source_recording_id .- C2[Conversation]
        

Project, Subject Profile, and Assessment

A Project is a container for your Subject Profiles - organize them however makes sense for your own account (by team, by year, by case type). A Subject Profile is the person - created once under a Project, and reused for every Assessment that person ever has. An Assessment is one specific recording session for that person - one video, one set of results, one set of reports. A Subject Profile can have any number of Assessments over time (an exit interview today, a follow-up assessment next quarter - each its own Assessment).

This API's own endpoints and fields call an Assessment a Conversation (/conversations, conversation_id) - the two names mean the same thing throughout this documentation.

See Projects and Subject Profiles for the real endpoints, and Assessments for creating the recording itself.

One person per video

Every video submitted through this API represents exactly one person. If a real recording session involved more than one person - say, two cameras in the same interview room - send each person's own footage as its own Assessment, and relate them with join_source_recording_id, below.

Relating Assessments from the same real session

If you have separate camera footage of two (or more) people from the same real event - say, an interviewer and a candidate, each on their own camera - you can mark their Assessments as belonging to the same session. This doesn't change how either video is analyzed (each is still processed as its own single-person recording); it just lets Revealense's reporting and UI know they happened together.

Pass join_source_recording_id when creating an Assessment, set to the conversation_id of any Assessment already in the group. There's no need to know every member up front - join one at a time, whenever each file actually arrives:

# Monday: upload the interviewer's camera
POST /subject-profiles/101/conversations
{ "name": "Panel interview - Camera A" }
-> { "conversation_id": 500, ... }

# Wednesday: the candidate's own camera from the same session arrives
POST /subject-profiles/205/conversations
{ "name": "Panel interview - Camera B", "join_source_recording_id": 500 }
-> { "conversation_id": 507, "source_recording_id": 500, ... }

# A month later, a third camera from the same real session turns up
POST /subject-profiles/309/conversations
{ "name": "Panel interview - Camera C", "join_source_recording_id": 500 }
-> { "conversation_id": 581, "source_recording_id": 500, ... }

The source_recording_id you get back in the response is the group's shared id - the same value across every member, usable to identify "these all belong together," even though each one keeps its own independent video, status, and results.

Subject Associations

Separately from any specific recording, two Subject Profiles can be linked as a standing relationship - a parent and child, siblings, or any other connection worth recording permanently. Independent of video or sessions, true regardless of how many assessments either person has. See Associations for the real endpoints.

Projects

Every Subject Profile belongs to a Project. Create one under your account's top-level project, then create Subject Profiles under it. Your API key's own top_level_project_id (returned when the key was created - see Getting a key) is the id to use as parent_project_id for your very first Project.

POST/projectsrequires: project:create

Request body

FieldTypeRequiredDescription
parent_project_idintegeryesAn existing Project's id - your key's top_level_project_id for the first one, or another Project you've already created for a nested one.
namestringyes
descriptionstringno
POST /projects
revealense_key: <YOUR_API_KEY>
Content-Type: application/json

{
  "parent_project_id": 78,
  "name": "2026 Exit Interviews",
  "description": "optional"
}
201 Created

{
  "project_id": 142,
  "parent_project_id": 78,
  "name": "2026 Exit Interviews"
}
GET/projects/{project_id}requires: project:view
200 OK

{
  "project_id": 142,
  "client_id": 9,
  "parent_project_id": 78,
  "name": "2026 Exit Interviews",
  "description": "optional",
  "active": true
}
PATCH/projects/{project_id}requires: project:update

Any subset of name, description, active.

DELETE/projects/{project_id}requires: project:delete

Delete a Project's own sub-projects first - a Project with children, or your account's top-level Project itself, can't be deleted directly.

Subject Profiles

A Subject Profile is the person being assessed - created under a Project (see Projects). Search first to check whether this exact person already exists in this Project before creating a new one.

POST/projects/{project_id}/subject-profilesrequires: subject:create

Request body

FieldTypeRequiredDescription
person_idintegernoFrom a prior search match - skips the fields below entirely.
first_name / last_namestringyes, unless person_id is set
gov_id / unique_idstringat least one, unless person_id is setSame fields the search call above matches on.

Raw person details:

POST /projects/142/subject-profiles
revealense_key: <YOUR_API_KEY>
Content-Type: application/json

{
  "first_name": "Jordan",
  "last_name": "Rivera",
  "unique_id": "EMP-20451"
}

Or, after a search match:

{
  "person_id": 5102
}
201 Created

{
  "subject_profile_id": 4821,
  "person_id": 5102,
  "project_id": 142
}
iA Subject Profile for the same real person already exists in this Project? You get back a 409 pointing at its subject_profile_id instead of a duplicate:
409 Conflict

{
  "message": "A Subject Profile for this person already exists in this project.",
  "subject_profile_id": 4821
}
POST/projects/{project_id}/subject-profiles/bulkrequires: subject:create

For onboarding many people at once (e.g. importing an existing roster) - up to 100 per call. Body: { "subjects": [ ...same shape as the single create above, one per person ] }.

POST /projects/142/subject-profiles/bulk
revealense_key: <YOUR_API_KEY>
Content-Type: application/json

{
  "subjects": [
    { "first_name": "Jordan", "last_name": "Rivera", "unique_id": "EMP-20451" },
    { "first_name": "Alex", "last_name": "Chen", "unique_id": "EMP-20452" },
    { "last_name": "Missing-First-Name", "unique_id": "EMP-20453" }
  ]
}

Always returns 207 Multi-Status - one real result per item, in the same order as your request, each with the exact status/body the single-create endpoint would have returned for that one person alone. One bad entry never fails the rest of the batch:

207 Multi-Status

{
  "results": [
    { "index": 0, "status": 201, "body": { "subject_profile_id": 4821, "person_id": 5102, "project_id": 142 } },
    { "index": 1, "status": 201, "body": { "subject_profile_id": 4822, "person_id": 5103, "project_id": 142 } },
    { "index": 2, "status": 400, "body": { "message": "first_name and last_name are required when person_id is not supplied." } }
  ]
}
GET/projects/{project_id}/subject-profilesrequires: subject:view

Optional query params: ?page=1&limit=20 - omit both to get everything in one call.

200 OK

{
  "subject_profiles": [
    {
      "subject_profile_id": 4821,
      "project_id": 142,
      "status": "ACTIVE",
      "person": { "person_id": 5102, "first_name": "Jordan", "last_name": "Rivera", "email": null }
    }
  ],
  "total": 1
}
GET/subject-profiles/{subject_profile_id}requires: subject:view
200 OK

{
  "subject_profile_id": 4821,
  "project_id": 142,
  "status": "ACTIVE",
  "person": { "person_id": 5102, "first_name": "Jordan", "last_name": "Rivera", "email": null }
}
PATCH/subject-profiles/{subject_profile_id}requires: subject:update

Body: { "status": "ACTIVE" } or { "status": "DISABLED" }.

DELETE/subject-profiles/{subject_profile_id}requires: subject:delete

A soft delete - the Subject Profile and everything under it stay in Revealense's records, hidden from view. Restorable below.

⚠️Need to permanently erase a person's data instead - for a real data-erasure request, not routine cleanup? Add ?hard=true: DELETE /subject-profiles/{subject_profile_id}?hard=true. This requires a separate permission (subject:erase) that's never granted by default - your account's Admin grants it explicitly, to a role or directly to an API key, before it can be used at all. Once granted, it's a normal, directly callable action - nothing is routed through Revealense staff. It permanently deletes the real video/results files, the Subject Profile and every Conversation/Report under it, and can't be undone. Returns a 409 instead if this Subject Profile's own video is the shared source for another Subject Profile's recording (a rare case - contact your Revealense contact if you hit it).
POST/subject-profiles/{subject_profile_id}/restorerequires: subject:delete

Reverses a delete.

GET/projects/{project_id}/subject-profiles/deletedrequires: subject:delete

Every deleted Subject Profile in a Project - use this to find the subject_profile_id to pass to restore, above.

Assessments

An Assessment is one recording session - see Core Concepts for the one-person-per-video rule. In this API's own endpoints and fields, an Assessment is called a Conversation (/conversations, conversation_id) - the two names mean the same thing throughout.

POST/subject-profiles/{subject_profile_id}/conversationsrequires: assessment:create

Creates a new Assessment under the given Subject Profile and returns a one-time encryption key for the upload step below.

Request body

FieldTypeRequiredDescription
namestringyesA label for this Assessment - shown in the Revealense web app, not used in analysis.
voice_analysis_expectedbooleanno (default true)Set false for a video where nobody is expected to speak at all (e.g. a silent stimulus/reaction recording) - voice analysis is skipped entirely rather than running against silence.
base_voice_startnumber (seconds)noThe start of a window, somewhere in this recording, where only your declared subject is talking - the most reliable way to attribute their voice. If you don't know of one, omit this (and base_voice_end) entirely - Revealense auto-attributes the subject when the recording genuinely has one voice, and flags it for review (blocking report generation until resolved) only when it can't tell with confidence.
base_voice_endnumber (seconds)noThe end of that same window - must be at least 3 seconds after base_voice_start when provided.
join_source_recording_idintegernoThe conversation_id of an existing Assessment this one should be grouped with - see Core Concepts.

Example

POST /subject-profiles/4821/conversations
revealense_key: <YOUR_API_KEY>
Content-Type: application/json

{
  "name": "Exit interview - J. Smith",
  "base_voice_start": 12.0,
  "base_voice_end": 18.0
}
201 Created

{
  "conversation_id": 9931,
  "subject_profile_id": 4821,
  "upload_encryption_key": "7h2p9s...=="
}

With join_source_recording_id set, the response also includes the shared group id:

201 Created

{
  "conversation_id": 9932,
  "subject_profile_id": 4822,
  "upload_encryption_key": "k1m0q7...==",
  "source_recording_id": 9931
}

Response fields

FieldDescription
conversation_idThe id you'll use in every other call for this Assessment.
upload_encryption_keyReserved for Revealense's own internal upload flow - not needed when using the premade-upload-url endpoint below.
source_recording_idOnly present when you passed join_source_recording_id - the group's shared id.
POST/conversations/{conversation_id}/premade-upload-urlrequires: assessment:create

Returns a one-time signed URL you upload your video file to directly. No request body needed.

200 OK

{ "upload_url": "https://storage.googleapis.com/....(valid for a limited time - use it right away)" }

Upload the file with a plain PUT, body = the raw video bytes:

curl -X PUT "<upload_url>" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @your-video.mp4
⚠️The URL expires after a short time - request it right before you're ready to upload, not in advance.
POST/conversations/{conversation_id}/finish-premade-uploadrequires: assessment:create

Tells Revealense your upload is complete - this is what actually starts analysis. Call it only after the PUT above has fully finished. No request body needed.

202 Accepted

{ "status": "scan_dispatched" }

Your file first goes through a malware/integrity scan, then real analysis begins. Poll GET /conversations/{id} below to track progress.

iNo file size limit - send whatever you have. This call does reject with a 400 if the uploaded file is unreasonably large, which almost always means the wrong file was sent - a sanity check, not a real restriction.
iCan only be called once per Assessment. If you're not sure whether an earlier call actually went through, don't retry this endpoint blindly - check GET /conversations/{id} first. A second call returns 409 instead of starting a second analysis run.
GET/conversations/{conversation_id}requires: assessment:view

Full details and current status for one Assessment.

200 OK

{
  "conversation_id": 9931,
  "subject_profile_id": 4821,
  "name": "Exit interview - J. Smith",
  "status": "COMPLETED",
  "file_type": "UPLOAD",
  "started_at": null,
  "ended_at": null,
  "detected_language": "en",
  "progress_percent": 100,
  "subject_display_name": "J. Smith",
  "voice_analysis_expected": true,
  "compare_notes": "",
  "compare_notes_updated_at": null,
  "co_subjects": []
}

Response fields

FieldDescription
statusWAITING → ANALYZING → COMPLETED (or FAILED). Reports can only be generated once COMPLETED.
progress_percent0-100, how far analysis has gotten. Useful for a progress indicator while polling.
detected_languageThe language Revealense's voice analysis detected, once available; null until then.
voice_analysis_expectedReflects whatever you set at creation (or the default).
GET/conversations/status?ids=9931,9932,9933requires: assessment:view

Tracking many Assessments at once? Check up to 100 in a single call instead of polling each one individually - same status/progress_percent fields as the single-get above, nothing else. An id that doesn't exist, or isn't yours, is silently left out of the response rather than failing the whole call.

200 OK

{
  "conversations": [
    { "conversation_id": 9931, "status": "COMPLETED", "progress_percent": 100 },
    { "conversation_id": 9932, "status": "ANALYZING", "progress_percent": 55 },
    { "conversation_id": 9933, "status": "WAITING", "progress_percent": null }
  ]
}
iThis endpoint has its own, more generous rate limit (300/minute) than the general tier - see Rate Limits & Errors.

Why no push notifications (webhooks)?

We don't currently offer a webhook/callback option - this bulk endpoint, together with its own generous rate limit, is the intended way to track many Assessments without excessive polling. A webhook means our servers make outbound requests to a URL you control, which is a real security surface (server-side request forgery) that needs careful, dedicated engineering to do safely - we'd rather not ship that without a real need for it. If your integration genuinely can't work with polling, talk to your Revealense contact.

GET/subject-profiles/{subject_profile_id}/assessmentrequires: subject:view

Lists every Assessment under a Subject Profile - use this to find ones you created earlier without having stored their ids yourself. Optional query params: ?page=1&limit=20 - omit both to get everything in one call.

200 OK

{
  "subject_profile_id": 4821,
  "conversations": [
    { "conversation_id": 9931, "name": "Exit interview - J. Smith", "status": "COMPLETED", "created_at": "2026-10-01T09:14:02.000Z" }
  ],
  "conversations_total": 1
}
iA deleted Assessment (below) never appears in this list again.
DELETE/conversations/{conversation_id}requires: assessment:delete

A soft delete - the Assessment, its video, and its results all stay in Revealense's records, just hidden from view (including from the list endpoint above). It can be restored.

200 OK

{ "message": "Conversation deleted.", "entity_id": 9931, "entity_type": "conversation" }
POST/conversations/{conversation_id}/restorerequires: assessment:delete

Reverses a delete. The Assessment comes back in WAITING status - if it had already finished analysis before being deleted, its real results and reports are untouched and still available.

200 OK

{ "message": "Conversation restored.", "entity_id": 9931, "status": "WAITING" }

Reports

A report is generated from a completed Assessment (status: "COMPLETED" - see Assessments) against one of your account's available report templates. Generating a report in a second language, or regenerating one, uses the exact same endpoint - just call it again with the extra language, or the same report_id.

GET/client/{client_id}/content-library/report-templatesrequires: a valid key for this client

Lists the report templates available to your account - use this to find a real platform_report_template_id before calling generate-report below. client_id is your own account's id, the same one shown in the URL of the API Keys page where you created your key.

200 OK

{
  "report_templates": [
    { "platform_report_template_id": 7, "name": "Standard Exit Interview Profile" },
    { "platform_report_template_id": 12, "name": "Integrity Screening Summary" }
  ]
}
POST/conversations/{conversation_id}/generate-reportrequires: subject-report:generate

Request body

FieldTypeRequiredDescription
platform_report_template_idintegeryesFrom the templates endpoint above.
languagesarrayno (default: English)Up to 2 entries, each { "name": "English", "prefix": "EN" }.
video_contextstringnoFree-text background Revealense's report-writing uses as context - e.g. what kind of interview this was.
header_dataobjectnoAny of classification, subject, date, prepared_by, source_material - shown on the report's own cover/header.
report_idintegernoPass an existing report's id to add a language or regenerate it, reusing that report's own original context instead of sending video_context again.
POST /conversations/9931/generate-report
revealense_key: <YOUR_API_KEY>
Content-Type: application/json

{
  "platform_report_template_id": 7,
  "languages": [{ "name": "English", "prefix": "EN" }],
  "video_context": "Exit interview, voluntary resignation, 45 minutes.",
  "header_data": {
    "subject": "J. Smith",
    "prepared_by": "Acme HR Systems"
  }
}
200 OK

{ "success": true, "message": "Report generation dispatched.", "report_id": 2201 }
iThis call returns immediately - generation happens in the background. Poll GET /reports/{id} below and check each language's own status.
⚠️Calling this before the Assessment has finished analysis returns a 409 - see Rate Limits & Errors.
GET/reports/{report_id}requires: subject-report:view

Status and metadata for a report, including per-language progress.

200 OK

{
  "id": 2201,
  "subject_profile_id": 4821,
  "platform_report_template_id": 7,
  "template_name": "Standard Exit Interview Profile",
  "created_at": "2026-10-01T10:02:11.000Z",
  "context_snippet": "Exit interview, voluntary resignation, 45 minutes.",
  "has_full_context": false,
  "has_design": true,
  "languages": [
    { "language_code": "EN", "status": "COMPLETED", "progress": 100, "error": null, "created_at": "2026-10-01T10:03:40.000Z" }
  ],
  "assessments": [
    { "subject_profile_id": 4821, "subject_display_name": "J. Smith", "examinee_id": null, "conversation_id": 9931, "role": null }
  ]
}
FieldDescription
languages[].statusGENERATING → COMPLETED (or FAILED). Fetch content only once COMPLETED.
has_designWhether this template has a visual, component-based design - if true, the rendered-HTML endpoint below is also available.
GET/reports/{report_id}/languages/{language_code}/contentrequires: subject-report:view

The actual generated report text, as Markdown.

200 OK

{
  "status": "COMPLETED",
  "language_code": "EN",
  "content": "# Exit Interview Report\n\n## Summary\n...(the full report text, in Markdown)...",
  "design_id": "hpp-v2",
  "design_content": { "...": "a structured, component-based version of the same report" },
  "design_update_available": false
}

If this language hasn't finished generating yet, you get back { "status": "GENERATING", "progress": 60, "error": null } instead of real content - check status before assuming content is present.

GET/reports/{report_id}/languages/{language_code}/rendered-htmlrequires: subject-report:view

A ready-to-display HTML version of the report, for templates that have a visual design assigned (has_design: true above). Returns real text/html, meant to be embedded directly (e.g. in an <iframe>) rather than parsed.

Returns 404 if this template has no design assigned - use the plain Markdown content endpoint above instead in that case.

GET/subject-profiles/{subject_profile_id}/reportsrequires: subject-report:view

Every report ever generated for a Subject Profile, most recent first.

200 OK

{
  "reports": [ { "id": 2201, "template_name": "Standard Exit Interview Profile", "...": "same shape as GET /reports/{id} above" } ],
  "total": 1
}

Optional query params: ?page=1&limit=20 - omit both to get everything in one call.

DELETE/reports/{report_id}requires: subject-report:delete

Deletes a report and every one of its generated languages. Returns { "success": true }.

DELETE/reports/{report_id}/languages/{language_code}requires: subject-report:delete

Deletes just one language from a report. Deleting the last remaining language deletes the whole report instead - the response's report_deleted field tells you which happened.

{ "success": true, "report_deleted": false }

Associations

A standing link between two Subject Profiles - see Core Concepts for how this differs from grouping Assessments from the same recording session. Both Subject Profiles must already exist and belong to your account.

POST/subject-profiles/{subject_profile_id}/associationsrequires: subject:manage-associates

Request body

FieldTypeRequiredDescription
associate_subject_profile_idintegeryesThe other Subject Profile's id. Must belong to the same account; can't be the same id as the one in the URL.
role_labelstringnoFreeform, e.g. "Sibling", "Parent" - a label, not a controlled list.
POST /subject-profiles/4821/associations
revealense_key: <YOUR_API_KEY>
Content-Type: application/json

{
  "associate_subject_profile_id": 4822,
  "role_label": "Sibling"
}
201 Created

{
  "association_id": 310,
  "subject_profile_id": 4821,
  "associate_subject_profile_id": 4822,
  "role_label": "Sibling"
}

The link works in both directions - creating it from either Subject Profile's side has the same effect.

GET/subject-profiles/{subject_profile_id}/associationsrequires: subject:view

Every association for a Subject Profile. Optional query params: ?page=1&limit=20 - omit both to get everything in one call.

200 OK

{
  "subject_profile_id": 4821,
  "associations": [
    {
      "association_id": 310,
      "associate_subject_profile_id": 4822,
      "associate_name": "A. Smith",
      "role_label": "Sibling",
      "access_status": null,
      "access_via": null,
      "grant_id": null,
      "associate_project_id": null
    }
  ],
  "total": 1
}

access_status, access_via, and grant_id reflect Revealense's own internal cross-project access requests between staff members - they're always null for an API-key request and can be ignored.

Rate Limits & Errors

Rate limits

Limits are tracked per API key, in four tiers:

TierLimitApplies to
Expensive actions30 requests / minuteCreate/search a Subject Profile, create an Assessment, request an upload URL, finish an upload, generate a report, hard-delete a Subject Profile (?hard=true)
Bulk creation10 requests / minuteBulk-create Subject Profiles - its own, stricter tier, since each item in the request does the same real work as one single create
Status checks300 requests / minuteGetting one Assessment's status, and the bulk status-check endpoint - deliberately generous, separate from the general tier, since tracking many in-flight Assessments means polling often
Everything else120 requests / minuteCreate/list/get endpoints not covered above, and a plain (non-hard) delete

Every response includes standard headers so you can track your own usage without guessing:

RateLimit-Policy: 120;w=60
RateLimit-Limit: 120
RateLimit-Remaining: 87
RateLimit-Reset: 42

Going over the limit gets a plain, predictable response:

429 Too Many Requests

{ "message": "Too many requests - please slow down and try again shortly." }
iNeed a higher limit? Talk to your Revealense contact.

Error responses

Every error follows the same plain shape:

{ "message": "A plain, human-readable description of what went wrong." }

The HTTP status code itself tells you what kind of problem it is:

StatusMeaningWhat to do
400Bad RequestSomething in your request body or params is missing, invalid, or (for multi-person fields) unsupported. The message says exactly what.
401UnauthorizedYour revealense_key header is missing, malformed, or has been revoked. Check the key value and its status in the web app.
403ForbiddenYour key is valid but doesn't have the specific permission this action needs, or the resource belongs to a different project than your key is scoped to. Check the permission listed at the top of the endpoint.
404Not FoundThe id in the URL doesn't exist, or doesn't belong to your account.
409ConflictThe action can't happen yet given the resource's current state - trying to generate a report before analysis has finished, calling finish-upload a second time, hard-deleting a Subject Profile whose video another one depends on, or restoring something that isn't deleted.
429Too Many RequestsYou've hit the rate limit above. Wait and retry - the RateLimit-Reset header tells you how long.
500 / 502Server errorSomething went wrong on our side. Safe to retry after a short delay; contact Revealense if it persists.

About

The Revealense external API lets a system you already run - a case-management tool, an HR platform, an internal investigation workflow - create assessments, upload recordings, and pull back Revealense's analysis results and reports over plain HTTP, without anyone using the Revealense web app directly.

This mirrors the same real flow Revealense's own web app uses internally - Projects, Subject Profiles, Assessments, and Reports - just driven entirely by your own system instead of a person clicking through a UI. The web app itself is only needed to manage your API keys and billing; everything else can be done through this API alone.

Questions about this API, or need something it doesn't cover yet? Talk to your Revealense contact.