Org nodes API

GET /v1/org-nodes

Auth: Bearer token. Permission: org-unit.view.

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

Auth: Bearer token. Permission: org-unit.create.

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}

Auth: Bearer token. Permission: org-unit.view.

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}

Auth: Bearer token. Permission: org-unit.edit.

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}

Auth: Bearer token. Permission: org-unit.delete.

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

Auth: Bearer token. Permission: user.view.

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

Auth: Bearer token. Permission: user.edit.

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.

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

Auth: Bearer token. Permission: user.edit.

Changes the role of one person's role assignment at this location. Provide roleId. The location stays the same. You must be allowed to remove the old role and to grant the new one at this location: only an account owner can change an owner, and you cannot give or take away a permission you do not hold here. Refuses the request if it would leave the workspace without any account owner. Notes. - The location of the assignment does not change. To give access at another location, add a role assignment there.

Request body: application/json

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

Response 200: Success.

Response 401: Missing, expired or revoked bearer token.

Response 403: You do not hold user.edit here, the person outranks you (owner_required, outranked), or the new role holds permissions you cannot grant at this location.

Response 404: No such location, membership or role.

Response 409: last_owner: this is the last owner of the workspace. duplicate: the person already has this role here.

Response 422: roleId is missing.

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

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

Auth: Bearer token. Permission: user.edit.

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

Auth: Bearer token.

Get the link to the card page for a location that pays for its own screens and has not paid yet. Requires billing.edit at that location, so the location’s owner can pay without access to the rest of the account; invoices go to the caller’s email. Returns 409 already_live when the location is already live.

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

Auth: Bearer token.

Email a location that is awaiting payment the link to its card page. Optionally send { email } to set where the link and future invoices go. Requires billing.edit on the whole account; an API key also needs the location-payment.edit scope. Returns the link and who it was sent to, or 409 already_live when the location is already live.

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

Auth: Bearer token. Permission: org-unit.create.

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.