---
title: "Submit an SDK evidence window"
method: POST
path: "/api/v1/sessions/{session_id}/evidence"
tags: ["canonical"]
---

# Submit an SDK evidence window

`POST /api/v1/sessions/{session_id}/evidence`

## Request

- Base URL: `https://app.graypass.org` (the document declares no server; this is the origin it was published from)
- URL: `https://app.graypass.org/api/v1/sessions/{session_id}/evidence`
- Auth: HTTP bearer

Submit a session-signed feature window and receive accepted coverage accounting.

## Path parameters

- `session_id` string, required

## Request body

- FeatureFrameRequest: A feature window submitted by the supported SDK, which handles extraction, session signing and transport.
  - `duration_ms` number, required: Frame duration in milliseconds; finite values from 0 through 600000 are accepted by the schema. Accepted coverage applies additional server checks.
  - `features` object, required: SDK-produced modality feature object containing bounded derived features. Raw key content, images, video and audio stay outside the evidence submission.
  - `frame_id` string, required: Unique identifier for this frame within the session; repeated identifiers are refused by replay controls.
  - `purpose` string: Frame purpose: enroll for enrollment evidence; score for observation. It must match the session’s purpose.
  - `research_optin` boolean: Separate per-frame JSON opt-in, default false. Retention requires this field plus current subject consent, environment participation and deployment eligibility.
  - `timestamp` number, required: Frame timestamp. The browser SDK emits Unix milliseconds; native-compatible Unix seconds are also normalized. Use the SDK’s clock convention consistently.
  - `window_end` number, nullable: Optional evidence-window end as Unix seconds. Bounds must describe a fresh, non-overlapping window for this session.
  - `window_start` number, nullable: Optional evidence-window start as Unix seconds. When omitted, bounds are derived from timestamp and duration_ms.

## Response `200`

accepted, neutral or rejected status plus coverage, reasons and enrollment readiness.

- EvidenceAck: Receipt for one evidence window, including whether it contributed to accepted coverage.
  - `active_seconds` number, required: Duration of accepted active evidence in seconds.
  - `coverage` 'none' | 'sparse' | 'partial' | 'sufficient', required: Evidence-coverage category: none, sparse, partial or sufficient. Describes the amount and variety of accepted evidence.
  - `enrollment_ready` boolean: Whether the server’s accepted coverage meets enrollment readiness. Client elapsed time alone is insufficient.
  - `evidence_windows` integer, required: Number of accepted, non-overlapping evidence windows accounted for in this session or profile.
  - `modalities_present` string[]: Names of observed evidence modalities included in coverage accounting.
  - `reason_codes` string[]: Stable reason identifiers explaining acceptance, limitations or a decision; resolve them in the reason-code catalog.
  - `status` 'accepted' | 'neutral' | 'rejected', required: accepted contributes to coverage. Interpret neutral and rejected through the associated reason codes.

## Other responses

- `422`: The canonical handler returns a Problem for invalid input; correct the request before retrying.

---

[API](https://skmtc.dev/graypass/apis/graypass-api.md) - [All operations](https://skmtc.dev/graypass/apis/graypass-api/llms.txt) - [OpenAPI document](https://skmtc.dev/graypass/apis/graypass-api/revisions/5f9ab64fdfdb?raw)