Org nodes API

GET/v1/org-nodes

Returns the workspace's location tree, for example districts, regions, sites, and departments, with each location's path and member count. Every location in the workspace tree the caller may see (not paginated). Build the tree from parentId.

curl "https://api.brixsignage.com/v1/org-nodes" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200 Success.

{
  "data": [
    {
      "id": "on_4d5e6f7a8b9c0d1e",
      "name": "Chicago Loop",
      "parentId": "space_1a2b3c4d5e6f7a8b",
      "externalId": "STORE-0142",
      "timezone": "America/Chicago",
      "tier": 2,
      "isSpace": false,
      "payment": null,
      "paymentTrial": null,
      "screenCount": 6,
      "members": [
        {
          "userId": "usr_5e6f7a8b9c0d1e2f",
          "userName": "Sam Rivera",
          "roleId": "role_0a1b2c3d4e5f6a7b",
          "roleName": "Store manager",
          "roleColor": null,
          "source": null
        }
      ],
      "featureOverrides": [],
      "approval": {
        "required": false,
        "inheritFromParent": true,
        "escalateUpTiers": false,
        "allowSharedExemptions": false,
        "approvers": []
      },
      "billing": null,
      "prefs": {
        "location": {
          "label": "Chicago Loop",
          "lat": 41.8837,
          "lng": -87.6289
        },
        "language": null,
        "defaultContent": null
      }
    }
  ]
}

Response 401 Missing, expired or revoked bearer token.

Response 403 The token lacks the permission this operation needs (see `x-brix-permission`).

Response 5XX Server error. The body carries a `requestId` to quote to support.

POST/v1/org-nodes

Creates a new location under a parent location. Provide name, parentId, and an optional kind. To create many locations at once, use the bulk-create operation instead.

Request body application/json

curl -X POST "https://api.brixsignage.com/v1/org-nodes" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Chicago Loop","parentId":"on_0a1b2c3d4e5f6a7b","externalId":"STORE-0142","timezone":"America/Chicago"}'

Response 201 Success.

Response 401 Missing, expired or revoked bearer token.

Response 403 An owner-only field was set (`isSpace`, `billing`, `featureOverrides`, `tier`, `screenLimit`, or a non-inheriting approval policy).

Response 409 `location_id_taken`: another location already uses this `externalId`.

Response 422 `name` missing, invalid `externalId`, or `parentId` not found.

Response 5XX Server error. The body carries a `requestId` to quote to support.

GET/v1/org-nodes/{id}

Returns one location, including its path, parent, and settings.

curl "https://api.brixsignage.com/v1/org-nodes/{id}" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200 Success.

Response 401 Missing, expired or revoked bearer token.

Response 403 The token lacks the permission this operation needs (see `x-brix-permission`).

Response 404 No such location in this workspace.

Response 5XX Server error. The body carries a `requestId` to quote to support.

PATCH/v1/org-nodes/{id}

Updates a location's name, parent location, approval configuration, or preferences. Moving a location to a new parent updates the path of every location beneath it. Rename, re-code, move, or change inheritable settings. Only the fields sent change.

Request body application/json

curl -X PATCH "https://api.brixsignage.com/v1/org-nodes/{id}" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"

Response 200 Success.

Response 401 Missing, expired or revoked bearer token.

Response 403 Owner-only field, or a move you lack permission for at the destination.

Response 404 No such location in this workspace.

Response 409 `externalId` already used, or `approvalBase` no longer matches.

Response 422 Invalid field (a malformed `prefs`, moving a location under itself, unplayable default content).

Response 5XX Server error. The body carries a `requestId` to quote to support.

DELETE/v1/org-nodes/{id}

Soft-deletes a location. Everything at that location, including screens, content, folders and the people assigned there, moves to its parent location first, so nothing is left orphaned. Each person keeps their role, now at the parent location; if they already have that access there, the duplicate is dropped. Because a role at the parent applies to everything under it, you can only delete a location when you could give each of those roles at the parent yourself, and only an account owner can move an owner. People never move into another workspace: deleting a franchise workspace's top location removes the role assignments there. The root location and any location with active child locations cannot be deleted, and a deleted location cannot be restored. **Notes.** - Screens, content and people move to the parent location. Each person keeps their role, now at the parent, so it applies to everything under the parent. If they already have that access at the parent or above, the moved role assignment is dropped; otherwise they keep both. - Because the move widens where a role applies, you need to be able to give each moved role at the parent yourself. That includes your own role. - People never move into another workspace. Deleting a franchise workspace's top location removes the role assignments there. - A deleted location cannot be restored. The activity log records where each person was moved from.

curl -X DELETE "https://api.brixsignage.com/v1/org-nodes/{id}" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200 Success.

Response 401 Missing, expired or revoked bearer token.

Response 403 You do not hold `org-unit.delete` there; `owner_required`: an owner placed here would move up and you are not an owner at the parent (an API key never is); or `outranked`: a person placed here holds a permission you do not hold at the parent.

Response 404 No such location in this workspace.

Response 409 `protected` (the workspace root), `has_children` (move or delete the child locations first), or `last_owner` (deleting a franchise workspace's top location would remove the last owner).

Response 502 A franchise workspace's own subscription could not be ended; nothing was deleted.

Response 5XX Server error. The body carries a `requestId` to quote to support.

GET/v1/org-nodes/{id}/members

Returns the people directly assigned a role at this specific location, including the id of each role assignment. This id is needed to remove a membership, and is not included in the general roster listing. **Notes.** - Only the roles granted at this location, not those inherited from a parent.

curl "https://api.brixsignage.com/v1/org-nodes/{id}/members" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200 Success.

Response 401 Missing, expired or revoked bearer token.

Response 403 You do not hold `user.view` at this location.

Response 404 No such location in this workspace.

Response 5XX Server error. The body carries a `requestId` to quote to support.

POST/v1/org-nodes/{id}/members

Grants a person a role at this location. Provide userId and roleId. You cannot grant a role carrying permissions you do not hold yourself at that location. **Notes.** - The 201 body is the membership row as written.

Request body application/json

curl -X POST "https://api.brixsignage.com/v1/org-nodes/{id}/members" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"

Response 201 Success.

Response 401 Missing, expired or revoked bearer token.

Response 403 The role holds permissions you do not hold, or you cannot grant them at this location.

Response 404 No such location, person or role in this workspace.

Response 422 `userId` or `roleId` is missing.

Response 5XX Server error. The body carries a `requestId` to quote to support.

DELETE/v1/org-nodes/{id}/members/{memberId}

Removes one person's role assignment at this location. Only an account owner can remove the assignment of a person who is an owner at this location, and you cannot remove an assignment that carries a permission you do not hold here. An API key is never an owner. Refuses the request if it would leave the workspace without any account owner.

curl -X DELETE "https://api.brixsignage.com/v1/org-nodes/{id}/members/{memberId}" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200 Success.

Response 401 Missing, expired or revoked bearer token.

Response 403 You do not hold `user.edit` here, or the person outranks you (`owner_required`, `outranked`).

Response 404 No such location or membership.

Response 409 `last_owner`: this is the last owner of the workspace.

Response 5XX Server error. The body carries a `requestId` to quote to support.

POST/v1/org-nodes/{id}/payment/checkout

The card page for a location waiting on its payment: its payer's no-login page, created on first use with the caller's email. billing.edit AT the location. The one write auth() lets a person whose every seat is in that location make (402 payment_required elsewhere). 409 already_live once paid.

curl -X POST "https://api.brixsignage.com/v1/org-nodes/{id}/payment/checkout" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 4XX Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.

Response 5XX Server error. The body carries a `requestId` to quote to support.

POST/v1/org-nodes/{id}/payment/send

Corporate emails a location waiting on its payment its card page; email sets where the link and the invoices go. billing.edit at the workspace root. 409 already_live once paid. Audited.

curl -X POST "https://api.brixsignage.com/v1/org-nodes/{id}/payment/send" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 4XX Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.

Response 5XX Server error. The body carries a `requestId` to quote to support.

POST/v1/org-nodes/bulk

Creates up to 200 locations in a single call, for example to paste in a full location list at fleet setup. Send parentId and either a list of names or a list of units, each with a name and an optional time zone, town, Location ID and parent Location ID, so one list can hold regions and the stores under them. Empty or repeated names, and Location IDs already in use, are skipped, so the same list can safely be submitted again. Requires the create-location permission at the parent location. **Notes.** - Idempotent: sending the same list again creates nothing new and lists every row in skipped.

Request body application/json

curl -X POST "https://api.brixsignage.com/v1/org-nodes/bulk" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"parentId":"on_0a1b2c3d4e5f6a7b","units":[{"name":"Chicago Loop","timezone":"America/Chicago","externalId":"STORE-0142"}]}'

Response 201 Success.

Response 401 Missing, expired or revoked bearer token.

Response 403 You do not hold `org-unit.create` at the parent location.

Response 422 `parentId` missing or not found, no rows, more than 200 rows, an invalid Location ID or time zone, or a parent that is a separate workspace.

Response 5XX Server error. The body carries a `requestId` to quote to support.