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-Versionstring

    Optional API version pin (a date). Overrides the version pinned on the secret key / organisation for this request. Echoed in the Vojo-Version response header. Within /v1 only additive changes ship, so most callers can omit it.

    date

  • Idempotency-Keystring

    Client-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 409 idempotency_key_reused.

    8 to 255 characters

Request body

  • typestringRequired

    One of calibration, quality_good, quality_bad, screen_off, screen_on

Response 202

Accepted — the event is sent in the background.

  • dataobjectRequired
    Show 8 fields
    • idstringRequired

      Prefixed tsev_.

    • typestringRequired

      One of calibration, quality_good, quality_bad, screen_off, screen_on

    • statusstringRequired

      One of queued, sending, sent, failed

    • screen_idstringRequired
    • failureobject or nullRequired
      Show 2 fields
      • codestringRequired

        One of simulation_unavailable, evidence_rejected, expired

      • messagestringRequired
    • created_atstringRequired

      date-time

    • sent_atstring or nullRequired

      date-time

    • livemodeboolean

      Always false.

  • metaobjectRequired

Response headers

  • Locationstring

    URL of the test screen event to poll.

  • Vojo-Versionstring

    The API version (date) this response was rendered with — the request's Vojo-Version, else the key/org pin.

  • RateLimitstring

    IETF RateLimit header: remaining quota in the current window, e.g. "default";r=97;t=42.

  • RateLimit-Policystring

    IETF RateLimit-Policy header, e.g. "default";q=100;w=60. Portal OAuth clients get a higher tier.

  • Idempotent-Replayedstring

    true when this response is a stored replay of an earlier request with the same Idempotency-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-After seconds.

  • 500

    Unexpected server failure.