Create an organisation

post/v1/organisations

This endpoint is in the contract, but the API doesn't serve it during early access. It returns 404 for now.

Creates an organisation owned by the user in one transaction (Organisation, backing Client, an OWNER OrganisationAccess grant, optional Address) and makes it the user's default org. A duplicate name returns 409 duplicate_name. OAuth only; no org header.

curl -X POST "https://api.vojo-media.com/v1/organisations" \
  -H "Authorization: Bearer $VOJO_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Northwind Media",
  "email": "[email protected]",
  "billing_email": "[email protected]",
  "address": {
    "street": "1 Market Street",
    "line_two": null,
    "city": "Leeds",
    "state": "West Yorkshire",
    "postal_code": "LS1 6DT",
    "country": "GB"
  }
}'

const { data, error } = await api.POST("/v1/organisations", {
  params: { header: { "Idempotency-Key": crypto.randomUUID() } },
  body: {
    name: "Northwind Media",
    email: "[email protected]",
    billing_email: "[email protected]",
    address: {
      street: "1 Market Street",
      line_two: null,
      city: "Leeds",
      state: "West Yorkshire",
      postal_code: "LS1 6DT",
      country: "GB",
    },
  },
});
if (error) throw new VojoApiError(error);

Response 201

{
  "data": {
    "id": "cm1org8k2q0001x7v3n9p4d2fa",
    "name": "Northwind Media",
    "email": "[email protected]",
    "is_active": true,
    "api_version": "2026-10-07",
    "created_at": "2025-03-02T10:00:00Z"
  },
  "meta": {}
}

Access

Authentication: OAuth access token only. Secret keys are rejected.
Scope: account:write
User permission: Membership of the organisation is enough.
Safe to retry: Send an Idempotency-Key.

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

namestringRequired
Unique across Vojo; a clash returns 409 duplicate_name.
1 to 120 characters
emailstringRequired
Contact email.
email
billing_emailstringRequired
Billing contact email.
email
categorystring
up to 120 characters
addressobject
Optional head-office address.
Show 6 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.

Response 201

Created

dataobjectRequired
An organisation (tenant).
Show 6 fields
- idstringRequired
  Organisation id. Opaque string — treat as an identifier, never parse it.
- namestringRequired
- emailstringRequired
  Contact email.
  email
- is_activebooleanRequired
- api_versionstring or nullRequired
  Default API version pin for this org (date), used when neither the key nor the request pins one.
  date
- created_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.