Sessions and evidence API
A session belongs to a subject and has either enroll or observe purpose. Prefer the browser SDK for collection and signed evidence submission. It handles frame-signing material, feature extraction, windowing, and the supported transport lifecycle. Collect evidence from the authenticated user's interaction with your application.
FeatureFrameRequest defines the JSON window envelope; the SDK supplies its signing and modality handling. SDK frames use purpose: "enroll" for enrollment and purpose: "score" for observation. Use the separate consent workflow before setting the per-frame JSON field research_optin. The session's research_enabled flag reports environment and subject eligibility at session creation; storage also requires current consent and frame opt-in.
Status and assessment are different
Browser-safe session status reports accepted coverage, active seconds, modalities, freshness, readiness, and limitations. Use the server assessment endpoint for the full Assurance Profile. Complete enrollment when the server reports readiness.
Status reads can record qualifying Active Brainprint usage in a live environment. The browser-safe response contains the fields needed by the browser workflow.
The server-only assessment operation returns an Assurance Profile. Retrieving an assessment can record qualifying assurance for commercial usage. Call it when the integration needs an assessment. Use the health endpoints for monitoring, and load assessments through an intentional application request. Review Usage and billing before using it in live workflows.
Evidence integrity and shutdown
The service validates signatures, frame identity, time windows, shape, and evidence eligibility before accepting a frame. Accepted evidence contributes to coverage accounting. Signing protects session transport; protect the browser evidence producer through your page and endpoint controls.
End sessions when observation stops or the authenticated account changes. Stop an optional camera controller separately if it is shared with the observer. The operations below describe session creation, evidence submission, safe status, assessment, and session end. See Browser SDK for lifecycle methods and Data flow for collection boundaries.
POST /api/v1/sessions
Start an enroll or observe session for a subject using the scoped browser workflow.
Credential: Scoped browser token or server credential.
Inputs: purpose defaults observe. Optional device_context records application-supplied context. Validate endpoint trust through your application's attestation controls.
Effect and retry behavior: Creates a new session and scoped signing material. Enrollment sessions update enrollment lifecycle; retrying can create another session.
Request body
application/json; required. SessionCreate.
Responses
| HTTP status | Meaning | Body |
|---|---|---|
201 | Session id, purpose, feature version, scoped signing material and research eligibility flag. | application/json: SessionCreated |
422 | The canonical handler returns a Problem for invalid input; correct the request before retrying. | application/problem+json: Problem |
Response handling: Revoked or unavailable subjects and mismatched browser-token subject/origin are refused.
Example
POST /api/v1/sessions{
"subject": "sub_example",
"purpose": "enroll"
}{
"id": "ses_example",
"subject": "sub_example",
"purpose": "enroll",
"research_enabled": false,
"created_at": "2026-10-01T12:00:00Z"
}GET /api/v1/sessions/{session_id}/assessment
Build the current server assessment for the session and its subject.
Credential: Server credential.
Inputs: Server credential and session id. Use browser-safe status for progress UI.
Effect and retry behavior: This GET can record qualifying billable assurance. Request it for its assessment result and use health endpoints for monitoring; see usage and billing.
Usage side effect: this GET can record qualifying billable assurance. See usage rules.
Parameters
| Name / location | Required | Meaning, type and constraints |
|---|---|---|
session_id (path) | Yes | Session identifier owned by the scoped subject in the authenticated environment. string |
Responses
| HTTP status | Meaning | Body |
|---|---|---|
200 | Server Assurance Profile with claim statuses, evidence freshness and limitations. | application/json: AssuranceProfile |
422 | The canonical handler returns a Problem for invalid input; correct the request before retrying. | application/problem+json: Problem |
Response handling: 404 when session or subject state is unavailable. Read insufficient_evidence in the profile as a collection or approval requirement, and follow the returned policy decision.
Example
GET /api/v1/sessions/ses_example/assessment{
"id": "asr_example",
"subject": "sub_example",
"session": "ses_example",
"assessed_at": "2026-10-01T12:00:00Z",
"claims": [],
"coverage": "none",
"evidence_windows": 0,
"active_seconds": 0.0,
"modalities_present": [],
"freshness_ms": null,
"limitations": [
"insufficient evidence"
],
"model_version": "example-model-version",
"rule_version": "example-rule-version",
"feature_schema_version": "example-feature-version",
"insufficient_evidence": true
}POST /api/v1/sessions/{session_id}/end
Stop accepting further evidence in the selected session and return its accounting summary.
Credential: Scoped browser token or server credential.
Inputs: Use the session id and stop the customer observer when the session or signed-in account ends.
Effect and retry behavior: Marks the session ended while preserving the subject and template. Use the subject lifecycle operations for revocation or deletion.
Parameters
| Name / location | Required | Meaning, type and constraints |
|---|---|---|
session_id (path) | Yes | Session identifier owned by the scoped subject in the authenticated environment. string |
Responses
| HTTP status | Meaning | Body |
|---|---|---|
200 | ended receipt with elapsed session seconds and accounted evidence-window count. | application/json: SessionEnded |
422 | The canonical handler returns a Problem for invalid input; correct the request before retrying. | application/problem+json: Problem |
Response handling: Missing or out-of-scope sessions are refused; reconcile an uncertain response rather than continuing to submit frames.
Example
POST /api/v1/sessions/ses_example/end{
"session": "ses_example",
"status": "ended",
"duration_seconds": 30,
"evidence_windows": 5
}POST /api/v1/sessions/{session_id}/evidence
Submit a session-signed feature window and receive accepted coverage accounting.
Credential: Scoped browser token or server credential.
Inputs: Use the browser SDK’s exact-body signing and feature transport. JSON fields alone are insufficient. Match enroll/score purpose to the session; research_optin defaults false.
Effect and retry behavior: May contribute accepted non-overlapping evidence to coverage and enrollment readiness. Duplicate frames never count as fresh evidence.
Parameters
| Name / location | Required | Meaning, type and constraints |
|---|---|---|
session_id (path) | Yes | Session identifier owned by the scoped subject in the authenticated environment. string |
Request body
application/json; required. FeatureFrameRequest.
Responses
| HTTP status | Meaning | Body |
|---|---|---|
200 | accepted, neutral or rejected status plus coverage, reasons and enrollment readiness. | application/json: EvidenceAck |
422 | The canonical handler returns a Problem for invalid input; correct the request before retrying. | application/problem+json: Problem |
Response handling: Unsigned, stale, replayed, overlapping, malformed or purpose-mismatched windows are refused or neutralized. Opt-in without required consent/environment eligibility returns 422.
Example
POST /api/v1/sessions/ses_example/evidence{
"frame_id": "frame-example-7",
"timestamp": 1790856000000,
"duration_ms": 5000,
"window_start": 1790855995,
"window_end": 1790856000,
"features": {},
"purpose": "enroll",
"research_optin": false
}{
"status": "neutral",
"coverage": "none",
"evidence_windows": 0,
"active_seconds": 0,
"modalities_present": [],
"reason_codes": [],
"enrollment_ready": false
}GET /api/v1/sessions/{session_id}/status
Inspect accepted evidence coverage, freshness and enrollment readiness without exposing a full server assessment.
Credential: Scoped browser token or server credential.
Inputs: Use the subject’s scoped session id.
Effect and retry behavior: Returns status without changing enrollment state or authorizing a business action. A qualifying assurance profile can record Active Brainprint usage under the agreement's shadow-use terms. The enrollment_ready flag allows your backend to request enrollment completion.
Parameters
| Name / location | Required | Meaning, type and constraints |
|---|---|---|
session_id (path) | Yes | Session identifier owned by the scoped subject in the authenticated environment. string |
Responses
| HTTP status | Meaning | Body |
|---|---|---|
200 | Browser-safe coverage, accepted-window count, active duration, freshness and readiness. | application/json: StatusSummary |
422 | The canonical handler returns a Problem for invalid input; correct the request before retrying. | application/problem+json: Problem |
Response handling: Use an active session belonging to the authenticated subject and environment. Inspect the response code when that session needs renewal or correction.
Example
GET /api/v1/sessions/ses_example/status{
"session": "ses_example",
"coverage": "partial",
"evidence_windows": 5,
"active_seconds": 25,
"modalities_present": [
"keyboard"
],
"freshness_ms": 500,
"human_readable": "Evidence is available.",
"enrollment_ready": true,
"limitations": []
}