Skip to main content
POST
cURL

Authorizations

Authorization
string
header
required

Your API key, sent as Authorization: Bearer <key>. A key is nrk_live_ or nrk_test_, a 26-character key id, _ and a 43-character secret. Account, audit and usage data stay within the key's environment. Dedicated team scopes apply across the workspace.

assess creates and reads assessments, records outcomes and reports key usage. investigate reads accounts, assessment history and request diagnostics without export or enforcement access. The legacy history scope also permits account exports, submitted identifiers and enforcement reports. delete permits account and assessment deletion.

evidence or detailed adds detailed merged evidence and submitted identifiers where the operation permits them. Neither grants access to the underlying resource alone. exports permits exports with the underlying account or audit scope. audit reads audit events and usage reads usage. audit_manage manages audit streams and retention, and includes audit-read and export authority.

webhooks manages webhook endpoints. integrations manages hosted auth-provider integrations. management manages keys, settings, lists, reviews and policy evaluations in the key's environment. New keys cannot exceed the issuer's effective permissions.

settings reads configuration, previews policy and list changes, runs evaluations and changes retention. Publishing decision policy or changing lists requires settings and policy_publish together, or the legacy management scope.

groups creates and reads groups, adds people, starts and cancels screenings and records decisions on people, in the key's environment.

members reads the workspace directory. members_manage also administers non-owner members and invitations. These scopes require a live key issued by a current owner with access to both environments. They grant access across the workspace. management does not grant team access. API keys cannot change owners or accept invitations.

A missing, unknown, revoked or expired key answers 401. A valid key without a required scope answers 403.

Path Parameters

workspace_id
string
required

The workspace id. A workspace the acting user is not an active member of answers 404, as do another workspace than an API key's own, a malformed id and a test environment's id. The workspace id, which is also its live environment's workspace id; the test environment's is the same id with:test appended. A workspace created through the API is tnt_ and a 26-character ULID.

Pattern: ^[A-Za-z0-9][A-Za-z0-9_.-]{0,122}$
environment
enum<string>
required

The environment: live or test. Each has its own settings. Any other value answers 400. An API key reads and changes only its own environment's; the other answers 404. The environment the key belongs to. A live key assesses with live sources; a test key answers from the deterministic simulator.

Available options:
live,
test
group_id
string
required
Pattern: ^grp_[0-7][0-9A-HJKMNP-TV-Z]{25}$
screening_id
string
required
Pattern: ^scn_[0-7][0-9A-HJKMNP-TV-Z]{25}$

Body

application/json

An empty object.

Response

The screening, cancelled, or as it finished when it already had.

A screening and its progress.

id
string
required
Pattern: ^scn_[0-7][0-9A-HJKMNP-TV-Z]{25}$
group_id
string
required
Pattern: ^grp_[0-7][0-9A-HJKMNP-TV-Z]{25}$
environment
enum<string>
required
Available options:
live,
test
status
enum<string>
required

partial finished with some people or platforms not covered; people_failed and people_partial count them.

Available options:
queued,
running,
completed,
partial,
failed,
cancelled
depth
enum<string>
required
Available options:
standard
platforms
enum<string>[]
required
Required array length: 1 - 11 elements

A platform a screening can cover. github and scratch through flickr are each one read of the public profile a handle names, with no posts. synthetic is the deterministic connector's own platform, for exercising the product end to end with no network.

Available options:
instagram,
x,
bluesky,
youtube,
tiktok,
facebook,
threads,
reddit,
telegram,
linkedin,
github,
scratch,
dailymotion,
substack,
duolingo,
dockerhub,
wikipedia,
internetarchive,
spotify,
patreon,
wordpress,
okru,
flickr,
synthetic
requested_by
string
required
Required string length: 1 - 256
created_at
string<date-time>
required
expires_at
string<date-time>
required

A screening still running then fails with error_code expired.

people_total
integer
required

People selected when the screening started.

Required range: 0 <= x <= 20000
people_done
integer
required

People screened so far, failed ones included.

Required range: 0 <= x <= 20000
people_flagged
integer
required
Required range: 0 <= x <= 20000
people_failed
integer
required
Required range: 0 <= x <= 20000
people_partial
integer
required

People screened with some requested platform not covered; their coverage names which.

Required range: 0 <= x <= 20000
estimated_spend
integer
required

What the screening was estimated to cost when it started, in minor units of USD (cents): its people at its depth and platforms. Until the screening finishes, what it has not yet spent counts against the environment's screening_daily_cap.

Required range: x >= 0
spent
integer
required

What the people it has screened recorded, in minor units of USD. Each counts toward the UTC day it was recorded on; a failed person records nothing.

Required range: x >= 0
spend
object
required

What every pass of the screening cost, by implementation: the people spent records, and also the people that failed and the passes retried, which record nothing toward spent.

started_at
string<date-time>
finished_at
string<date-time>
error_code
string

Why a failed or cancelled screening stopped.

Required string length: 1 - 64