Create a site

post/v1/sites

Creates a site with optional address, coordinates and multi-range operating times.

curl -X POST "https://api.vojo-media.com/v1/sites" \
  -H "Authorization: Bearer $VOJO_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Leeds Trinity",
  "address": {
    "street": "1 Market Street",
    "line_two": null,
    "city": "Leeds",
    "state": "West Yorkshire",
    "postal_code": "LS1 6DT",
    "country": "GB",
    "latitude": 53.7966,
    "longitude": -1.5432
  },
  "operating_times_enabled": true,
  "operating_times": {
    "monday": {
      "operational": true,
      "ranges": [
        {
          "start": "07:00",
          "end": "22:00"
        }
      ]
    },
    "tuesday": {
      "operational": true,
      "ranges": [
        {
          "start": "07:00",
          "end": "22:00"
        }
      ]
    },
    "wednesday": {
      "operational": true,
      "ranges": [
        {
          "start": "07:00",
          "end": "22:00"
        }
      ]
    },
    "thursday": {
      "operational": true,
      "ranges": [
        {
          "start": "07:00",
          "end": "22:00"
        }
      ]
    },
    "friday": {
      "operational": true,
      "ranges": [
        {
          "start": "07:00",
          "end": "22:00"
        }
      ]
    },
    "saturday": {
      "operational": true,
      "ranges": [
        {
          "start": "07:00",
          "end": "22:00"
        }
      ]
    },
    "sunday": {
      "operational": false,
      "ranges": []
    }
  }
}'

const { data, error } = await api.POST("/v1/sites", {
  params: { header: { "Idempotency-Key": crypto.randomUUID() } },
  body: {
    name: "Leeds Trinity",
    address: {
      street: "1 Market Street",
      line_two: null,
      city: "Leeds",
      state: "West Yorkshire",
      postal_code: "LS1 6DT",
      country: "GB",
      latitude: 53.7966,
      longitude: -1.5432,
    },
    operating_times_enabled: true,
    operating_times: {
      monday: {
        operational: true,
        ranges: [
          {
            start: "07:00",
            end: "22:00",
          },
        ],
      },
      tuesday: {
        operational: true,
        ranges: [
          {
            start: "07:00",
            end: "22:00",
          },
        ],
      },
      wednesday: {
        operational: true,
        ranges: [
          {
            start: "07:00",
            end: "22:00",
          },
        ],
      },
      thursday: {
        operational: true,
        ranges: [
          {
            start: "07:00",
            end: "22:00",
          },
        ],
      },
      friday: {
        operational: true,
        ranges: [
          {
            start: "07:00",
            end: "22:00",
          },
        ],
      },
      saturday: {
        operational: true,
        ranges: [
          {
            start: "07:00",
            end: "22:00",
          },
        ],
      },
      sunday: {
        operational: false,
        ranges: [],
      },
    },
  },
});
if (error) throw new VojoApiError(error);

Response 201

{
  "data": {
    "id": "cm1sit5r9j0001p3l7v2x8c4qd",
    "name": "Leeds Trinity",
    "address": {
      "street": "1 Market Street",
      "line_two": null,
      "city": "Leeds",
      "state": "West Yorkshire",
      "postal_code": "LS1 6DT",
      "country": "GB",
      "latitude": 53.7966,
      "longitude": -1.5432
    },
    "operating_times_enabled": true,
    "operating_times": {
      "monday": {
        "operational": true,
        "ranges": [
          {
            "start": "07:00",
            "end": "22:00"
          }
        ]
      },
      "tuesday": {
        "operational": true,
        "ranges": [
          {
            "start": "07:00",
            "end": "22:00"
          }
        ]
      },
      "wednesday": {
        "operational": true,
        "ranges": [
          {
            "start": "07:00",
            "end": "22:00"
          }
        ]
      },
      "thursday": {
        "operational": true,
        "ranges": [
          {
            "start": "07:00",
            "end": "22:00"
          }
        ]
      },
      "friday": {
        "operational": true,
        "ranges": [
          {
            "start": "07:00",
            "end": "22:00"
          }
        ]
      },
      "saturday": {
        "operational": true,
        "ranges": [
          {
            "start": "07:00",
            "end": "22:00"
          }
        ]
      },
      "sunday": {
        "operational": false,
        "ranges": []
      }
    },
    "created_at": "2025-04-11T12:00:00Z",
    "updated_at": "2026-10-07T09:30:00Z"
  },
  "meta": {}
}

Access

Authentication: Secret key or OAuth access token.
Scope: sites:write
User permission: sitesAddNew
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
addressobject
Address fields; all optional.
Show 8 fields
- streetstring or null
- line_twostring or null
- citystring or null
- statestring or null
- postal_codestring or null
- countrystring or null
  ISO 3166-1 alpha-2 preferred.
- latitudenumber or null
  -90 to 90
- longitudenumber or null
  -180 to 180
operating_times_enabledboolean
operating_timesobject
Weekly operating hours. Each day carries an array of open windows (multi-range).
Show 7 fields
- mondayobjectRequired
  Show 2 fields
  - operationalbooleanRequired
    False = closed all day.
  - rangesarray of objectsRequired
    Zero or more open windows. A day can have several (multi-range).
    Show 2 fields
    startstringRequired
    Opening time, 24-hour HH:MM.
    matches ^([01]\d|2[0-3]):[0-5]\d$
    endstringRequired
    Closing time, 24-hour HH:MM.
    matches ^([01]\d|2[0-3]):[0-5]\d$
- tuesdayobjectRequired
  Show 2 fields
  - operationalbooleanRequired
    False = closed all day.
  - rangesarray of objectsRequired
    Zero or more open windows. A day can have several (multi-range).
    Show 2 fields
    startstringRequired
    Opening time, 24-hour HH:MM.
    matches ^([01]\d|2[0-3]):[0-5]\d$
    endstringRequired
    Closing time, 24-hour HH:MM.
    matches ^([01]\d|2[0-3]):[0-5]\d$
- wednesdayobjectRequired
  Show 2 fields
  - operationalbooleanRequired
    False = closed all day.
  - rangesarray of objectsRequired
    Zero or more open windows. A day can have several (multi-range).
    Show 2 fields
    startstringRequired
    Opening time, 24-hour HH:MM.
    matches ^([01]\d|2[0-3]):[0-5]\d$
    endstringRequired
    Closing time, 24-hour HH:MM.
    matches ^([01]\d|2[0-3]):[0-5]\d$
- thursdayobjectRequired
  Show 2 fields
  - operationalbooleanRequired
    False = closed all day.
  - rangesarray of objectsRequired
    Zero or more open windows. A day can have several (multi-range).
    Show 2 fields
    startstringRequired
    Opening time, 24-hour HH:MM.
    matches ^([01]\d|2[0-3]):[0-5]\d$
    endstringRequired
    Closing time, 24-hour HH:MM.
    matches ^([01]\d|2[0-3]):[0-5]\d$
- fridayobjectRequired
  Show 2 fields
  - operationalbooleanRequired
    False = closed all day.
  - rangesarray of objectsRequired
    Zero or more open windows. A day can have several (multi-range).
    Show 2 fields
    startstringRequired
    Opening time, 24-hour HH:MM.
    matches ^([01]\d|2[0-3]):[0-5]\d$
    endstringRequired
    Closing time, 24-hour HH:MM.
    matches ^([01]\d|2[0-3]):[0-5]\d$
- saturdayobjectRequired
  Show 2 fields
  - operationalbooleanRequired
    False = closed all day.
  - rangesarray of objectsRequired
    Zero or more open windows. A day can have several (multi-range).
    Show 2 fields
    startstringRequired
    Opening time, 24-hour HH:MM.
    matches ^([01]\d|2[0-3]):[0-5]\d$
    endstringRequired
    Closing time, 24-hour HH:MM.
    matches ^([01]\d|2[0-3]):[0-5]\d$
- sundayobjectRequired
  Show 2 fields
  - operationalbooleanRequired
    False = closed all day.
  - rangesarray of objectsRequired
    Zero or more open windows. A day can have several (multi-range).
    Show 2 fields
    startstringRequired
    Opening time, 24-hour HH:MM.
    matches ^([01]\d|2[0-3]):[0-5]\d$
    endstringRequired
    Closing time, 24-hour HH:MM.
    matches ^([01]\d|2[0-3]):[0-5]\d$

Response 201

Created

dataobjectRequired
A physical location that contains screens.
Show 7 fields
- idstringRequired
  Site id. Opaque string — treat as an identifier, never parse it.
- namestringRequired
- addressobject or nullRequired
  Postal address and coordinates.
  Show 8 fields
  - streetstring or nullRequired
  - line_twostring or nullRequired
  - citystring or nullRequired
  - statestring or nullRequired
  - postal_codestring or nullRequired
  - countrystring or nullRequired
    ISO 3166-1 alpha-2 preferred.
  - latitudenumber or nullRequired
    -90 to 90
  - longitudenumber or nullRequired
    -180 to 180
- operating_times_enabledbooleanRequired
  Whether operating_times is enforced (screens outside hours are expected off).
- operating_timesobject or nullRequired
  Weekly operating hours. Each day carries an array of open windows (multi-range).
  Show 7 fields
  - mondayobjectRequired
    Show 2 fields
    operationalbooleanRequired
    False = closed all day.
    rangesarray of objectsRequired
    Zero or more open windows. A day can have several (multi-range).
    Show 2 fields
    startstringRequired
    Opening time, 24-hour HH:MM.
    matches ^([01]\d|2[0-3]):[0-5]\d$
    endstringRequired
    Closing time, 24-hour HH:MM.
    matches ^([01]\d|2[0-3]):[0-5]\d$
  - tuesdayobjectRequired
    Show 2 fields
    operationalbooleanRequired
    False = closed all day.
    rangesarray of objectsRequired
    Zero or more open windows. A day can have several (multi-range).
    Show 2 fields
    startstringRequired
    Opening time, 24-hour HH:MM.
    matches ^([01]\d|2[0-3]):[0-5]\d$
    endstringRequired
    Closing time, 24-hour HH:MM.
    matches ^([01]\d|2[0-3]):[0-5]\d$
  - wednesdayobjectRequired
    Show 2 fields
    operationalbooleanRequired
    False = closed all day.
    rangesarray of objectsRequired
    Zero or more open windows. A day can have several (multi-range).
    Show 2 fields
    startstringRequired
    Opening time, 24-hour HH:MM.
    matches ^([01]\d|2[0-3]):[0-5]\d$
    endstringRequired
    Closing time, 24-hour HH:MM.
    matches ^([01]\d|2[0-3]):[0-5]\d$
  - thursdayobjectRequired
    Show 2 fields
    operationalbooleanRequired
    False = closed all day.
    rangesarray of objectsRequired
    Zero or more open windows. A day can have several (multi-range).
    Show 2 fields
    startstringRequired
    Opening time, 24-hour HH:MM.
    matches ^([01]\d|2[0-3]):[0-5]\d$
    endstringRequired
    Closing time, 24-hour HH:MM.
    matches ^([01]\d|2[0-3]):[0-5]\d$
  - fridayobjectRequired
    Show 2 fields
    operationalbooleanRequired
    False = closed all day.
    rangesarray of objectsRequired
    Zero or more open windows. A day can have several (multi-range).
    Show 2 fields
    startstringRequired
    Opening time, 24-hour HH:MM.
    matches ^([01]\d|2[0-3]):[0-5]\d$
    endstringRequired
    Closing time, 24-hour HH:MM.
    matches ^([01]\d|2[0-3]):[0-5]\d$
  - saturdayobjectRequired
    Show 2 fields
    operationalbooleanRequired
    False = closed all day.
    rangesarray of objectsRequired
    Zero or more open windows. A day can have several (multi-range).
    Show 2 fields
    startstringRequired
    Opening time, 24-hour HH:MM.
    matches ^([01]\d|2[0-3]):[0-5]\d$
    endstringRequired
    Closing time, 24-hour HH:MM.
    matches ^([01]\d|2[0-3]):[0-5]\d$
  - sundayobjectRequired
    Show 2 fields
    operationalbooleanRequired
    False = closed all day.
    rangesarray of objectsRequired
    Zero or more open windows. A day can have several (multi-range).
    Show 2 fields
    startstringRequired
    Opening time, 24-hour HH:MM.
    matches ^([01]\d|2[0-3]):[0-5]\d$
    endstringRequired
    Closing time, 24-hour HH:MM.
    matches ^([01]\d|2[0-3]):[0-5]\d$
- 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).
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.