Create a screen

post/v1/screens

Creates a screen. site_id and harvester_id (optional) must belong to the org and the harvester must be unassigned (409 harvester_already_assigned). A duplicate name returns 409 duplicate_name. Send screen_size_range_id, or size_inches and let the server pick the band.

Linking fields need the same permission as their own sub-resource, in addition to networkAddNew: sending site_id also requires sitesAssignScreen (as PUT /v1/screens/{screen_id}/site), and sending harvester_id also requires networkUpdateHarvester (as PUT /v1/screens/{screen_id}/harvester). Without it the request fails with 403 permission_denied and nothing is created.

curl -X POST "https://api.vojo-media.com/v1/screens" \
  -H "Authorization: Bearer $VOJO_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Lobby North",
  "brand": "iiyama",
  "model": "LH5560UHS",
  "condition": "new",
  "screen_size_range_id": "cm1ssr1a5e0001t7y3u9i2o6pj",
  "orientation": "portrait",
  "screen_24_hour": false,
  "harvester_screen_location": "top_right",
  "site_id": "cm1sit5r9j0001p3l7v2x8c4qd"
}'

const { data, error } = await api.POST("/v1/screens", {
  params: { header: { "Idempotency-Key": crypto.randomUUID() } },
  body: {
    name: "Lobby North",
    brand: "iiyama",
    model: "LH5560UHS",
    condition: "new",
    screen_size_range_id: "cm1ssr1a5e0001t7y3u9i2o6pj",
    orientation: "portrait",
    screen_24_hour: false,
    harvester_screen_location: "top_right",
    site_id: "cm1sit5r9j0001p3l7v2x8c4qd",
  },
});
if (error) throw new VojoApiError(error);

Response 201

{
  "data": {
    "id": "cm1scr2w6n0001h8d4k9t3m7ve",
    "name": "Lobby North",
    "brand": "iiyama",
    "model": "LH5560UHS",
    "condition": "new",
    "notes": null,
    "orientation": "portrait",
    "screen_24_hour": false,
    "harvester_screen_location": "top_right",
    "size_range": {
      "id": "cm1ssr1a5e0001t7y3u9i2o6pj",
      "label": "50–59 in",
      "min_inches": 50,
      "max_inches": 59
    },
    "last_evidence_at": "2026-10-07T09:29:41Z",
    "quality_bad": false,
    "site": {
      "id": "cm1sit5r9j0001p3l7v2x8c4qd",
      "name": "Leeds Trinity",
      "latitude": 53.7966,
      "longitude": -1.5432
    },
    "harvester": {
      "id": "cm1hrv7c3b0001q9z5l2n8x4tg",
      "mac_address": "D8:3A:DD:41:7C:02"
    },
    "created_at": "2025-04-11T12:30:00Z",
    "updated_at": "2026-10-07T09:30:00Z"
  },
  "meta": {}
}

Access

Authentication: Secret key or OAuth access token.
Scope: screens:write
User permission: networkAddNew
Sending site_id: Also needs sitesAssignScreen
Sending harvester_id: Also needs networkUpdateHarvester
Safe to retry: Send an Idempotency-Key.

Headers

Vojo-Organisationstring
The organisation this request acts on (org id). Required for oauth2 callers — a missing header returns 400 organisation_header_required; an org the user cannot access (a membership or an access grant, and granted to this OAuth client) returns 403 organisation_access_denied. Secret keys are bound to one org: the header may be omitted, and if sent it must match the key's org (else 403). Every query is scoped by the resolved org, never by an id in the body.
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

namestringRequired
1 to 120 characters
brandstring or null
up to 120 characters
modelstring or null
up to 120 characters
conditionstring or null
up to 60 characters
notesstring or null
up to 2000 characters
screen_size_range_idstring
Size band id from GET /v1/screen-size-ranges.
size_inchesnumber
Convenience alternative to screen_size_range_id: the server maps the diagonal to a size band. Send one or the other.
more than 0
orientationstring
Physical orientation of the display.
One of landscape, portrait
screen_24_hourboolean
harvester_screen_locationstring
Corner of the screen the harvester sensor is mounted on.
One of top_left, top_right, bottom_left, bottom_right
site_idstring
Assign to this site (must belong to the org).
harvester_idstring
Pair this unassigned harvester (must belong to the org).

Response 201

Created

dataobjectRequired
A physical display. status and verification are derived server-side.
Show 16 fields
- idstringRequired
  Screen id. Opaque string — treat as an identifier, never parse it.
- namestringRequired
  Unique within the org.
- brandstring or nullRequired
- modelstring or nullRequired
- conditionstring or nullRequired
- notesstring or nullRequired
- orientationstringRequired
  Physical orientation of the display.
  One of landscape, portrait
- screen_24_hourbooleanRequired
  True when the screen runs 24 hours and ignores site operating times.
- harvester_screen_locationstring or nullRequired
  Corner of the screen the harvester sensor is mounted on.
  One of top_left, top_right, bottom_left, bottom_right
- size_rangeobject or nullRequired
  Global reference data: a diagonal size band used for fingerprint geometry.
  Show 4 fields
  - idstringRequired
    Screen size range id. Opaque string — treat as an identifier, never parse it.
  - labelstringRequired
    Display label.
  - min_inchesnumberRequired
  - max_inchesnumber or nullRequired
    Null for the open-ended top range.
- last_evidence_atstring or nullRequired
  The reported time of the newest Passport or Harvester event in this screen's latest play; null if there isn't one. A fact, not a status — Vojo does not say whether a screen is on, off or working. Draw your own conclusion.
  date-time
- quality_badbooleanRequired
  The harvester currently reports a quality problem.
- siteobject or nullRequired
  The site the screen is assigned to, or null.
  Show 4 fields
  - idstringRequired
    Site id. Opaque string — treat as an identifier, never parse it.
  - namestringRequired
  - latitudenumber or nullRequired
  - longitudenumber or nullRequired
- harvesterobject or nullRequired
  Paired harvester, or null.
  Show 2 fields
  - idstringRequired
    Harvester id. Opaque string — treat as an identifier, never parse it.
  - mac_addressstringRequired
- created_atstringRequired
  RFC 3339 / ISO-8601 UTC timestamp.
  date-time
- updated_atstring or nullRequired
  RFC 3339 / ISO-8601 UTC timestamp, or null.
  date-time
metaobjectRequired
Response metadata for single-resource responses. Reserved; currently empty. Clients must ignore unknown members.

Response headers

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.
Locationstring
URL of the created resource.
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.

400
Malformed request: invalid JSON, a bad cursor, a missing Vojo-Organisation for an OAuth caller, or an unknown Vojo-Version.
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.
409
The request conflicts with current state (duplicate name, device already paired, idempotency key reuse).
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.