Make a simulated screen do something
post/v1/test_helpers/screens/{screen_id}/events
Has a simulated screen's Harvester report an event, exactly as a real one would, so the real pipeline produces its effects and webhooks:
| type | what the Harvester sends | what follows |
|---|---|---|
calibration |
a calibration-complete colour reading | a new baseline; screen.calibrated |
quality_good |
colour readings matching the baseline | screen.quality with every channel GOOD |
quality_bad |
readings well below the baseline | screen.quality with channels BAD |
screen_off |
the screen switching off | later plays on it read SCREEN_OFF |
screen_on |
the screen switching on | plays on it are scored normally again |
A quality event on a screen with no baseline calibrates it first (so
screen.calibrated comes too). As on a real screen, screen.quality
fires at most once per screen per 10 minutes: a second quality event
sooner than that is folded into the next one. Returns at once with a
test_screen_event (status: queued); it is sent within seconds.
Access
- Authentication
- Secret key or OAuth access token.
- Scope
test_helpers:write- User permission
developerAccess- Safe to retry
- Send an Idempotency-Key.
Path parameters
screen_idstringRequired
Headers
Vojo-VersionstringOptional API version pin (a date). Overrides the version pinned on the secret key / organisation for this request. Echoed in the
Vojo-Versionresponse header. Within/v1only additive changes ship, so most callers can omit it.Idempotency-KeystringClient-generated unique key (UUID v4 recommended) making this create safe to retry. A replay within 24 hours returns the stored response (with
Idempotent-Replayed: true). Reusing a key with a different body returns 409idempotency_key_reused.
Request body
typestringRequired
Response 202
Accepted — the event is sent in the background.
dataobjectRequiredShow 8 fields
idstringRequiredPrefixed
tsev_.typestringRequiredstatusstringRequiredscreen_idstringRequiredfailureobject or nullRequiredShow 2 fields
codestringRequiredmessagestringRequired
created_atstringRequiredsent_atstring or nullRequiredlivemodebooleanAlways false.
metaobjectRequired
Response headers
LocationstringURL of the test screen event to poll.
Vojo-VersionstringThe API version (date) this response was rendered with — the request's
Vojo-Version, else the key/org pin.RateLimitstringIETF RateLimit header: remaining quota in the current window, e.g.
"default";r=97;t=42.RateLimit-PolicystringIETF RateLimit-Policy header, e.g.
"default";q=100;w=60. Portal OAuth clients get a higher tier.Idempotent-Replayedstringtruewhen this response is a stored replay of an earlier request with the sameIdempotency-Key.
Errors
Every error is application/problem+json. Branch on its code.
- 401
Missing, invalid, expired or revoked credential.
- 403
The caller is authenticated but not allowed: missing scope (
insufficient_scope), missing Permissions flag (permission_denied), a client/installer persona on an operator endpoint (operator_access_required), or no access to the requested org (organisation_access_denied). - 404
The resource does not exist, or belongs to another organisation. Cross-org ids always 404, never 403.
- 422
Well-formed request that failed validation.
errors[]lists each failing field. - 429
Rate limit exceeded for this principal. Back off for
Retry-Afterseconds. - 500
Unexpected server failure.