{ "openapi": "3.0.3", "info": { "title": "Bramble Admin Centre API", "version": "2026-11-13", "description": "The Admin Centre API is everything an organisation's admins can do in the Admin Centre: people, groups, roles and licences; sign-in security; single sign-on apps; branding and domains; guests and portal users; the audit log; and each app's admin settings. All of it lives in BRM-API under `/api/v1/admin/...` and works with an API key belonging to an admin.\n" }, "servers": [ { "url": "https://{org}.brambleit.cloud/api", "variables": { "org": { "default": "your-org" } } }, { "url": "https://{org}.brambleit.cloud/admin", "variables": { "org": { "default": "your-org" } } } ], "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "session": { "type": "apiKey", "in": "cookie", "name": "sso_session" }, "bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } } }, "tags": [ { "name": "Organisation", "description": "The organisation itself: its record, name and type (MSP or company), whether Bramble support may access it, and what the signed-in admin is allowed to manage.\n" }, { "name": "People", "description": "Staff accounts: create, edit, turn off and delete people; their username and email aliases, mailbox, groups, roles and licences; reset passwords and two-step sign-in; sign someone out everywhere. A person's username is their email address on one of the organisation's verified domains.\n" }, { "name": "Groups", "description": "Groups of people. Groups are used to give access (apps, sites, PSA queues, single sign-on apps, security policies) to many people at once.\n" }, { "name": "Roles & permissions", "description": "Roles bundle permissions. Built-in roles (Global Administrator, RMM Technician, PSA Admin…) can't be changed; organisations can create custom roles from the permission catalogue and give them to people.\n" }, { "name": "Licences", "description": "The licence packages the organisation has, how many seats are used, and which licensed apps the organisation actually uses (which decides what shows in the launcher). Assign a licence to a person with `PATCH /v1/admin/user/licenses`.\n" }, { "name": "Domains", "description": "Email domains. A domain is added, then verified by publishing a DNS TXT record; only verified domains can be used for usernames and mailboxes. Bramble checks verified domains again later and marks them \"verification lost\" if the record disappears.\n" }, { "name": "Security policies", "description": "Conditional access. A policy either **requires two-step sign-in** or **blocks sign-in**, for everyone or for chosen people and groups, optionally only from (or except from) named locations — lists of countries and IP ranges. Also the session length (how long people stay signed in).\n" }, { "name": "Sign-ins & sessions", "description": "Every sign-in attempt (success, failure, interrupted for two-step sign-in) with where it came from, and the sessions currently signed in. Revoke a session to sign that device out.\n" }, { "name": "Audit log", "description": "Who changed what, when. `audit-events` is the detailed trail (each change with its modified properties, before and after) with filters and CSV export; `audit-log` is the older request log.\n" }, { "name": "Single sign-on apps", "description": "\"Sign in with Bramble\" for other applications (OpenID Connect). Register an app to get its client ID and secret, choose who may use it, and optionally show it in the app launcher. Bramble's own platform apps can be switched on or off for the organisation.\n" }, { "name": "Branding & launcher", "description": "The organisation's colours, logo, sign-in page background and wording, and custom links added to everyone's app launcher.\n" }, { "name": "Guests & portal users", "description": "Guests are people from outside the organisation invited by email (for example to a site or a shared file). Portal users are PSA contacts given a client-portal sign-in.\n" }, { "name": "Partners", "description": "MSP partnerships. A partner (MSP) asks to manage this organisation; the organisation approves it and chooses what the partner may do: `devices.read` (see devices in the partner's RMM), `device_management.manage` (manage device policies) and `admin.full` (delegated admin of the Admin Centre). Either side can end it.\n" }, { "name": "Storage", "description": "The organisation's storage pool: how much each app and person uses, per-app limits, and Drive settings.\n" }, { "name": "Delete the organisation", "description": "Permanently deleting the organisation is a three-step process: **request** (type the organisation's name), **confirm** from the link emailed to the admin, then a grace period during which it can be **cancelled**. After the grace period every app's data is purged. The preview shows what would go.\n" }, { "name": "App settings: PSA", "description": "PSA administration: queues and their mailboxes, statuses, ticket types, categories, SLA policies, workflows, email templates, procedures and approvals.\n" }, { "name": "App settings: Forms", "description": "Every form in the organisation, with admin overrides for owners and collaborators." }, { "name": "App settings: Sites", "description": "Every site in the organisation, its members, and who may create sites." }, { "name": "App settings: Mail", "description": "Mail domains (set up and check DNS), every mailbox, shared mailboxes and their members (full access, send as, send on behalf), and app passwords for accounts that never sign in interactively (a scanner, Paper's intake).\n" }, { "name": "App settings: HR", "description": "HR policy (leave year, allowances, carry-over, half days), leave types, company closures, checklist templates, who is in HR, removed people, and each person's HR record including dated allowance changes.\n" }, { "name": "App settings: SimpleBooks", "description": "Companies, who can access each company and with what role, and the receipts email address." }, { "name": "App settings: Warden", "description": "Warden administration: overview, network device integrations (UniFi), SIEM (Logs & auditing) collection, general settings, ticket and notification rules, and connectors.\n" }, { "name": "RMM: checks & alerts", "description": "Checks watch devices and raise alerts: CPU, memory and disk, stopped services, offline devices, containers, Proxmox and backup health, HTTP/TCP/ping, network devices and interfaces, database and device backups. Each check has a severity, the devices it applies to (assignments), and actions to take when it fires (notify a channel).\n" }, { "name": "RMM: scripts", "description": "The script library and its categories. Scripts run on devices directly or as steps of a task." }, { "name": "RMM: scheduled tasks", "description": "Tasks run one or more scripts on a schedule (every N hours, daily, weekly, a day of the month, or the Nth weekday of the month) on the devices they're assigned to. Each run records a result per device and per step.\n" }, { "name": "RMM: sites, groups & enrolment", "description": "Sites and groups organise devices. Enrolment keys add devices: each key puts new devices into a site and group. Anyone holding a key can add a device, so keep keys private and delete unused ones.\n" }, { "name": "RMM: device management", "description": "Device management (MDM) for Linux devices: configuration profiles and baselines, and which devices, sites or groups they apply to. MSP technicians can manage a customer's policies with `?tenant=` when the partnership allows it.\n" }, { "name": "RMM: agent updates", "description": "Automatic agent updates, how long RMM history is kept (utilisation, commands, logs), and hypervisor summaries.\n" } ], "paths": { "/v1/admin/isadmin": { "get": { "tags": [ "Organisation" ], "summary": "Can the caller use the Admin Centre?", "operationId": "get-v1-admin-isadmin", "description": "Returns whether the signed-in person can open the Admin Centre and which sections their roles unlock. Use it to check an API key's reach.\n\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`).", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "403": { "description": "Insufficient permissions" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/info": { "get": { "tags": [ "Organisation" ], "summary": "Get the organisation", "operationId": "get-v1-admin-tenant-info", "description": "Get the caller's tenant record. Requires the GLOBAL_ADMIN role. Returns the full tenants row (SELECT *) for the caller's own tenant.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant": {} } } } } }, "404": { "description": "Tenant not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/session-policy": { "patch": { "tags": [ "Security policies" ], "summary": "Set how long people stay signed in", "operationId": "patch-v1-admin-tenant-session-policy", "description": "Set the tenant's login session TTL. Requires the GLOBAL_ADMIN role. session_ttl_days must be an integer between 1 and 90, or null/empty to reset to the platform default (7 days).\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "session_ttl_days": { "type": "integer" } } } } } }, "400": { "description": "session_ttl_days must be an integer between 1 and 90, or null for the platform default" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "session_ttl_days": { "type": "integer", "description": "Days a sign-in lasts, 1–90. `null` uses the platform default (7)." } } } } } } } }, "/v1/admin/tenant/support-access": { "patch": { "tags": [ "Organisation" ], "summary": "Allow or stop Bramble support access", "operationId": "patch-v1-admin-tenant-support-access", "description": "Allow or stop Bramble support access to this tenant. \"Requires the GLOBAL_ADMIN role. Body: enabled (boolean).\"\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "support_access": { "type": "boolean" } } } } } }, "400": { "description": "enabled must be true or false" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "`true` lets Bramble support sign in to help; `false` stops it." } } } } } } } }, "/v1/admin/tenant/name": { "patch": { "tags": [ "Organisation" ], "summary": "Rename the organisation", "operationId": "patch-v1-admin-tenant-name", "description": "Set the tenant's organisation name. Requires the GLOBAL_ADMIN role. name is required, max 100 characters.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "name": { "type": "string" } } } } } }, "400": { "description": "Organisation name is required" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The organisation's name, up to 100 characters." } } } } } } } }, "/v1/admin/tenant/security-policies": { "get": { "tags": [ "Security policies" ], "summary": "List the tenant's Conditional Access-style security policies", "operationId": "get-v1-admin-tenant-security-policies", "description": "List the tenant's Conditional Access-style security policies. Requires the GLOBAL_ADMIN role. Each policy includes its include/exclude subjects (users/groups) and named-location conditions.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "policies": { "type": "array", "items": {} } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "post": { "tags": [ "Security policies" ], "summary": "Create a security policy", "operationId": "post-v1-admin-tenant-security-policies", "description": "Create a security policy. Requires the GLOBAL_ADMIN role. control must be require_mfa or block; target_scope must be all or specific.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "id": { "type": "integer" } } } } } }, "400": { "description": "name is required" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "A name admins will recognise." }, "description": { "type": "string", "description": "Optional notes." }, "control": { "type": "string", "enum": [ "require_mfa", "block" ], "description": "`require_mfa` asks for two-step sign-in; `block` refuses the sign-in." }, "target_scope": { "enum": [ "all", "specific" ], "description": "`all` applies to everyone; `specific` only to the people and groups added as subjects." }, "applies_to_user_types": { "type": "array", "items": {}, "description": "Which kinds of account it covers, e.g. `[\"staff\", \"guest\"]`." } }, "required": [ "name" ] } } } } } }, "/v1/admin/tenant/security-policies/{id}": { "patch": { "tags": [ "Security policies" ], "summary": "Update a security policy", "operationId": "patch-v1-admin-tenant-security-policies-id", "description": "Update a security policy. Requires the GLOBAL_ADMIN role. All fields optional; omitted fields keep their existing value.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "400": { "description": "control must be 'require_mfa' or 'block'" }, "404": { "description": "Policy not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "enabled": { "type": "boolean" }, "control": { "type": "string", "enum": [ "require_mfa", "block" ] }, "target_scope": { "type": "string", "enum": [ "all", "specific" ] }, "applies_to_user_types": { "type": "array", "items": {} } } } } } } }, "delete": { "tags": [ "Security policies" ], "summary": "Delete a security policy", "operationId": "delete-v1-admin-tenant-security-policies-id", "description": "Delete a security policy. Requires the GLOBAL_ADMIN role. Cascades to the policy's subject and location rows in a transaction.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "404": { "description": "Policy not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/security-policies/{id}/subjects": { "post": { "tags": [ "Security policies" ], "summary": "Add an include/exclude subject (user or group) to a security policy", "operationId": "post-v1-admin-tenant-security-policies-id-subjects", "description": "Add an include/exclude subject (user or group) to a security policy. Requires the GLOBAL_ADMIN role. Validates that the subject belongs to the caller's tenant before adding it.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "400": { "description": "mode must be 'include' or 'exclude'" }, "404": { "description": "Policy not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "include", "exclude" ], "description": "`include` applies the policy to them; `exclude` exempts them." }, "subject_type": { "type": "string", "enum": [ "user", "group" ], "description": "`user` or `group`." }, "subject_id": { "type": "integer", "description": "The person's or group's id." } }, "required": [ "subject_id" ] } } } } } }, "/v1/admin/tenant/security-policies/{id}/subjects/{subjectRowId}": { "delete": { "tags": [ "Security policies" ], "summary": "Remove a subject entry from a security policy", "operationId": "delete-v1-admin-tenant-security-policies-id-subjects-subjectrowid", "description": "Remove a subject entry from a security policy. Requires the GLOBAL_ADMIN role.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "subjectRowId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "404": { "description": "Policy not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/security-policies/{id}/locations": { "post": { "tags": [ "Security policies" ], "summary": "Add an include/exclude named-location condition to a security policy", "operationId": "post-v1-admin-tenant-security-policies-id-locations", "description": "Add an include/exclude named-location condition to a security policy. Requires the GLOBAL_ADMIN role. Validates the named location belongs to the caller's tenant.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "400": { "description": "mode must be 'include' or 'exclude'" }, "404": { "description": "Policy not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "include", "exclude" ], "description": "`include`: only sign-ins from this location; `exclude`: everywhere except it." }, "named_location_id": { "type": "integer", "description": "A named location's id." } }, "required": [ "named_location_id" ] } } } } } }, "/v1/admin/tenant/security-policies/{id}/locations/{locationRowId}": { "delete": { "tags": [ "Security policies" ], "summary": "Remove a location condition from a security policy", "operationId": "delete-v1-admin-tenant-security-policies-id-locations-locationrowid", "description": "Remove a location condition from a security policy. Requires the GLOBAL_ADMIN role.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "locationRowId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "404": { "description": "Policy not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/named-locations": { "get": { "tags": [ "Security policies" ], "summary": "List the tenant's named locations", "operationId": "get-v1-admin-tenant-named-locations", "description": "List the tenant's named locations. Requires the GLOBAL_ADMIN role. Each location includes its country/CIDR match entries.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "locations": { "type": "array", "items": {} } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "post": { "tags": [ "Security policies" ], "summary": "Create a named location", "operationId": "post-v1-admin-tenant-named-locations", "description": "Create a named location. Requires the GLOBAL_ADMIN role. name is required.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "id": { "type": "integer" } } } } } }, "400": { "description": "name is required" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } }, "required": [ "name" ] } } } } } }, "/v1/admin/tenant/named-locations/{id}": { "patch": { "tags": [ "Security policies" ], "summary": "Rename/update a named location", "operationId": "patch-v1-admin-tenant-named-locations-id", "description": "Rename/update a named location. Requires the GLOBAL_ADMIN role. name is required.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "400": { "description": "name is required" }, "404": { "description": "Named location not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } }, "required": [ "name" ] } } } } }, "delete": { "tags": [ "Security policies" ], "summary": "Delete a named location", "operationId": "delete-v1-admin-tenant-named-locations-id", "description": "Delete a named location. Requires the GLOBAL_ADMIN role. Cascades — any security policy referencing this location loses that condition, and the location's match entries are deleted too.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "404": { "description": "Named location not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/named-locations/{id}/entries": { "post": { "tags": [ "Security policies" ], "summary": "Add a country or CIDR match entry to a named location", "operationId": "post-v1-admin-tenant-named-locations-id-entries", "description": "Add a country or CIDR match entry to a named location. Requires the GLOBAL_ADMIN role. match_type=country requires a 2-letter ISO code; match_type=cidr requires a CIDR range e.g. 203.0.113.0/24.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "400": { "description": "match_type must be 'country' or 'cidr'" }, "404": { "description": "Named location not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "match_type": { "type": "string", "enum": [ "country", "cidr" ], "description": "`country` or `cidr`." }, "value": { "type": "string", "description": "A two-letter country code (`GB`) or an IP range (`203.0.113.0/24`)." } } } } } } } }, "/v1/admin/tenant/named-locations/{id}/entries/{entryId}": { "delete": { "tags": [ "Security policies" ], "summary": "Remove a match entry from a named location", "operationId": "delete-v1-admin-tenant-named-locations-id-entries-entryid", "description": "Remove a match entry from a named location. Requires the GLOBAL_ADMIN role.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "entryId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "404": { "description": "Named location not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/users": { "get": { "tags": [ "People" ], "summary": "List people", "operationId": "get-v1-admin-tenant-users", "description": "Every staff account in the organisation, with their roles.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "users": { "type": "array", "items": {} } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/domains": { "get": { "tags": [ "Domains" ], "summary": "List the tenant's verified/pending domains", "operationId": "get-v1-admin-tenant-domains", "description": "List the tenant's verified/pending domains. Requires the GLOBAL_ADMIN role.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "domains": { "type": "array", "items": {} } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "delete": { "tags": [ "Domains" ], "summary": "Remove a domain", "operationId": "delete-v1-admin-tenant-domains", "description": "Remove a tenant domain. Requires the GLOBAL_ADMIN role. System domains (domain_status=2) cannot be removed.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "400": { "description": "domain_id is required" }, "403": { "description": "System domains cannot be removed" }, "404": { "description": "Domain not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/groups": { "get": { "tags": [ "Groups" ], "summary": "List the tenant's groups with member counts", "operationId": "get-v1-admin-tenant-groups", "description": "List the tenant's groups with member counts. Requires the GLOBAL_ADMIN role.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "groups": { "type": "array", "items": {} } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "post": { "tags": [ "Groups" ], "summary": "Create a group. Requires the GLOBAL_ADMIN role", "operationId": "post-v1-admin-tenant-groups", "description": "Create a group. Requires the GLOBAL_ADMIN role. group_name is required.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "group": { "type": "object", "properties": { "id": { "type": "integer" }, "group_name": { "type": "string" } } } } } } } }, "400": { "description": "Group name is required" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "group_name": { "type": "string", "description": "The group's name." } }, "required": [ "group_name" ] } } } } } }, "/v1/admin/tenant/groups/{id}": { "get": { "tags": [ "Groups" ], "summary": "Get a group and its members", "operationId": "get-v1-admin-tenant-groups-id", "description": "Get a group and its members. Requires the GLOBAL_ADMIN role.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "group": {}, "members": { "type": "array", "items": {} } } } } } }, "404": { "description": "Group not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "patch": { "tags": [ "Groups" ], "summary": "Rename a group. Requires the GLOBAL_ADMIN role", "operationId": "patch-v1-admin-tenant-groups-id", "description": "Rename a group. Requires the GLOBAL_ADMIN role. group_name is required.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "400": { "description": "Group name is required" }, "404": { "description": "Group not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "group_name": { "type": "string" } }, "required": [ "group_name" ] } } } } }, "delete": { "tags": [ "Groups" ], "summary": "Delete a group. Requires the GLOBAL_ADMIN role", "operationId": "delete-v1-admin-tenant-groups-id", "description": "Delete a group. Requires the GLOBAL_ADMIN role. Cascades to the group's membership rows in a transaction.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "404": { "description": "Group not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/groups/{id}/members": { "post": { "tags": [ "Groups" ], "summary": "Add a user to a group", "operationId": "post-v1-admin-tenant-groups-id-members", "description": "Add a user to a group. Requires the GLOBAL_ADMIN role. Validates the user belongs to the caller's tenant; uses INSERT IGNORE so re-adding an existing member is a no-op.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "400": { "description": "user_id is required" }, "404": { "description": "Group not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "integer", "description": "The person to add." } }, "required": [ "user_id" ] } } } } } }, "/v1/admin/tenant/groups/{id}/members/{userId}": { "delete": { "tags": [ "Groups" ], "summary": "Remove a user from a group", "operationId": "delete-v1-admin-tenant-groups-id-members-userid", "description": "Remove a user from a group. Requires the GLOBAL_ADMIN role.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "404": { "description": "Membership not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/licenses": { "get": { "tags": [ "Licences" ], "summary": "List licence packages and seats", "operationId": "get-v1-admin-tenant-licenses", "description": "List the tenant's acquired license packages, with seat usage and RMM grace-period status. Requires the GLOBAL_ADMIN role. Each package includes assigned seat count and the applications it grants. Also returns a separate `rmm` object describing RMM license/grace-period state (see services/rmmLicenseEnforcement.js).\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`).", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "licenses": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "tenant_id": { "type": "integer" }, "package_id": { "type": "integer" }, "seats": { "type": "integer" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "acquired_at": { "type": "string", "format": "date-time" }, "is_active": { "type": "boolean" }, "package_name": { "type": "string" }, "package_description": { "type": "string", "nullable": true }, "assigned_users": {}, "applications": {} } } }, "rmm": {} } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/audit-log": { "get": { "tags": [ "Audit log" ], "summary": "Search/list the tenant's audit log", "operationId": "get-v1-admin-tenant-audit-log", "description": "Search/list the tenant's audit log. Requires the audit.view permission. Supports free-text search, HTTP method, status-code class, and date-range filters, paginated.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `audit.view`.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "schema": {} }, { "name": "method", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status_class", "in": "query", "required": false, "schema": {} }, { "name": "from", "in": "query", "required": false, "schema": {} }, { "name": "to", "in": "query", "required": false, "schema": {} } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "logs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "user_email": { "type": "string", "nullable": true }, "method": { "type": "string" }, "path": { "type": "string" }, "status_code": { "type": "integer" }, "duration_ms": { "type": "integer" }, "ip": { "type": "string", "nullable": true } } } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "pages": { "type": "integer" } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/audit-log/{id}": { "get": { "tags": [ "Audit log" ], "summary": "Get a single audit log entry", "operationId": "get-v1-admin-tenant-audit-log-id", "description": "Get a single audit log entry. Requires the audit.view permission. Returns the full row (SELECT *), unlike the list endpoint's trimmed column set.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `audit.view`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "log": {} } } } } }, "404": { "description": "Not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/audit-events": { "get": { "tags": [ "Audit log" ], "summary": "Search the tenant's activity audit trail", "operationId": "get-v1-admin-tenant-audit-events", "description": "Search the tenant's activity audit trail. >\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `audit.view`.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "pages": { "type": "integer" } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/audit-events/facets": { "get": { "tags": [ "Audit log" ], "summary": "Filter options for the audit trail report", "operationId": "get-v1-admin-tenant-audit-events-facets", "description": "Filter options for the audit trail report. Requires audit.view. Every workload/category/activity/resource-type combination actually present in this tenant's retained audit trail, with counts — used to populate the report's filter dropdowns.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `audit.view`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "facets": { "type": "array", "items": { "type": "object", "properties": { "workload": { "type": "string" }, "category": { "type": "string" }, "operation": { "type": "string" }, "target_type": { "type": "string", "nullable": true }, "count": { "type": "integer" } } } } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/audit-events/export": { "get": { "tags": [ "Audit log" ], "summary": "Export the audit trail as CSV", "operationId": "get-v1-admin-tenant-audit-events-export", "description": "Export the audit trail as CSV. Requires audit.view. Same filters as GET /admin/tenant/audit-events; capped at 50,000 rows (newest first).\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `audit.view`.", "parameters": [], "responses": { "200": { "description": "Success" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/audit-events/{id}": { "get": { "tags": [ "Audit log" ], "summary": "Get a single audit event, with modified properties", "operationId": "get-v1-admin-tenant-audit-events-id", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `audit.view`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "object", "properties": { "id": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "tenant_id": { "type": "integer", "nullable": true }, "workload": { "type": "string" }, "category": { "type": "string" }, "operation": { "type": "string" }, "result": { "type": "string", "enum": [ "success", "failure" ] }, "result_reason": { "type": "string", "nullable": true }, "actor_type": { "type": "string" }, "actor_user_id": { "type": "integer", "nullable": true }, "actor_email": { "type": "string", "nullable": true }, "actor_name": { "type": "string", "nullable": true }, "target_type": { "type": "string", "nullable": true }, "target_id": { "type": "string", "nullable": true }, "target_name": { "type": "string", "nullable": true }, "modified_properties": { "type": "object", "nullable": true }, "details": { "type": "object", "nullable": true }, "ip": { "type": "string", "nullable": true }, "user_agent": { "type": "string", "nullable": true }, "session_ref": { "type": "string", "nullable": true }, "request_method": { "type": "string", "nullable": true }, "request_path": { "type": "string", "nullable": true } } } } } } } }, "404": { "description": "Not found" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/sign-ins": { "get": { "tags": [ "Sign-ins & sessions" ], "summary": "Search the tenant's sign-in logs", "operationId": "get-v1-admin-tenant-sign-ins", "description": "Search the tenant's sign-in logs. >\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `audit.view`.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "signIns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "user_id": { "type": "integer", "nullable": true }, "user_email": { "type": "string", "nullable": true }, "user_name": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "success", "failure", "interrupted" ] }, "failure_code": { "type": "string", "nullable": true }, "failure_reason": { "type": "string", "nullable": true }, "application": { "type": "string" }, "interactive": { "type": "boolean" }, "auth_method": { "type": "string", "nullable": true }, "mfa_result": { "type": "string", "nullable": true }, "ip": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "browser": { "type": "string", "nullable": true }, "os": { "type": "string", "nullable": true } } } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "pages": { "type": "integer" } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/sign-ins/facets": { "get": { "tags": [ "Sign-ins & sessions" ], "summary": "Filter options for the sign-in log report", "operationId": "get-v1-admin-tenant-sign-ins-facets", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `audit.view`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "applications": { "type": "array", "items": {} }, "failureCodes": { "type": "array", "items": {} }, "countries": { "type": "array", "items": {} } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/sign-ins/export": { "get": { "tags": [ "Sign-ins & sessions" ], "summary": "Export sign-in logs as CSV", "operationId": "get-v1-admin-tenant-sign-ins-export", "description": "Export sign-in logs as CSV. Requires audit.view. Same filters as GET /admin/tenant/sign-ins; capped at 50,000 rows.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `audit.view`.", "parameters": [], "responses": { "200": { "description": "Success" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/sign-ins/{id}": { "get": { "tags": [ "Sign-ins & sessions" ], "summary": "Get a single sign-in, with the activities done in that session", "operationId": "get-v1-admin-tenant-sign-ins-id", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `audit.view`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "signIn": { "type": "object", "properties": { "id": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "tenant_id": { "type": "integer", "nullable": true }, "user_id": { "type": "integer", "nullable": true }, "user_email": { "type": "string", "nullable": true }, "user_name": { "type": "string", "nullable": true }, "user_type": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "success", "failure", "interrupted" ] }, "failure_code": { "type": "string", "nullable": true }, "failure_reason": { "type": "string", "nullable": true }, "application": { "type": "string" }, "client_id": { "type": "string", "nullable": true }, "interactive": { "type": "boolean" }, "auth_method": { "type": "string", "nullable": true }, "mfa_result": { "type": "string", "nullable": true }, "policy_name": { "type": "string", "nullable": true }, "ip": { "type": "string", "nullable": true }, "client_reported_ip": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "region": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "browser": { "type": "string", "nullable": true }, "os": { "type": "string", "nullable": true }, "user_agent": { "type": "string", "nullable": true }, "session_ref": { "type": "string", "nullable": true } } }, "sessionActivity": {} } } } } }, "404": { "description": "Not found" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/sessions": { "get": { "tags": [ "Sign-ins & sessions" ], "summary": "List active Bramble Cloud sessions in this tenant", "operationId": "get-v1-admin-tenant-sessions", "description": "List active Bramble Cloud sessions in this tenant. Requires audit.view. One row per signed-in browser session. Session IDs themselves are never returned — only a short hashed reference that matches sign-in logs and audit events.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `audit.view`.", "parameters": [ { "name": "user_id", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "user", "in": "query", "required": false, "schema": {} } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessions": { "type": "array", "items": {} }, "session_ttl_days": { "type": "array", "items": {} } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/sessions/{id}": { "delete": { "tags": [ "Sign-ins & sessions" ], "summary": "Revoke (sign out) one session", "operationId": "delete-v1-admin-tenant-sessions-id", "description": "Revoke (sign out) one session. GLOBAL_ADMIN only. The user's current page keeps working until its short-lived access token expires (≤15 min), then they're asked to sign in again.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "404": { "description": "Session not found" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/users/{id}/revoke-sessions": { "post": { "tags": [ "People" ], "summary": "Sign a person out everywhere", "operationId": "post-v1-admin-tenant-users-id-revoke-sessions", "description": "Sign a user out everywhere. GLOBAL_ADMIN only. Deletes every Bramble Cloud session for the user.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "revoked": { "type": "integer" } } } } } }, "404": { "description": "User not found" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/monitoring/summary": { "get": { "tags": [ "Organisation" ], "summary": "Health summary for the Admin Centre home page", "operationId": "get-v1-admin-tenant-monitoring-summary", "description": "get:\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `audit.view`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "signIns": { "type": "object", "properties": { "success": {}, "failure": {}, "interrupted": {}, "users": { "type": "array", "items": {} } } }, "events": { "type": "object", "properties": { "total": { "type": "integer" }, "admin": {}, "failed": {} } }, "sessions": { "type": "object", "properties": { "active": { "type": "boolean" } } } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/applications": { "get": { "tags": [ "Roles & permissions" ], "summary": "List the platform-wide application catalog", "operationId": "get-v1-admin-tenant-applications", "description": "List the platform-wide application catalog. Requires the GLOBAL_ADMIN role. Not filtered to what this tenant has licensed — used to populate the \"which app does this role apply to\" dropdown when creating a role.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "applications": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "logo": { "type": "string" } } } } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/permissions": { "get": { "tags": [ "Roles & permissions" ], "summary": "List the full platform permission catalog", "operationId": "get-v1-admin-tenant-permissions", "description": "List the full platform permission catalog. Requires the GLOBAL_ADMIN role. Global, not per-tenant. Used to render a checklist when creating a new role, before it has any granted permissions of its own.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "permissions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "slug": { "type": "string" }, "display_name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "application_id": { "type": "integer", "nullable": true }, "category": { "type": "string", "nullable": true } } } } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/roles": { "get": { "tags": [ "Roles & permissions" ], "summary": "List all roles with their application and assigned-user count", "operationId": "get-v1-admin-tenant-roles", "description": "List all roles with their application and assigned-user count. Requires the GLOBAL_ADMIN role.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "roles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "slug": { "type": "string" }, "display_name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "application_id": { "type": "integer", "nullable": true }, "application_name": { "type": "string" }, "is_system": { "type": "boolean" }, "user_count": { "type": "boolean" } } } } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "post": { "tags": [ "Roles & permissions" ], "summary": "Create a custom role", "operationId": "post-v1-admin-tenant-roles", "description": "Create a custom role. Requires the GLOBAL_ADMIN role. slug is auto-derived from display_name (uppercased, non-alphanumerics collapsed to underscores). New roles are always is_system=0.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "role": { "type": "object", "properties": { "id": { "type": "integer" }, "slug": { "type": "string" }, "display_name": { "type": "string" } } } } } } } }, "400": { "description": "display_name is required" }, "409": { "description": "A role with that name already exists" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "display_name": { "type": "string", "description": "The role's name." }, "description": { "type": "string", "description": "What the role is for." }, "application_id": { "type": "string", "description": "The app the role belongs to (optional)." }, "permission_ids": { "type": "array", "items": {}, "description": "Permission ids from `GET /v1/admin/tenant/permissions`." } }, "required": [ "display_name" ] } } } } } }, "/v1/admin/tenant/roles/{id}": { "get": { "tags": [ "Roles & permissions" ], "summary": "Get a role with its full permission checklist", "operationId": "get-v1-admin-tenant-roles-id", "description": "Get a role with its full permission checklist. Requires the GLOBAL_ADMIN role. Returns every permission applicable to the role's application (or global permissions if application_id is null), each flagged with whether it's currently granted.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "role": {}, "permissions": { "type": "array", "items": {} } } } } } }, "404": { "description": "Role not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "patch": { "tags": [ "Roles & permissions" ], "summary": "Update a custom role's description and permissions", "operationId": "patch-v1-admin-tenant-roles-id", "description": "Update a custom role's description and permissions. Requires the GLOBAL_ADMIN role. System roles (GLOBAL_ADMIN/USER/RMM_ADMIN) cannot be edited.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "403": { "description": "Built-in roles can't be edited. Create a custom role instead." }, "404": { "description": "Role not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "display_name": { "type": "string" }, "description": { "type": "string" }, "permission_ids": { "type": "array", "items": {} } } } } } } }, "delete": { "tags": [ "Roles & permissions" ], "summary": "Delete a custom role", "operationId": "delete-v1-admin-tenant-roles-id", "description": "Delete a custom role. Requires the GLOBAL_ADMIN role. System roles cannot be deleted. If users currently hold the role, the request is rejected unless force=true is passed.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "force", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "403": { "description": "Built-in roles can't be deleted" }, "404": { "description": "Role not found" }, "409": { "description": "… user(s) currently hold this role. Reassign them first, or pass ?force=true to delete anyway." }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/roles/{id}/members": { "get": { "tags": [ "Roles & permissions" ], "summary": "List the users in this tenant who hold a role", "operationId": "get-v1-admin-tenant-roles-id-members", "description": "List the users in this tenant who hold a role. Requires the GLOBAL_ADMIN role.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "members": { "type": "array", "items": {} } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "post": { "tags": [ "Roles & permissions" ], "summary": "Give a user in this tenant a role", "operationId": "post-v1-admin-tenant-roles-id-members", "description": "Give a user in this tenant a role. Requires the GLOBAL_ADMIN role. Idempotent.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "404": { "description": "Role not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "integer" } } } } } } } }, "/v1/admin/tenant/roles/{id}/members/{userId}": { "delete": { "tags": [ "Roles & permissions" ], "summary": "Take a role away from a user in this tenant", "operationId": "delete-v1-admin-tenant-roles-id-members-userid", "description": "Take a role away from a user in this tenant. Requires the GLOBAL_ADMIN role. Refuses to remove the tenant's last Global Administrator, or your own Global Administrator role.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "404": { "description": "Role not found" }, "409": { "description": "You can't remove your own Global Administrator role. Ask another Global Administrator." }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/oidc": { "get": { "tags": [ "Single sign-on apps" ], "summary": "Get OIDC SSO status and the tenant's registered OIDC clients", "operationId": "get-v1-admin-tenant-oidc", "description": "Get OIDC SSO status and the tenant's registered OIDC clients. Requires the GLOBAL_ADMIN role. Client secrets are never returned here.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "clients": { "type": "array", "items": {} } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/oidc/enable": { "post": { "tags": [ "Single sign-on apps" ], "summary": "Enable or disable OIDC SSO for the tenant", "operationId": "post-v1-admin-tenant-oidc-enable", "description": "Enable or disable OIDC SSO for the tenant. Requires the GLOBAL_ADMIN role.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "enabled": { "type": "boolean" } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" } } } } } } } }, "/v1/admin/tenant/oidc/clients": { "post": { "tags": [ "Single sign-on apps" ], "summary": "Register a single sign-on app", "operationId": "post-v1-admin-tenant-oidc-clients", "description": "Returns the new app's `client_id` and `client_secret`. **The secret is shown only once**; rotate it if it's lost.\n\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "client": { "type": "object", "properties": { "id": { "type": "integer" }, "client_id": { "type": "integer" }, "client_secret": {}, "name": { "type": "string" }, "redirect_uris": {}, "launch_url": { "type": "string", "nullable": true }, "icon_url": { "type": "string", "nullable": true }, "show_in_drawer": { "type": "integer" }, "is_active": { "type": "integer" } } } } } } } }, "400": { "description": "name and at least one redirect_uri are required" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The app's name, shown on the consent screen." }, "redirect_uris": { "type": "array", "items": {}, "description": "Every address the app may return to after sign-in (http or https)." }, "launch_url": { "type": "string", "description": "Where the launcher opens the app. Required to show it in the launcher." }, "icon_url": { "type": "string", "description": "An image for its launcher icon." }, "show_in_drawer": { "description": "Show the app in people's launcher." } }, "required": [ "name", "redirect_uris", "launch_url" ] } } } } } }, "/v1/admin/tenant/oidc/clients/{id}": { "patch": { "tags": [ "Single sign-on apps" ], "summary": "Update an OIDC client's settings", "operationId": "patch-v1-admin-tenant-oidc-clients-id", "description": "Update an OIDC client's settings. Requires the GLOBAL_ADMIN role. All fields optional. groups_claim_name lets the claim key be renamed from the default (e.g. to \"roles\"); pass an empty string to reset it.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "400": { "description": "redirect_uris must be an array of valid http(s) URLs" }, "404": { "description": "Client not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "redirect_uris": { "type": "array", "items": {} }, "launch_url": { "type": "string" }, "icon_url": { "type": "string" }, "show_in_drawer": {}, "groups_claim_name": { "type": "string", "description": "Name of the claim that carries the person's groups (default `groups`)." }, "is_active": { "type": "boolean", "description": "Turn the app on or off." } }, "required": [ "redirect_uris" ] } } } } }, "delete": { "tags": [ "Single sign-on apps" ], "summary": "Delete an OIDC client", "operationId": "delete-v1-admin-tenant-oidc-clients-id", "description": "Delete an OIDC client. Requires the GLOBAL_ADMIN role.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "404": { "description": "Client not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/oidc/clients/{id}/rotate-secret": { "post": { "tags": [ "Single sign-on apps" ], "summary": "Rotate an OIDC client's secret", "operationId": "post-v1-admin-tenant-oidc-clients-id-rotate-secret", "description": "Rotate an OIDC client's secret. Requires the GLOBAL_ADMIN role. Invalidates the old secret immediately. The new client_secret is returned only in this response, never again.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "client_secret": {} } } } } }, "404": { "description": "Client not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/oidc/clients/{id}/access": { "get": { "tags": [ "Single sign-on apps" ], "summary": "Get an OIDC client's access-restriction settings and allow-listed subjects", "operationId": "get-v1-admin-tenant-oidc-clients-id-access", "description": "Get an OIDC client's access-restriction settings and allow-listed subjects. Requires the GLOBAL_ADMIN role.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "restrict_access": { "type": "boolean" }, "entries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "subject_type": { "type": "string", "enum": [ "user", "group", "tenant" ] }, "subject_id": { "type": "integer" }, "label": { "type": "boolean" } } } } } } } } }, "404": { "description": "Client not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "post": { "tags": [ "Single sign-on apps" ], "summary": "Add a user or group to an OIDC client's access allow-list", "operationId": "post-v1-admin-tenant-oidc-clients-id-access", "description": "Add a user or group to an OIDC client's access allow-list. Requires the GLOBAL_ADMIN role. Validates the subject belongs to the caller's tenant; uses INSERT IGNORE so re-adding an existing entry is a no-op.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "400": { "description": "subject_type ('user'|'group') and subject_id are required" }, "404": { "description": "Client not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "subject_type": { "type": "string", "enum": [ "user", "group" ] }, "subject_id": { "type": "integer" } }, "required": [ "subject_id" ] } } } } } }, "/v1/admin/tenant/oidc/clients/{id}/access/toggle": { "post": { "tags": [ "Single sign-on apps" ], "summary": "Toggle whether an OIDC client's access is restricted to an allow-list", "operationId": "post-v1-admin-tenant-oidc-clients-id-access-toggle", "description": "Toggle whether an OIDC client's access is restricted to an allow-list. Requires the GLOBAL_ADMIN role.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "restrict_access": { "type": "boolean" } } } } } }, "404": { "description": "Client not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "restrict_access": { "type": "boolean", "description": "`true`: only the people and groups on its access list may use it." } } } } } } } }, "/v1/admin/tenant/oidc/clients/{id}/access/{accessId}": { "delete": { "tags": [ "Single sign-on apps" ], "summary": "Remove a subject from an OIDC client's access allow-list", "operationId": "delete-v1-admin-tenant-oidc-clients-id-access-accessid", "description": "Remove a subject from an OIDC client's access allow-list. Requires the GLOBAL_ADMIN role.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "accessId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "404": { "description": "Client not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/forms": { "get": { "tags": [ "App settings: Forms" ], "summary": "List every form", "operationId": "get-v1-admin-forms", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `forms.admin.manage`.", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": {} } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "forms": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "tenant_id": { "type": "integer" }, "slug": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "draft", "published", "closed" ] }, "require_login": { "type": "boolean" }, "allow_multiple_responses": { "type": "boolean" }, "auto_link_project_id": { "type": "integer", "nullable": true }, "accent_color": { "type": "string" }, "background_color": { "type": "string" }, "background_image_id": { "type": "integer", "nullable": true }, "background_preset": { "type": "string", "enum": [ "none", "soft_clouds", "waves", "gradient_warm", "gradient_cool", "bramble" ] }, "font_family": { "type": "string" }, "button_style": { "type": "string", "enum": [ "rounded", "square", "pill" ] }, "card_radius": { "type": "string", "enum": [ "rounded", "sharp" ] }, "layout_style": { "type": "string", "enum": [ "classic", "title_on_background", "card_left", "card_right", "compact" ] }, "notify_on_submission": { "type": "boolean" }, "created_by": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": "string", "format": "date-time", "nullable": true }, "response_count": { "type": "boolean" }, "collaborator_count": { "type": "boolean" }, "owner": { "type": "object" } } } } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/forms/{id}": { "get": { "tags": [ "App settings: Forms" ], "summary": "Get a form with its questions", "operationId": "get-v1-admin-forms-id", "description": "One form's details and questions, for the BRM-Admin Forms drawer (\"view\"). Editing happens in BRM-Forms itself, where Global Admins get collaborator access to every form (v1-appForms.js).\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `forms.admin.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "form": {}, "fields": { "type": "array", "items": {} } } } } } }, "404": { "description": "Form not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/forms/{id}/collaborators": { "get": { "tags": [ "App settings: Forms" ], "summary": "List a form's collaborators", "operationId": "get-v1-admin-forms-id-collaborators", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `forms.admin.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "owner": { "type": "object", "properties": { "id": { "type": "integer" } } }, "collaborators": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "user": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" } } } } } } } } }, "404": { "description": "Form not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "post": { "tags": [ "App settings: Forms" ], "summary": "Add a collaborator to a form", "operationId": "post-v1-admin-forms-id-collaborators", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `forms.admin.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "400": { "description": "user_id is required" }, "404": { "description": "Form not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "integer" } } } } } } } }, "/v1/admin/forms/{id}/collaborators/available": { "get": { "tags": [ "App settings: Forms" ], "summary": "People who could be added as collaborators", "operationId": "get-v1-admin-forms-id-collaborators-available", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `forms.admin.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "schema": {} } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "users": { "type": "array", "items": {} } } } } } }, "404": { "description": "Form not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/forms/{id}/collaborators/{collabId}": { "delete": { "tags": [ "App settings: Forms" ], "summary": "Remove a collaborator from a form", "operationId": "delete-v1-admin-forms-id-collaborators-collabid", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `forms.admin.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "collabId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "404": { "description": "Form not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/forms/{id}/owner": { "patch": { "tags": [ "App settings: Forms" ], "summary": "Give a form a new owner", "operationId": "patch-v1-admin-forms-id-owner", "description": "Admin override. Unlike the owner's own transfer, the new owner doesn't need to be a collaborator already.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `forms.admin.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "400": { "description": "user_id is required" }, "404": { "description": "Form not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "integer" } } } } } } } }, "/v1/admin/tenant/apps-in-use": { "get": { "tags": [ "Licences" ], "summary": "Which licensed apps are in use", "operationId": "get-v1-admin-tenant-apps-in-use", "description": "Which licensed apps this organisation uses. Apps switched off leave the launcher, Hub and search for everyone; they stay licensed and reachable.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/apps-in-use/{applicationId}": { "patch": { "tags": [ "Licences" ], "summary": "Mark an app as used or not", "operationId": "patch-v1-admin-tenant-apps-in-use-applicationid", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "applicationId", "in": "path", "required": true, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "app": {} } } } } }, "400": { "description": "in_use must be true or false" }, "500": { "description": "Internal Server Error" }, "err.status": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "in_use": { "description": "`true` shows the app in everyone's launcher; `false` hides it." } } } } } } } }, "/v1/admin/tenant/org-type": { "patch": { "tags": [ "Organisation" ], "summary": "Set the organisation type", "operationId": "patch-v1-admin-tenant-org-type", "description": "`msp` or `company`. Decides which apps are switched on by default in the launcher.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "500": { "description": "Internal Server Error" }, "err.status": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "org_type": { "type": "string", "enum": [ "msp", "company" ] } }, "required": [ "org_type" ] } } } } } }, "/v1/admin/tenant/custom-links": { "get": { "tags": [ "Branding & launcher" ], "summary": "List launcher links", "operationId": "get-v1-admin-tenant-custom-links", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "links": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "tenant_id": { "type": "integer" }, "name": { "type": "string" }, "url": { "type": "string" }, "icon_url": { "type": "string", "nullable": true }, "position": { "type": "integer" }, "is_active": { "type": "boolean" }, "created_by": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "post": { "tags": [ "Branding & launcher" ], "summary": "Add a launcher link", "operationId": "post-v1-admin-tenant-custom-links", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "link": {} } } } } }, "400": { "description": "name is required" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The label people see." }, "url": { "type": "string", "description": "Where it goes (http or https)." }, "icon_url": { "type": "string", "description": "An image for its icon." } }, "required": [ "name", "url" ] } } } } } }, "/v1/admin/tenant/custom-links/{id}": { "patch": { "tags": [ "Branding & launcher" ], "summary": "Change a launcher link", "operationId": "patch-v1-admin-tenant-custom-links-id", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "400": { "description": "name cannot be empty" }, "404": { "description": "Link not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "icon_url": { "type": "string" }, "is_active": { "type": "boolean", "description": "Show or hide it." }, "position": { "type": "integer", "description": "Its place in the list." } }, "required": [ "name" ] } } } } }, "delete": { "tags": [ "Branding & launcher" ], "summary": "Remove a launcher link", "operationId": "delete-v1-admin-tenant-custom-links-id", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "404": { "description": "Link not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/oidc/platform-apps": { "get": { "tags": [ "Single sign-on apps" ], "summary": "List Bramble's own platform apps", "operationId": "get-v1-admin-tenant-oidc-platform-apps", "description": "First-party apps (such as Bramble Sync) the organisation can switch on or off.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "client_id": { "type": "string" }, "name": { "type": "string" }, "redirect_uris": { "type": "object" }, "is_public": { "type": "boolean" }, "enabled": { "type": "boolean" } } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/oidc/platform-apps/{clientId}/enable": { "post": { "tags": [ "Single sign-on apps" ], "summary": "Opt the tenant into a platform OIDC app", "operationId": "post-v1-admin-tenant-oidc-platform-apps-clientid-enable", "description": "Opt the tenant into a platform OIDC app. Requires the GLOBAL_ADMIN role. Adds a subject_type=tenant row to oidc_client_access for this platform-wide client.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "404": { "description": "Platform app not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/oidc/platform-apps/{clientId}/disable": { "post": { "tags": [ "Single sign-on apps" ], "summary": "Opt the tenant out of a platform OIDC app", "operationId": "post-v1-admin-tenant-oidc-platform-apps-clientid-disable", "description": "Opt the tenant out of a platform OIDC app. Requires the GLOBAL_ADMIN role. Removes the tenant's oidc_client_access row. Already-issued sessions lose access within their access-token lifetime (~10 minutes) on next refresh, not instantly.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/oidc/clients/{id}/icon": { "post": { "tags": [ "Single sign-on apps" ], "summary": "Upload a drawer/rail icon for an OIDC client", "operationId": "post-v1-admin-tenant-oidc-clients-id-icon", "description": "Upload a drawer/rail icon for an OIDC client. Requires the GLOBAL_ADMIN role. Multipart upload, field name \"icon\", 1 MB max, image mimetypes only. Stored as a BLOB in oidc_client_icons; sets the client's icon_url to the public GET /tenant/oidc/icons/{id} URL.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "icon_url": { "type": "string" } } } } } }, "400": { "description": "No image file provided" }, "404": { "description": "Client not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "delete": { "tags": [ "Single sign-on apps" ], "summary": "Remove an OIDC client's uploaded icon", "operationId": "delete-v1-admin-tenant-oidc-clients-id-icon", "description": "Remove an OIDC client's uploaded icon. Requires the GLOBAL_ADMIN role. Deletes the stored BLOB and clears icon_url.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "404": { "description": "Client not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/oidc/icons/{id}": { "get": { "tags": [ "Single sign-on apps" ], "summary": "Serve an uploaded OIDC client icon", "operationId": "get-v1-admin-tenant-oidc-icons-id", "description": "Serve an uploaded OIDC client icon. Public, no authentication — embedded via img src from other apps' origins (Hub drawer/rail). Cached for one year.\n\nRequires: None: public, or protected by a token in the address or body.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "File, page or redirect" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/branding": { "get": { "tags": [ "Branding & launcher" ], "summary": "Get the tenant's branding settings", "operationId": "get-v1-admin-tenant-branding", "description": "Get the tenant's branding settings. Requires the GLOBAL_ADMIN role. Returns colors, login headline/subtext, and logo/background image URLs (or all-null defaults if no branding row exists yet).\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "branding": { "type": "object", "properties": { "primaryColor": {}, "accentColor": {}, "loginHeadline": {}, "loginSubtext": { "type": "string" }, "logoUrl": { "type": "string", "nullable": true }, "backgroundUrl": { "type": "string", "nullable": true } } } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "put": { "tags": [ "Branding & launcher" ], "summary": "Set colours and sign-in wording", "operationId": "put-v1-admin-tenant-branding", "description": "Set the tenant's branding colors and login wording. Requires the GLOBAL_ADMIN role. Colors must be 6-digit hex (e.g. #1f9d57). login_headline max 255 chars, login_subtext max 500 chars. Upserts the tenant_branding row.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "400": { "description": "… must be a hex color like #1f9d57" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "primary_color": { "description": "Hex colour, e.g. `#1f9d57`." }, "accent_color": { "description": "Hex colour." }, "login_headline": { "type": "string", "description": "Sign-in page headline, up to 255 characters." }, "login_subtext": { "type": "string", "description": "Sign-in page text, up to 500 characters." } } } } } } } }, "/v1/admin/tenant/branding/logo": { "post": { "tags": [ "Branding & launcher" ], "summary": "Upload the tenant's branding logo", "operationId": "post-v1-admin-tenant-branding-logo", "description": "Upload the tenant's branding logo. Requires the GLOBAL_ADMIN role. Multipart upload, field name \"image\", 4 MB max, image mimetypes only. Replaces and deletes any existing logo BLOB in the same transaction.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "delete": { "tags": [ "Branding & launcher" ], "summary": "Remove the tenant's branding logo", "operationId": "delete-v1-admin-tenant-branding-logo", "description": "Remove the tenant's branding logo. Requires the GLOBAL_ADMIN role. Deletes the stored BLOB and clears logo_image_id.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/branding/background": { "post": { "tags": [ "Branding & launcher" ], "summary": "Upload the tenant's branding background image", "operationId": "post-v1-admin-tenant-branding-background", "description": "Upload the tenant's branding background image. Requires the GLOBAL_ADMIN role. Multipart upload, field name \"image\", 4 MB max, image mimetypes only. Replaces and deletes any existing background BLOB in the same transaction.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "delete": { "tags": [ "Branding & launcher" ], "summary": "Remove the tenant's branding background image", "operationId": "delete-v1-admin-tenant-branding-background", "description": "Remove the tenant's branding background image. Requires the GLOBAL_ADMIN role. Deletes the stored BLOB and clears background_image_id.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/branding/image/{id}": { "get": { "tags": [ "Branding & launcher" ], "summary": "Serve a tenant branding image (logo or background)", "operationId": "get-v1-admin-tenant-branding-image-id", "description": "Serve a tenant branding image (logo or background). Public, no authentication — embedded on the pre-login tenant login page and inside the admin panel. Not scoped by the caller's tenant since there isn't one pre-login; the image id itself is the only key.\n\nRequires: None: public, or protected by a token in the address or body.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "File, page or redirect" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/subjects/users": { "get": { "tags": [ "People" ], "summary": "Find people (for pickers)", "operationId": "get-v1-admin-tenant-subjects-users", "description": "Search the tenant's users for use as a subject picker (security policies, OIDC access, groups). Requires the GLOBAL_ADMIN role. Matches first/last/display name or email, limited to 50 results.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`).", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": {} } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "label": {}, "email": { "type": "string" } } } } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/subjects/groups": { "get": { "tags": [ "People" ], "summary": "Find groups (for pickers)", "operationId": "get-v1-admin-tenant-subjects-groups", "description": "Search the tenant's groups for use as a subject picker (security policies, OIDC access). Requires the GLOBAL_ADMIN role. Matches group name, limited to 50 results.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`).", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": {} } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "groups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "label": { "type": "string" } } } } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/user/check-email": { "post": { "tags": [ "People" ], "summary": "Is this address free?", "operationId": "post-v1-admin-user-check-email", "description": "Checks an address before creating or renaming someone.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "available": { "type": "boolean" }, "email": { "type": "string" }, "message": { "type": "string" } } } } } }, "400": { "description": "local_part and domain are required" }, "404": { "description": "Admin user not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "local_part": { "type": "string", "description": "The part before the @." }, "domain": { "type": "string", "description": "One of the organisation's verified domains." }, "exclude_user_id": { "description": "When renaming, the person being renamed." } }, "required": [ "local_part", "domain" ] } } } } } }, "/v1/admin/user": { "post": { "tags": [ "People" ], "summary": "Create a person", "operationId": "post-v1-admin-user", "description": "Creates a staff account. The username (`email`) must be on one of the organisation's verified domains. Roles, licences and groups can be given at the same time. Needs Global Administrator.\n\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "user_id": { "type": "integer" } } } } } }, "400": { "description": "email and password are required" }, "404": { "description": "Admin user not found" }, "409": { "description": "A user with this email already exists" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string", "description": "First name." }, "last_name": { "type": "string", "description": "Last name." }, "display_name": { "type": "string", "description": "How their name is shown." }, "email": { "type": "string", "description": "Their username: an address on a verified domain, e.g. `alex@example.com`." }, "recovery_email": { "type": "string", "description": "A personal address for password resets." }, "department": {}, "job_title": { "type": "string" }, "location": {}, "password": { "description": "Their first password." }, "roles": { "type": "array", "items": {}, "description": "Role slugs to give them, e.g. `[\"RMM_TECHNICIAN\"]`." }, "package_ids": { "type": "array", "items": {}, "description": "Licence package ids to assign." }, "group_ids": { "type": "array", "items": {}, "description": "Group ids to add them to." } }, "required": [ "email", "password" ] } } } } }, "delete": { "tags": [ "People" ], "summary": "Delete a person", "operationId": "delete-v1-admin-user", "description": "Permanently deletes the account. Their mailbox is either turned into a shared mailbox (`shared`) or deleted with all its mail (`delete`). You can't delete yourself.\n\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "mailbox": {} } } } } }, "400": { "description": "user_id is required" }, "404": { "description": "Admin user not found" }, "500": { "description": "Internal Server Error" }, "503": { "description": "The mail server isn't answering, so their mailbox can't be dealt with. Nothing was removed; try again in a few minutes." }, "err.status": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/portal/contacts/{contactId}/invite": { "post": { "tags": [ "Guests & portal users" ], "summary": "Invite a PSA contact as a client-portal user", "operationId": "post-v1-admin-portal-contacts-contactid-invite", "description": "Invite a PSA contact as a client-portal user. Requires the GLOBAL_ADMIN role. Contact must belong to a client and have an email on file; email must not already be a users.email (unique platform-wide). Creates a user_type=client_contact row and emails a 24-hour set-password link.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "contactId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "user_id": { "type": "integer" } } } } } }, "400": { "description": "Contact must belong to a client before granting portal access" }, "404": { "description": "Contact not found" }, "409": { "description": "A user with this email already exists" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/portal/contacts": { "get": { "tags": [ "Guests & portal users" ], "summary": "List every client-portal login in the tenant", "operationId": "get-v1-admin-portal-contacts", "description": "List every client-portal login in the tenant. Requires the GLOBAL_ADMIN role. Every user_type=client_contact user regardless of how it was created (staff invite from PSA, or self-service join link), with the associated client name attached.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "contacts": { "type": "array", "items": {} } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/portal/contacts/{userId}/revoke": { "post": { "tags": [ "Guests & portal users" ], "summary": "Revoke a client-portal user's access", "operationId": "post-v1-admin-portal-contacts-userid-revoke", "description": "Revoke a client-portal user's access. Requires the GLOBAL_ADMIN role. Non-destructive (sets status=0, row kept) so access can be restored by inviting the same contact again; also kills any active sessions.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "404": { "description": "Portal user not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/guests/invite": { "post": { "tags": [ "Guests & portal users" ], "summary": "Invite a guest user by email", "operationId": "post-v1-admin-guests-invite", "description": "Invite a guest user by email. Requires the GLOBAL_ADMIN role. Unlike staff creation, any email is accepted (no tenants_domains restriction) since users.email is now unique per (tenant_id, email) rather than platform-wide. Creates a user_type=guest row and emails a 7-day set-password link.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "user_id": { "type": "integer" } } } } } }, "400": { "description": "A valid email is required" }, "409": { "description": "A user with this email already exists on this tenant" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Their email address." }, "display_name": { "type": "string", "description": "Their name." } } } } } } } }, "/v1/admin/guests": { "get": { "tags": [ "Guests & portal users" ], "summary": "List the tenant's guest users", "operationId": "get-v1-admin-guests", "description": "List the tenant's guest users. Requires the GLOBAL_ADMIN role. Each guest includes its assigned license tenant_package_ids, in the same shape the frontend already compares against for staff users' embedded licenses.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "guests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "display_name": { "type": "string", "nullable": true }, "status": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time", "nullable": true } } } } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/guests/{guestId}/resend": { "post": { "tags": [ "Guests & portal users" ], "summary": "Resend a guest's set-password invite link", "operationId": "post-v1-admin-guests-guestid-resend", "description": "Resend a guest's set-password invite link. Requires the GLOBAL_ADMIN role. Issues a fresh 7-day link for a guest who hasn't accepted yet or lost the original email, without re-collecting their details.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "guestId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "404": { "description": "Guest not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/guests/{guestId}/revoke": { "post": { "tags": [ "Guests & portal users" ], "summary": "Revoke a guest's access", "operationId": "post-v1-admin-guests-guestid-revoke", "description": "Revoke a guest's access. Requires the GLOBAL_ADMIN role. Non-destructive (sets status=0, row kept), same pattern as POST /admin/portal/contacts/{userId}/revoke; also kills any active sessions.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "guestId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "404": { "description": "Guest not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/domains/verify": { "post": { "tags": [ "Domains" ], "summary": "Check a domain's verification record", "operationId": "post-v1-admin-tenant-domains-verify", "description": "Re-check a domain's DNS TXT verification record. Requires the GLOBAL_ADMIN role. Compares live DNS TXT records against the stored verification string. Sets domain_status to 1 (verified) on match; if a previously-verified domain (status 1) no longer matches, flips it to 3 (verification lost). System domains (status 2) cannot be re-verified.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "domain": { "type": "string" }, "verified": {}, "checked_records": { "type": "array", "items": {} } } } } } }, "400": { "description": "domain_id is required" }, "404": { "description": "Domain not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "domain_id": { "type": "integer" } }, "required": [ "domain_id" ] } } } } } }, "/v1/admin/tenant/domains/add": { "post": { "tags": [ "Domains" ], "summary": "Add a domain", "operationId": "post-v1-admin-tenant-domains-add", "description": "Returns the TXT record to publish in the domain's DNS to prove you own it.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "id": { "type": "integer" }, "domain": { "type": "string" }, "verifyRecord": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "value": {} } } } } } } }, "400": { "description": "Domain invalid format!" }, "403": { "description": "This domain cannot be added" }, "404": { "description": "User not found" }, "409": { "description": "Domain already in use" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "The domain, e.g. `example.com`." } } } } } } } }, "/v1/admin/tenant/user": { "post": { "tags": [ "People" ], "summary": "Get a person", "operationId": "post-v1-admin-tenant-user", "description": "One person's full profile, groups and licences. (A POST because it takes `user_id` in the body.)\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "groups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "group_name": { "type": "string" } } } }, "licenses": { "type": "array", "items": { "type": "object", "properties": { "tenant_package_id": { "type": "integer" }, "package_id": { "type": "integer" }, "seats": { "type": "integer" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "acquired_at": { "type": "string", "format": "date-time" }, "is_active": { "type": "boolean" }, "package_name": { "type": "string" }, "package_description": { "type": "string", "nullable": true }, "applications": { "type": "object" } } } } } } } } } } }, "404": { "description": "User not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "integer" } } } } } } }, "patch": { "tags": [ "People" ], "summary": "Change one field on a person", "operationId": "patch-v1-admin-tenant-user", "description": "Update a single field on a tenant user. Requires the GLOBAL_ADMIN role. Generic single-field setter — updatedField must be one of first_name, last_name, email, recovery_email, display_name, profile_picture, status; updatedData is the new value.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Invalid updatedField value" }, "404": { "description": "User not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "integer" }, "updatedField": { "type": "string", "description": "The field to change." }, "updatedData": { "type": "number", "description": "Its new value." } } } } } } } }, "/v1/admin/tenant/users/{id}/picture": { "put": { "tags": [ "People" ], "summary": "Set a person's photo", "operationId": "put-v1-admin-tenant-users-id-picture", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "profile_picture": {} } } } } }, "404": { "description": "User not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "image": { "description": "The image as a data URL (`data:image/png;base64,…`)." } } } } } } }, "delete": { "tags": [ "People" ], "summary": "Remove a person's photo", "operationId": "delete-v1-admin-tenant-users-id-picture", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "profile_picture": {} } } } } }, "404": { "description": "User not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/user/profile": { "patch": { "tags": [ "People" ], "summary": "Update a person's name details", "operationId": "patch-v1-admin-user-profile", "description": "Update a user's display/personal name fields. Requires the GLOBAL_ADMIN role. Only display_name, first_name, last_name, recovery_email are updatable here; only fields actually present in the body are written.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "400": { "description": "user_id is required" }, "404": { "description": "Admin user not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "integer" }, "display_name": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "recovery_email": { "type": "string" } }, "required": [ "user_id" ] } } } } } }, "/v1/admin/user/account": { "patch": { "tags": [ "People" ], "summary": "Update a person's account", "operationId": "patch-v1-admin-user-account", "description": "Update a user's account fields (email, status, department, job title, location). Requires the GLOBAL_ADMIN role. Only fields actually present in the body are written.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "400": { "description": "user_id is required" }, "404": { "description": "Admin user not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "integer" }, "status": { "type": "string", "description": "`1` active, `0` turned off. Turning someone off signs them out and stops their API keys." }, "department": {}, "job_title": { "type": "string" }, "location": {} }, "required": [ "user_id" ] } } } } } }, "/v1/admin/user/addresses": { "get": { "tags": [ "People" ], "summary": "A person's username and aliases", "operationId": "get-v1-admin-user-addresses", "description": "A user's username and aliases. Requires the GLOBAL_ADMIN role. Mail to any of these addresses reaches the user's mailbox; only the username signs in.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "user_id", "in": "query", "required": false, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "username": { "type": "string" }, "aliases": { "type": "array", "items": {} }, "mailbox_domain": { "type": "string" } } } } } }, "404": { "description": "User not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/user/username": { "patch": { "tags": [ "People" ], "summary": "Change a person's username", "operationId": "patch-v1-admin-user-username", "description": "Change a user's username. Requires the GLOBAL_ADMIN role. The new address must be on a verified domain and not anyone's username or alias. With keep_old_as_alias (default true) the old username stays as an alias, so mail to it keeps arriving. Sign-in moves to the new username.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "username": { "type": "string" } } } } } }, "404": { "description": "User not found" }, "409": { "description": "That address is already someone's username or alias." }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "number" }, "local_part": {}, "domain": { "type": "string" }, "keep_old_as_alias": { "type": "boolean", "description": "Keep the old address as an alias so mail still arrives." } } } } } } } }, "/v1/admin/user/aliases": { "post": { "tags": [ "People" ], "summary": "Add an email alias", "operationId": "post-v1-admin-user-aliases", "description": "Add an alias to a user. Requires the GLOBAL_ADMIN role. The alias must be on a verified domain and not anyone's username or alias.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "id": { "type": "integer" }, "email": { "type": "string" } } } } } }, "404": { "description": "User not found" }, "409": { "description": "That address is already someone's username or alias." }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "number" }, "local_part": {}, "domain": { "type": "string" } } } } } } } }, "/v1/admin/user/aliases/{id}": { "delete": { "tags": [ "People" ], "summary": "Remove an email alias", "operationId": "delete-v1-admin-user-aliases-id", "description": "Remove an alias from a user. Requires the GLOBAL_ADMIN role. Mail to the address stops arriving.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "number" } }, { "name": "user_id", "in": "query", "required": false, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "email": { "type": "string" } } } } } }, "404": { "description": "User not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/user/mailbox": { "patch": { "tags": [ "People" ], "summary": "Change a person's mailbox", "operationId": "patch-v1-admin-user-mailbox", "description": "Update a user's mailbox settings. Requires the GLOBAL_ADMIN role. Updates the mailboxes table row for the user (enabled, quota, plan, forwarding address); only fields actually present in the body are written.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "400": { "description": "user_id is required" }, "404": { "description": "Admin user not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "integer" }, "mailbox_enabled": { "description": "Whether they have a mailbox." }, "mailbox_quota_gb": { "description": "Mailbox size in GB." }, "mailbox_plan": { "description": "The mailbox plan." }, "forwarding_address": { "description": "Forward their mail to this address, or empty for none." } }, "required": [ "user_id" ] } } } } } }, "/v1/admin/user/groups": { "patch": { "tags": [ "People" ], "summary": "Set a person's groups", "operationId": "patch-v1-admin-user-groups", "description": "Replaces their group memberships with exactly this list.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "400": { "description": "user_id and group_ids (array) are required" }, "404": { "description": "Admin user not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "integer" }, "group_ids": { "type": "array", "items": {} } }, "required": [ "user_id" ] } } } } } }, "/v1/admin/user/roles": { "patch": { "tags": [ "People" ], "summary": "Set a person's roles", "operationId": "patch-v1-admin-user-roles", "description": "Replaces their roles with exactly this list. You can't remove your own Global Administrator role, or the organisation's last one.\n\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "roles": { "type": "array", "items": {} } } } } } }, "400": { "description": "user_id is required" }, "404": { "description": "Admin user not found" }, "409": { "description": "You can't remove your own Global Administrator role. Ask another Global Administrator." }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "number" }, "roles": { "type": "array", "items": {} } }, "required": [ "user_id" ] } } } } } }, "/v1/admin/user/licenses": { "patch": { "tags": [ "People" ], "summary": "Set a person's licences", "operationId": "patch-v1-admin-user-licenses", "description": "Replaces their licence packages with exactly this list. Fails if a package has no free seats.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "400": { "description": "user_id and license_ids (array) are required" }, "404": { "description": "Admin user not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "integer" }, "license_ids": { "type": "array", "items": {} } }, "required": [ "user_id" ] } } } } } }, "/v1/admin/user/security": { "patch": { "tags": [ "People" ], "summary": "Reset a person's password", "operationId": "patch-v1-admin-user-security", "description": "Reset a user's login password. Requires the GLOBAL_ADMIN role. new_password and confirm_password must match. Best-effort syncs the new plaintext password to the user's mailbox too (skipped for guests, who never have a mailbox), using their current mail-license enabled state.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "400": { "description": "user_id is required" }, "404": { "description": "Admin user not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "integer" }, "new_password": {}, "confirm_password": {} }, "required": [ "user_id", "new_password", "confirm_password" ] } } } } } }, "/v1/admin/user/mfa/reset": { "post": { "tags": [ "People" ], "summary": "Reset a person's two-step sign-in", "operationId": "post-v1-admin-user-mfa-reset", "description": "Turns off their authenticator so they can set it up again at next sign-in.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "400": { "description": "user_id is required" }, "404": { "description": "User not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "integer" } }, "required": [ "user_id" ] } } } } } }, "/v1/admin/domains/view": { "post": { "tags": [ "Domains" ], "summary": "Get a domain", "operationId": "post-v1-admin-domains-view", "description": "Get a single tenant domain by id. Requires the GLOBAL_ADMIN role. POST (not GET) — used as a lookup-by-id action from the admin UI.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" } } } } } }, "404": { "description": "User not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "domain_id": { "type": "integer" } } } } } } } }, "/v1/admin/tenant/license": { "post": { "tags": [ "Licences" ], "summary": "Get a licence package", "operationId": "post-v1-admin-tenant-license", "description": "One package with who it's assigned to. (A POST because it takes `tenant_package_id` in the body.)\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "license": { "type": "object", "properties": { "assigned_users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "display_name": { "type": "string", "nullable": true }, "status": { "type": "boolean" } } } } } } } } } } }, "400": { "description": "tenant_package_id is required" }, "404": { "description": "Package not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant_package_id": { "type": "integer" } }, "required": [ "tenant_package_id" ] } } } } } }, "/v1/admin/rmm/overview": { "get": { "tags": [ "RMM: sites, groups & enrolment" ], "summary": "Get device/site/group/script counts for the tenant's RMM instance", "operationId": "get-v1-admin-rmm-overview", "description": "Get device/site/group/script counts for the tenant's RMM instance. Requires the GLOBAL_ADMIN role. Reads from the RMM database (rmmPool). scripts includes both tenant-owned and global scripts.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `RMM_ANY`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "devices": { "type": "integer" }, "sites": { "type": "integer" }, "groups": { "type": "integer" }, "scripts": { "type": "integer" } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/rmm/sites": { "get": { "tags": [ "RMM: sites, groups & enrolment" ], "summary": "List the tenant's RMM sites with group and device counts", "operationId": "get-v1-admin-rmm-sites", "description": "List the tenant's RMM sites with group and device counts. Requires the GLOBAL_ADMIN role.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `RMM_ANY`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sites": { "type": "array", "items": {} } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "post": { "tags": [ "RMM: sites, groups & enrolment" ], "summary": "Create an RMM site. Requires the GLOBAL_ADMIN role", "operationId": "post-v1-admin-rmm-sites", "description": "Create an RMM site. Requires the GLOBAL_ADMIN role. name is required. The display-name column on the live sites table is auto-detected (name/site_name/title/label/display_name) since it varies; description is only written if that column actually exists on the live schema.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.enrollment.manage`.", "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "id": { "type": "integer" } } } } } }, "400": { "description": "name is required" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "client_id": { "type": "integer" } }, "required": [ "name" ] } } } } } }, "/v1/admin/rmm/sites/{id}/groups": { "get": { "tags": [ "RMM: sites, groups & enrolment" ], "summary": "Get an RMM site with its groups and per-group device counts", "operationId": "get-v1-admin-rmm-sites-id-groups", "description": "Get an RMM site with its groups and per-group device counts. Requires the GLOBAL_ADMIN role.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `RMM_ANY`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "site": {}, "groups": { "type": "array", "items": {} } } } } } }, "404": { "description": "Site not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/rmm/groups": { "get": { "tags": [ "RMM: sites, groups & enrolment" ], "summary": "List all RMM groups across every site in the tenant, with device counts", "operationId": "get-v1-admin-rmm-groups", "description": "List all RMM groups across every site in the tenant, with device counts. Requires the GLOBAL_ADMIN role.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `RMM_ANY`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "groups": { "type": "array", "items": {} } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "post": { "tags": [ "RMM: sites, groups & enrolment" ], "summary": "Create an RMM device group within a site", "operationId": "post-v1-admin-rmm-groups", "description": "Create an RMM device group within a site. Requires the GLOBAL_ADMIN role. site_id and name are required.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.enrollment.manage`.", "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "id": { "type": "integer" } } } } } }, "400": { "description": "site_id and name are required" }, "404": { "description": "Site not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "site_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" } }, "required": [ "site_id", "name" ] } } } } } }, "/v1/admin/rmm/scripts": { "get": { "tags": [ "RMM: scripts" ], "summary": "List RMM scripts available to the tenant", "operationId": "get-v1-admin-rmm-scripts", "description": "List RMM scripts available to the tenant. Requires the GLOBAL_ADMIN role. Includes both tenant-owned scripts and global (is_global=1) scripts, ordered global/system first.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.scripts.manage`, `rmm.scripts.run`, `rmm.checks.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "scripts": { "type": "array", "items": {} } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "post": { "tags": [ "RMM: scripts" ], "summary": "Create an RMM script", "operationId": "post-v1-admin-rmm-scripts", "description": "Create an RMM script. Requires the GLOBAL_ADMIN role. name, language and script_body are required. category_id is validated to belong to the tenant (or silently dropped to null). Always created as a non-global, non-system script at version 1.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.scripts.manage`.", "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "id": { "type": "integer" } } } } } }, "400": { "description": "name, language and script_body are required" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "language": {}, "script_body": {}, "timeout_seconds": { "type": "array", "items": {} }, "is_enabled": { "type": "boolean" }, "category_id": { "type": "integer" } }, "required": [ "name", "language", "script_body" ] } } } } } }, "/v1/admin/rmm/scripts/{id}": { "get": { "tags": [ "RMM: scripts" ], "summary": "Get one RMM script's full record, including its body", "operationId": "get-v1-admin-rmm-scripts-id", "description": "Get one RMM script's full record, including its body. Requires the GLOBAL_ADMIN role. Accessible if it belongs to the tenant or is global.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.scripts.manage`, `rmm.scripts.run`, `rmm.checks.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "script": {} } } } } }, "404": { "description": "Script not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "put": { "tags": [ "RMM: scripts" ], "summary": "Update an RMM script", "operationId": "put-v1-admin-rmm-scripts-id", "description": "Update an RMM script. Requires the GLOBAL_ADMIN role. System and global scripts cannot be edited, nor scripts belonging to another tenant. Increments the version column on every update.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.scripts.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "403": { "description": "System and global scripts cannot be edited" }, "404": { "description": "Script not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "language": {}, "script_body": {}, "timeout_seconds": { "type": "array", "items": {} }, "is_enabled": { "type": "boolean" }, "category_id": { "type": "integer" } } } } } } }, "delete": { "tags": [ "RMM: scripts" ], "summary": "Delete an RMM script", "operationId": "delete-v1-admin-rmm-scripts-id", "description": "Delete an RMM script. Requires the GLOBAL_ADMIN role. System and global scripts cannot be deleted, nor scripts belonging to another tenant.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.scripts.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "403": { "description": "System and global scripts cannot be deleted" }, "404": { "description": "Script not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/rmm/script-categories": { "get": { "tags": [ "RMM: scripts" ], "summary": "List the tenant's RMM script folders", "operationId": "get-v1-admin-rmm-script-categories", "description": "List the tenant's RMM script folders. Requires the GLOBAL_ADMIN role. Flat list with self-referencing parent_id — the client builds the tree. The \"Bramble Defaults\" (system/global scripts) folder is virtual and not represented here.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.scripts.manage`, `rmm.scripts.run`, `rmm.checks.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "categories": { "type": "array", "items": {} } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "post": { "tags": [ "RMM: scripts" ], "summary": "Create an RMM script folder", "operationId": "post-v1-admin-rmm-script-categories", "description": "Create an RMM script folder. Requires the GLOBAL_ADMIN role. name is required; parent_id is validated to belong to the tenant (or silently dropped to null/root).\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.scripts.manage`.", "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "id": { "type": "integer" } } } } } }, "400": { "description": "name is required" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "parent_id": { "type": "integer" } }, "required": [ "name" ] } } } } } }, "/v1/admin/rmm/script-categories/{id}": { "put": { "tags": [ "RMM: scripts" ], "summary": "Rename or re-parent an RMM script folder", "operationId": "put-v1-admin-rmm-script-categories-id", "description": "Rename or re-parent an RMM script folder. Requires the GLOBAL_ADMIN role. name is required. Server-side backstop rejects re-parenting a folder under itself or one of its own descendants (walks the ancestor chain, falls back to the folder's existing parent if a cycle is detected) — the admin UI's picker already filters these out, this is defense in depth.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.scripts.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "name is required" }, "404": { "description": "Folder not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "parent_id": { "type": "integer" } }, "required": [ "name" ] } } } } }, "delete": { "tags": [ "RMM: scripts" ], "summary": "Delete an RMM script folder and its subtree", "operationId": "delete-v1-admin-rmm-script-categories-id", "description": "Delete an RMM script folder and its subtree. Requires the GLOBAL_ADMIN role. Walks and deletes the entire nested folder subtree (no FK cascade available in this database), and uncategorizes (sets category_id=NULL) every script filed under any deleted folder rather than deleting the scripts themselves.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.scripts.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "404": { "description": "Folder not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/rmm/checks": { "get": { "tags": [ "RMM: checks & alerts" ], "summary": "List checks", "operationId": "get-v1-admin-rmm-checks", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.checks.view`, `rmm.checks.manage`, `rmm.alerts.resolve`, `rmm.integrations.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "checks": { "type": "array", "items": {} } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "post": { "tags": [ "RMM: checks & alerts" ], "summary": "Create a check", "operationId": "post-v1-admin-rmm-checks", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.checks.manage`.", "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "check_id": { "type": "integer" } } } } } }, "400": { "description": "name, check_type and check_config are required" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The check's name." }, "description": { "type": "string" }, "check_type": { "type": "string", "enum": [ "cpu_usage", "ram_usage", "disk_usage", "disk_free", "service_stopped", "device_offline", "docker_container_down", "proxmox_guest_down", "pbs_datastore_usage", "http_check", "tcp_check", "ping_check", "proxmox_host_health", "proxmox_backup_missing", "network_device_down", "network_interface_down", "mysql_backup", "device_backup" ] }, "check_config": { "type": "object", "description": "Settings for the check type, e.g. `{ \"threshold\": 90, \"duration_minutes\": 10 }` for CPU." }, "severity": { "enum": [ "info", "warning", "critical" ] }, "actions": { "type": "array", "items": {}, "description": "What to do when it fires, e.g. `[{ \"type\": \"channel\", \"channel_id\": 3 }]`." }, "assignments": { "type": "array", "items": {}, "description": "Where it applies: all devices, sites, groups or single devices." } }, "required": [ "name", "check_type", "check_config" ] } } } } } }, "/v1/admin/rmm/checks/{id}": { "get": { "tags": [ "RMM: checks & alerts" ], "summary": "Get a check with its actions and assignments", "operationId": "get-v1-admin-rmm-checks-id", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.checks.view`, `rmm.checks.manage`, `rmm.alerts.resolve`, `rmm.integrations.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "check": {}, "actions": { "type": "array", "items": {} }, "assignments": { "type": "array", "items": {} } } } } } }, "404": { "description": "Check not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "put": { "tags": [ "RMM: checks & alerts" ], "summary": "Update a check", "operationId": "put-v1-admin-rmm-checks-id", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.checks.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Unknown action_type" }, "404": { "description": "Check not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "check_type": { "type": "string" }, "check_config": {}, "severity": {}, "actions": { "type": "array", "items": {} }, "assignments": { "type": "array", "items": {} } } } } } } }, "delete": { "tags": [ "RMM: checks & alerts" ], "summary": "Delete a check", "operationId": "delete-v1-admin-rmm-checks-id", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.checks.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/rmm/checks/{id}/toggle": { "post": { "tags": [ "RMM: checks & alerts" ], "summary": "Turn a check on or off", "operationId": "post-v1-admin-rmm-checks-id-toggle", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.checks.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/rmm/alerts/stats": { "get": { "tags": [ "RMM: checks & alerts" ], "summary": "Alert statistics", "operationId": "get-v1-admin-rmm-alerts-stats", "description": "Active alerts by severity and scope, the trend, and the noisiest checks and devices.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.checks.view`, `rmm.checks.manage`, `rmm.alerts.resolve`, `rmm.integrations.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "active_total": {}, "active_by_severity": { "type": "array", "items": { "type": "object", "properties": { "severity": {}, "cnt": { "type": "integer" } } } }, "active_by_scope": {}, "trend": {}, "top_checks": { "type": "array", "items": { "type": "object", "properties": { "check_id": { "type": "integer" }, "check_name": { "type": "string", "nullable": true }, "cnt": { "type": "integer" } } } }, "top_devices": { "type": "array", "items": { "type": "object", "properties": { "device_id": { "type": "string", "nullable": true }, "device_name": { "type": "string", "nullable": true }, "cnt": { "type": "integer" } } } } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/rmm/alerts": { "get": { "tags": [ "RMM: checks & alerts" ], "summary": "List alerts", "operationId": "get-v1-admin-rmm-alerts", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.checks.view`, `rmm.checks.manage`, `rmm.alerts.resolve`, `rmm.integrations.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "alerts": { "type": "array", "items": {} } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/rmm/alerts/{id}/resolve": { "post": { "tags": [ "RMM: checks & alerts" ], "summary": "Resolve an alert", "operationId": "post-v1-admin-rmm-alerts-id-resolve", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.alerts.resolve`, `rmm.checks.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "404": { "description": "Alert not found or already resolved" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/rmm/alerts/active": { "get": { "tags": [ "RMM: checks & alerts" ], "summary": "List active alerts", "operationId": "get-v1-admin-rmm-alerts-active", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.checks.view`, `rmm.checks.manage`, `rmm.alerts.resolve`, `rmm.integrations.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "alerts": { "type": "array", "items": {} } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/rmm/tasks": { "get": { "tags": [ "RMM: scheduled tasks" ], "summary": "List scheduled tasks", "operationId": "get-v1-admin-rmm-tasks", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.scripts.run`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "tasks": { "type": "array", "items": {} } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "post": { "tags": [ "RMM: scheduled tasks" ], "summary": "Create a scheduled task", "operationId": "post-v1-admin-rmm-tasks", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.scripts.run`.", "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "task_id": { "type": "integer" } } } } } }, "400": { "description": "name, schedule and at least one step are required" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The task's name." }, "description": { "type": "string" }, "schedule": { "type": "object", "description": "When it runs: `{ \"type\": \"interval\", \"every_hours\": 6 }`, `{ \"type\": \"daily\", \"time\": \"02:00\" }`, `{ \"type\": \"weekly\", \"weekday\": 1, \"time\": \"02:00\" }`, `{ \"type\": \"monthly_day\", \"day\": 1 }` or `{ \"type\": \"monthly_weekday\", \"week\": 1, \"weekday\": 2 }`." }, "on_failure_notify": { "description": "Notify when a run fails." }, "notify_config": { "type": "string", "description": "Who or which channel to notify." }, "device_filters": { "type": "array", "items": {}, "description": "Narrow the devices further by type, OS or name." }, "assignments": { "type": "array", "items": {}, "description": "Devices, sites or groups it runs on." }, "steps": { "type": "array", "items": {}, "description": "Scripts to run in order: `[{ \"script_id\": 12, \"script_args\": {}, \"stop_on_failure\": true }]`." } }, "required": [ "name", "schedule", "steps" ] } } } } } }, "/v1/admin/rmm/tasks/{id}": { "get": { "tags": [ "RMM: scheduled tasks" ], "summary": "Get a task with its steps and assignments", "operationId": "get-v1-admin-rmm-tasks-id", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.scripts.run`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "task": {}, "steps": { "type": "array", "items": {} }, "assignments": { "type": "array", "items": {} } } } } } }, "404": { "description": "Task not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "put": { "tags": [ "RMM: scheduled tasks" ], "summary": "Update a scheduled task", "operationId": "put-v1-admin-rmm-tasks-id", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.scripts.run`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "At least one step is required" }, "404": { "description": "Task not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schedule": {}, "on_failure_notify": {}, "notify_config": { "type": "string" }, "device_filters": { "type": "string" }, "assignments": { "type": "array", "items": {} }, "steps": { "type": "array", "items": {} } }, "required": [ "steps" ] } } } } }, "delete": { "tags": [ "RMM: scheduled tasks" ], "summary": "Delete a task", "operationId": "delete-v1-admin-rmm-tasks-id", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.scripts.run`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "404": { "description": "Task not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/rmm/tasks/{id}/toggle": { "post": { "tags": [ "RMM: scheduled tasks" ], "summary": "Turn a task on or off", "operationId": "post-v1-admin-rmm-tasks-id-toggle", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.scripts.run`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/rmm/tasks/{id}/run": { "post": { "tags": [ "RMM: scheduled tasks" ], "summary": "Run a task now", "operationId": "post-v1-admin-rmm-tasks-id-run", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.scripts.run`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "404": { "description": "Task not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/rmm/tasks/{id}/runs": { "get": { "tags": [ "RMM: scheduled tasks" ], "summary": "A task's past runs", "operationId": "get-v1-admin-rmm-tasks-id-runs", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.scripts.run`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "runs": { "type": "array", "items": {} } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/rmm/runs": { "get": { "tags": [ "RMM: scheduled tasks" ], "summary": "Recent task runs", "operationId": "get-v1-admin-rmm-runs", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.scripts.run`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "runs": { "type": "array", "items": {} } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/rmm/runs/{runId}/results": { "get": { "tags": [ "RMM: scheduled tasks" ], "summary": "Per-device rollup plus the full per-step timeline (client groups by device_id and orders by sort_order to render a mini step-by-step timeline per device)", "operationId": "get-v1-admin-rmm-runs-runid-results", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.scripts.run`.", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "run_id": { "type": "integer" }, "task_id": { "type": "integer" }, "device_id": { "type": "string" }, "device_name": { "type": "string", "nullable": true }, "command_id": { "type": "integer", "nullable": true }, "status": { "type": "string", "enum": [ "pending", "running", "success", "failed", "timeout" ], "nullable": true }, "exit_code": { "type": "integer", "nullable": true }, "stdout": { "type": "string", "nullable": true }, "stderr": { "type": "string", "nullable": true }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } } } }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "run_id": { "type": "integer" }, "device_id": { "type": "string" }, "step_id": { "type": "integer" }, "sort_order": { "type": "integer" }, "command_id": { "type": "integer", "nullable": true }, "status": { "type": "string", "enum": [ "pending", "queued", "running", "success", "failed", "timeout", "skipped" ], "nullable": true }, "exit_code": { "type": "integer", "nullable": true }, "stdout": { "type": "string", "nullable": true }, "stderr": { "type": "string", "nullable": true }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "script_name": { "type": "string" }, "script_language": { "type": "string" } } } } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/rmm/runs/{runId}/cancel": { "post": { "tags": [ "RMM: scheduled tasks" ], "summary": "Cancel a running task", "operationId": "post-v1-admin-rmm-runs-runid-cancel", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.scripts.run`.", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "404": { "description": "Run not found" }, "409": { "description": "Run is not in progress" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/rmm/hypervisor-scope-summary": { "get": { "tags": [ "RMM: agent updates" ], "summary": "Hypervisors in a site or group", "operationId": "get-v1-admin-rmm-hypervisor-scope-summary", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `RMM_ANY`.", "parameters": [ { "name": "scope_type", "in": "query", "required": true, "schema": { "type": "string" }, "description": "`site` or `group`." }, { "name": "scope_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "The site's or group's id." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "docker_hosts": { "type": "number" }, "proxmox_hosts": { "type": "number" }, "pbs_hosts": { "type": "number" }, "total_devices": { "type": "number" } } } } } }, "400": { "description": "scope_type and scope_id are required" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/rmm/agent-updates": { "get": { "tags": [ "RMM: agent updates" ], "summary": "Agent update policy and devices behind", "operationId": "get-v1-admin-rmm-agent-updates", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `RMM_ANY`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "policy": { "type": "object", "properties": { "tenant_id": { "type": "integer" }, "enabled": { "type": "boolean" }, "update_rmm": { "type": "boolean" }, "update_remote": { "type": "boolean" }, "schedule_days": { "type": "string" }, "window_start": { "type": "string", "format": "time" }, "window_minutes": { "type": "integer" }, "timezone": { "type": "string" }, "max_parallel": { "type": "integer" }, "excluded_devices": { "type": "object", "nullable": true }, "updated_by": { "type": "string", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } } }, "devices": { "type": "integer" }, "rmm_behind": { "type": "integer" }, "remote_behind": { "type": "integer" } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "put": { "tags": [ "RMM: agent updates" ], "summary": "Turn automatic agent updates on or off", "operationId": "put-v1-admin-rmm-agent-updates", "description": "Only the switch is edited here; the rest of the policy keeps its values (or the defaults, the first time).\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.enrollment.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" } } } } } } } }, "/v1/admin/rmm/${base}/sites": { "get": { "tags": [ "RMM: device management" ], "summary": "This organisation's own RMM sites and who manages each one's devices (RMM2's site picker): the linked customer while its partnership lets us manage its devic…", "operationId": "get-v1-admin-rmm-base-sites", "description": "This organisation's own RMM sites and who manages each one's devices (RMM2's site picker): the linked customer while its partnership lets us manage its device policies, otherwise us.\n\nRequires: None: public, or protected by a token in the address or body.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sites": { "type": "array", "items": {} } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/rmm/${base}/baselines": { "get": { "tags": [ "RMM: device management" ], "summary": "List baselines", "operationId": "get-v1-admin-rmm-base-baselines", "description": "Requires: None: public, or protected by a token in the address or body.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "baselines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "updated_by": {}, "updated_at": { "type": "string", "format": "date-time" }, "profiles": { "type": "array", "items": {} }, "targets": { "type": "array", "items": {} } } } }, "available_targets": { "type": "array", "items": {} }, "default_priority": {} } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "post": { "tags": [ "RMM: device management" ], "summary": "Create a baseline", "operationId": "post-v1-admin-rmm-base-baselines", "description": "Requires: None: public, or protected by a token in the address or body.", "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } } } } } } } }, "/v1/admin/rmm/${base}/baselines/{id}": { "put": { "tags": [ "RMM: device management" ], "summary": "Update a baseline", "operationId": "put-v1-admin-rmm-base-baselines-id", "description": "Requires: None: public, or protected by a token in the address or body.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } } } } } } }, "delete": { "tags": [ "RMM: device management" ], "summary": "Delete a baseline", "operationId": "delete-v1-admin-rmm-base-baselines-id", "description": "Requires: None: public, or protected by a token in the address or body.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/rmm/${base}/baselines/{id}/targets": { "put": { "tags": [ "RMM: device management" ], "summary": "Which organisations the baseline is deployed to (replaces the list)", "operationId": "put-v1-admin-rmm-base-baselines-id-targets", "description": "Requires: None: public, or protected by a token in the address or body.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant_ids": { "type": "array", "items": {} } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant_ids": { "type": "array", "items": {} } } } } } } } }, "/v1/admin/rmm/history": { "get": { "tags": [ "RMM: agent updates" ], "summary": "History retention and usage", "operationId": "get-v1-admin-rmm-history", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.logs.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": {}, "summary": {}, "logs": { "type": "object", "properties": { "settings": {}, "total": { "type": "integer" } } } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "put": { "tags": [ "RMM: agent updates" ], "summary": "Set how long RMM history is kept", "operationId": "put-v1-admin-rmm-history", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.logs.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": {} } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "utilization_days": { "type": "integer", "description": "Days of CPU, memory and disk history." }, "command_days": { "type": "integer", "description": "Days of command and script output." }, "logs_days": { "type": "integer", "description": "Days of collected logs." } } } } } } } }, "/v1/admin/partners": { "get": { "tags": [ "Partners" ], "summary": "List partnerships", "operationId": "get-v1-admin-partners", "description": "Partners managing this organisation, customers this organisation manages, pending requests, and the permissions available.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "permissions": { "type": "array", "items": {} } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/partners/requests": { "post": { "tags": [ "Partners" ], "summary": "Ask to manage a customer", "operationId": "post-v1-admin-partners-requests", "description": "Sends a partnership request to the organisation that owns the domain. They approve it and choose the permissions.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "customer": { "type": "string" } } } } } }, "400": { "description": "That's your own organisation." }, "404": { "description": "No Bramble organisation uses that domain." } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "One of the customer's verified domains." }, "permissions": { "type": "array", "items": {}, "description": "What you're asking for: `devices.read`, `device_management.manage`. (`admin.full` can only be given by the customer.)" }, "note": { "type": "string", "description": "A message for the customer." } } } } } } } }, "/v1/admin/partners/{id}/approve": { "post": { "tags": [ "Partners" ], "summary": "Approve a partner", "operationId": "post-v1-admin-partners-id-approve", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "permissions": { "type": "array", "items": {} } } } } } }, "400": { "description": "Choose at least one thing they may do." }, "409": { "description": "This request has already been answered." } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "permissions": { "type": "array", "items": {}, "description": "What the partner may do: `devices.read`, `device_management.manage`, `admin.full`." } } } } } } } }, "/v1/admin/partners/{id}/decline": { "post": { "tags": [ "Partners" ], "summary": "Decline a partner's request", "operationId": "post-v1-admin-partners-id-decline", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } } } } } }, "409": { "description": "This request has already been answered." } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/partners/{id}/permissions": { "put": { "tags": [ "Partners" ], "summary": "Change what a partner may do", "operationId": "put-v1-admin-partners-id-permissions", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "permissions": { "type": "array", "items": {} } } } } } }, "400": { "description": "Choose at least one thing they may do, or end the partnership." }, "409": { "description": "Only an active partnership can be changed." } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "permissions": { "type": "array", "items": {} } } } } } } } }, "/v1/admin/partners/{id}/end": { "post": { "tags": [ "Partners" ], "summary": "End a partnership", "operationId": "post-v1-admin-partners-id-end", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } } } } } }, "409": { "description": "This partnership has already ended." } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/partners/sites": { "get": { "tags": [ "Partners" ], "summary": "Your RMM sites and the customers they're linked to", "operationId": "get-v1-admin-partners-sites", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sites": { "type": "array", "items": {} }, "customers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "permissions": { "type": "array", "items": {} } } } } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/partners/sites/{siteId}": { "put": { "tags": [ "Partners" ], "summary": "Link an RMM site to a customer", "operationId": "put-v1-admin-partners-sites-siteid", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "siteId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "managed_tenant_id": { "type": "integer" } } } } } }, "400": { "description": "Only organisations that have approved you as their partner can be linked." }, "404": { "description": "Site not found" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_tenant_id": { "type": "number", "description": "The customer organisation, or `null` to unlink." } } } } } } } }, "/v1/admin/mail/mailboxes": { "get": { "tags": [ "App settings: Mail" ], "summary": "List every mailbox", "operationId": "get-v1-admin-mail-mailboxes", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/mail/domains": { "get": { "tags": [ "App settings: Mail" ], "summary": "List mail domains and their DNS", "operationId": "get-v1-admin-mail-domains", "description": "Every verified domain with its mail state and DNS records (services/mailDomains.js).\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "domains": { "type": "array", "items": {} } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/mail/domains/{domain}/setup": { "post": { "tags": [ "App settings: Mail" ], "summary": "Set up mail for a domain", "operationId": "post-v1-admin-mail-domains-domain-setup", "description": "Creates the domain on the mail server and returns the DNS records (MX, SPF, DKIM, DMARC) to publish.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/mail/domains/{domain}/check": { "post": { "tags": [ "App settings: Mail" ], "summary": "Check a mail domain's DNS now", "operationId": "post-v1-admin-mail-domains-domain-check", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/mail/shared": { "get": { "tags": [ "App settings: Mail" ], "summary": "List shared mailboxes", "operationId": "get-v1-admin-mail-shared", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "shared": {} } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "post": { "tags": [ "App settings: Mail" ], "summary": "Create a shared mailbox", "operationId": "post-v1-admin-mail-shared", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "shared": {} } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "local_part": { "description": "The part before the @." }, "domain": { "type": "string", "description": "A mail domain." }, "display_name": { "type": "string", "description": "Its name." } } } } } } } }, "/v1/admin/mail/shared/existing": { "post": { "tags": [ "App settings: Mail" ], "summary": "Turn an existing mailbox into a shared one", "operationId": "post-v1-admin-mail-shared-existing", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "shared": {} } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "The mailbox's address." }, "display_name": { "type": "string" }, "keep_sign_in": { "type": "boolean", "description": "Keep the old account able to sign in." } } } } } } } }, "/v1/admin/mail/shared/{id}": { "patch": { "tags": [ "App settings: Mail" ], "summary": "Change a shared mailbox", "operationId": "patch-v1-admin-mail-shared-id", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "shared": {} } } } } }, "404": { "description": "Shared mailbox not found." } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "display_name": { "type": "string" }, "keep_sign_in": {} } } } } } }, "delete": { "tags": [ "App settings: Mail" ], "summary": "Stop sharing a mailbox", "operationId": "delete-v1-admin-mail-shared-id", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "404": { "description": "Shared mailbox not found." } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/mail/mailboxes/{domain}/{boxId}": { "delete": { "tags": [ "App settings: Mail" ], "summary": "Deletes a shared or unassigned mailbox and all its mail from the server", "operationId": "delete-v1-admin-mail-mailboxes-domain-boxid", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "boxId", "in": "path", "required": true, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "address": {} } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/mail/users/{userId}/mailbox": { "get": { "tags": [ "App settings: Mail" ], "summary": "A person's mailbox, so \"Remove user\" can ask what happens to it", "operationId": "get-v1-admin-mail-users-userid-mailbox", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "mailbox": {} } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/mail/users/{userId}/app-passwords": { "get": { "tags": [ "App settings: Mail" ], "summary": "List a person's admin-made app passwords", "operationId": "get-v1-admin-mail-users-userid-app-passwords", "description": "App passwords made by an admin, for accounts that never sign in interactively (a scanner's or Paper's mailbox). services/appPasswords.js.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "app_passwords": { "type": "array", "items": {} } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "post": { "tags": [ "App settings: Mail" ], "summary": "Make an app password for a person", "operationId": "post-v1-admin-mail-users-userid-app-passwords", "description": "For accounts that never sign in interactively (a scanner, Paper's intake mailbox). The password is shown once.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "number" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "app_password": {} } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "What it's for." } } } } } } } }, "/v1/admin/mail/users/{userId}/app-passwords/{id}": { "delete": { "tags": [ "App settings: Mail" ], "summary": "Revoke an app password", "operationId": "delete-v1-admin-mail-users-userid-app-passwords-id", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "number" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "404": { "description": "App password not found." } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/mail/shared/{id}/members/{userId}": { "put": { "tags": [ "App settings: Mail" ], "summary": "Set a person's access to a shared mailbox", "operationId": "put-v1-admin-mail-shared-id-members-userid", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "number" } }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "shared": {} } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "full_access": { "description": "Read and manage the mailbox." }, "send_as": { "type": "array", "items": {}, "description": "Send as the mailbox's address." }, "send_on_behalf": { "description": "Send \"on behalf of\" the mailbox." } } } } } } } }, "/v1/admin/warden/overview": { "get": { "tags": [ "App settings: Warden" ], "summary": "Warden configuration status + headline numbers for the admin overview", "operationId": "get-v1-admin-warden-overview", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Licence: Warden. Permission (any of): `secure.admin.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "type": "object", "properties": {} }, "findings": { "type": "object", "properties": { "open_": { "type": "integer" }, "critical": { "type": "number" }, "kev": { "type": "number" } } }, "devices": { "type": "object", "properties": { "total": { "type": "integer" }, "supported": { "type": "number" }, "limited_": { "type": "number" } } }, "policies": { "type": "object", "properties": { "n": { "type": "integer" }, "enabled": { "type": "number" } } }, "rules": { "type": "object", "properties": { "n": { "type": "integer" }, "enabled": { "type": "number" } } }, "mapped_sites": { "type": "integer" }, "total_sites": { "type": "integer" } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/warden/network": { "get": { "tags": [ "App settings: Warden" ], "summary": "Detection + PSA integration settings, and the site -> PSA customer map", "operationId": "get-v1-admin-warden-network", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Licence: Warden. Permission (any of): `secure.admin.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "network": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "hour": { "type": "integer" }, "extra_targets": { "type": "string" } } }, "probes": { "type": "array", "items": {} } } } } } }, "503": { "description": "Network scanning needs the Warden service restarted first" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "put": { "tags": [ "App settings: Warden" ], "summary": "Update the network", "operationId": "put-v1-admin-warden-network", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Licence: Warden. Permission (any of): `secure.admin.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Not an IPv4 address or /16–/32 network: …" }, "503": { "description": "Network scanning needs the Warden service restarted first" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "hour": { "type": "integer" }, "extra_targets": { "type": "array", "items": {} }, "enabled": { "type": "boolean" } } } } } } } }, "/v1/admin/warden/siem": { "get": { "tags": [ "App settings: Warden" ], "summary": "Get the SIEM", "operationId": "get-v1-admin-warden-siem", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Licence: Warden. Permission (any of): `secure.admin.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "siem": { "type": "object", "properties": { "updated_at": { "type": "string", "format": "date-time", "nullable": true } } }, "retention_options": { "type": "array", "items": {} }, "devices": { "type": "object", "properties": { "windows": { "type": "number" }, "linux": { "type": "number" }, "collecting": { "type": "number" }, "audit_applied": { "type": "number" }, "audit_failed": { "type": "number" } } } } } } } }, "503": { "description": "Logs & auditing needs the Warden service restarted first" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "put": { "tags": [ "App settings: Warden" ], "summary": "Update the SIEM", "operationId": "put-v1-admin-warden-siem", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Licence: Warden. Permission (any of): `secure.admin.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Keep events for … days" }, "503": { "description": "Logs & auditing needs the Warden service restarted first" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "retention_days": { "type": "number" }, "enabled": { "type": "boolean" }, "process_creation": { "type": "boolean" }, "powershell": { "type": "boolean" }, "bramble_audit": { "type": "boolean" }, "audit_policy": { "type": "boolean" } } } } } } } }, "/v1/admin/warden/settings": { "get": { "tags": [ "App settings: Warden" ], "summary": "Get the settings", "operationId": "get-v1-admin-warden-settings", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Licence: Warden. Permission (any of): `secure.admin.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "type": "object", "properties": { "tenant_id": { "type": "integer" } } }, "site_customers": { "type": "array", "items": { "type": "object", "properties": { "site_id": { "type": "integer" }, "psa_customer_id": { "type": "integer" } } } } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "put": { "tags": [ "App settings: Warden" ], "summary": "Update the settings", "operationId": "put-v1-admin-warden-settings", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Licence: Warden. Permission (any of): `secure.admin.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Unknown PSA queue" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "hide_low_priority": {}, "include_unfixed": {}, "psa_enabled": {}, "psa_queue_id": { "type": "number" }, "psa_default_customer_id": { "type": "number" }, "psa_auto_close": { "type": "boolean" }, "site_customers": { "type": "array", "items": {} } } } } } } } }, "/v1/admin/warden/lookups": { "get": { "tags": [ "App settings: Warden" ], "summary": "RMM sites and PSA queues/customers for the settings dropdowns", "operationId": "get-v1-admin-warden-lookups", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Licence: Warden. Permission (any of): `secure.admin.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sites": { "type": "array", "items": {} }, "queues": { "type": "array", "items": {} }, "customers": { "type": "array", "items": {} } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/warden/ticket-rules": { "get": { "tags": [ "App settings: Warden" ], "summary": "List ticket rules", "operationId": "get-v1-admin-warden-ticket-rules", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Licence: Warden. Permission (any of): `secure.admin.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "rules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "tenant_id": { "type": "integer" }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "min_severity": { "type": "string", "enum": [ "critical", "high", "medium", "low" ] }, "kev_only": { "type": "boolean" }, "fixable_only": { "type": "boolean" }, "site_ids": { "type": "array", "items": {} }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "queue_id": { "type": "integer", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true } } } } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "post": { "tags": [ "App settings: Warden" ], "summary": "Create a ticket rule", "operationId": "post-v1-admin-warden-ticket-rules", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Licence: Warden. Permission (any of): `secure.admin.manage`.", "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" } } } } } }, "400": { "description": "Name is required" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "enabled": { "type": "boolean" }, "min_severity": { "type": "string", "enum": [ "critical", "high", "medium", "low" ] }, "kev_only": {}, "fixable_only": { "type": "boolean" }, "site_ids": { "type": "array", "items": {} }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "queue_id": { "type": "number" } } } } } } } }, "/v1/admin/warden/ticket-rules/{id}": { "put": { "tags": [ "App settings: Warden" ], "summary": "Update a ticket rule", "operationId": "put-v1-admin-warden-ticket-rules-id", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Licence: Warden. Permission (any of): `secure.admin.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Name is required" }, "404": { "description": "Rule not found" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "enabled": { "type": "boolean" }, "min_severity": { "type": "string", "enum": [ "critical", "high", "medium", "low" ] }, "kev_only": {}, "fixable_only": { "type": "boolean" }, "site_ids": { "type": "array", "items": {} }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "queue_id": { "type": "number" } } } } } } }, "delete": { "tags": [ "App settings: Warden" ], "summary": "Delete a ticket rule", "operationId": "delete-v1-admin-warden-ticket-rules-id", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Licence: Warden. Permission (any of): `secure.admin.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "404": { "description": "Rule not found" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/warden/notify-channels": { "get": { "tags": [ "App settings: Warden" ], "summary": "The tenant's named notification channels Warden can deliver through (set up in Admin → RMM → Notification channels)", "operationId": "get-v1-admin-warden-notify-channels", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Licence: Warden. Permission (any of): `secure.admin.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "channels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "channel_type": { "type": "string" }, "name": { "type": "string" }, "is_enabled": { "type": "boolean" }, "last_sent_at": { "type": "string", "format": "date-time", "nullable": true }, "last_error": { "type": "string", "nullable": true }, "last_error_at": { "type": "string", "format": "date-time", "nullable": true } } } } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/warden/notify-rules": { "get": { "tags": [ "App settings: Warden" ], "summary": "Warden notification rules, with each rule's last delivery", "operationId": "get-v1-admin-warden-notify-rules", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Licence: Warden. Permission (any of): `secure.admin.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "rules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "tenant_id": { "type": "integer" }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "events": { "type": "array", "items": {} }, "min_severity": { "type": "string", "enum": [ "critical", "high", "medium", "low" ] }, "kev_only": { "type": "boolean" }, "site_ids": { "type": "array", "items": {} }, "actions": { "type": "array", "items": {} }, "test_requested_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "last": { "type": "object", "nullable": true } } } }, "log": {} } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "post": { "tags": [ "App settings: Warden" ], "summary": "Create a notify rule", "operationId": "post-v1-admin-warden-notify-rules", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Licence: Warden. Permission (any of): `secure.admin.manage`.", "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": {} }, "actions": { "type": "array", "items": {} }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "min_severity": { "type": "string", "enum": [ "critical", "high", "medium", "low" ] }, "kev_only": {}, "site_ids": { "type": "array", "items": {} } } } } } } } }, "/v1/admin/warden/notify-rules/{id}": { "put": { "tags": [ "App settings: Warden" ], "summary": "Update a notification rule", "operationId": "put-v1-admin-warden-notify-rules-id", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Licence: Warden. Permission (any of): `secure.admin.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "404": { "description": "Rule not found" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": {} }, "actions": { "type": "array", "items": {} }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "min_severity": { "type": "string", "enum": [ "critical", "high", "medium", "low" ] }, "kev_only": {}, "site_ids": { "type": "array", "items": {} } } } } } } }, "delete": { "tags": [ "App settings: Warden" ], "summary": "Delete a notify rule", "operationId": "delete-v1-admin-warden-notify-rules-id", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Licence: Warden. Permission (any of): `secure.admin.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "404": { "description": "Rule not found" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/warden/notify-rules/{id}/test": { "post": { "tags": [ "App settings: Warden" ], "summary": "Queue a test message for a rule (Warden sends it within ~15s; poll notify-rules for the result)", "operationId": "post-v1-admin-warden-notify-rules-id-test", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Licence: Warden. Permission (any of): `secure.admin.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "404": { "description": "Rule not found" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/warden/connectors": { "get": { "tags": [ "App settings: Warden" ], "summary": "List connectors", "operationId": "get-v1-admin-warden-connectors", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Licence: Warden. Permission (any of): `secure.admin.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "connectors": { "type": "array", "items": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "pinned": { "type": "boolean" }, "devices": { "type": "number" }, "updatable": { "type": "number" } } } }, "pollers": { "type": "array", "items": {} } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "post": { "tags": [ "App settings: Warden" ], "summary": "Create a connector", "operationId": "post-v1-admin-warden-connectors", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Licence: Warden. Permission (any of): `secure.admin.manage`.", "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" } } } } } }, "400": { "description": "Choose a Linux RMM device on the same network as the controller to poll it" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "api_key": { "type": "string" }, "poll_minutes": { "type": "integer" }, "probe_device_id": { "type": "integer" }, "enabled": { "type": "boolean" } } } } } } } }, "/v1/admin/warden/connectors/{id}": { "put": { "tags": [ "App settings: Warden" ], "summary": "Update a connector", "operationId": "put-v1-admin-warden-connectors-id", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Licence: Warden. Permission (any of): `secure.admin.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "description": "Choose a Linux RMM device on the same network as the controller to poll it" }, "404": { "description": "Integration not found" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "api_key": { "type": "string" }, "poll_minutes": { "type": "integer" }, "probe_device_id": { "type": "integer" }, "enabled": { "type": "boolean" } } } } } } }, "delete": { "tags": [ "App settings: Warden" ], "summary": "Delete a connector", "operationId": "delete-v1-admin-warden-connectors-id", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Licence: Warden. Permission (any of): `secure.admin.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "404": { "description": "Integration not found" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/warden/connectors/{id}/reset-pin": { "post": { "tags": [ "App settings: Warden" ], "summary": "After a controller is replaced or gets a new certificate", "operationId": "post-v1-admin-warden-connectors-id-reset-pin", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Licence: Warden. Permission (any of): `secure.admin.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "404": { "description": "Integration not found" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/simplebooks/companies": { "get": { "tags": [ "App settings: SimpleBooks" ], "summary": "Every SimpleBooks company in the tenant, with modules, access and receipt counts", "operationId": "get-v1-admin-simplebooks-companies", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "companies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "trading_name": { "type": "string", "nullable": true }, "business_type": { "type": "string", "enum": [ "sole_trader", "partnership", "limited" ] }, "year_end": { "type": "string", "enum": [ "mar31", "apr5" ] }, "created_at": { "type": "string", "format": "date-time" }, "archived_at": { "type": "string", "format": "date-time", "nullable": true }, "receipts": { "type": "boolean" }, "to_review": { "type": "boolean" }, "last_receipt_at": {}, "access_count": {}, "owner_count": {}, "modules": { "type": "array", "items": {} } } } }, "licensed_users": { "type": "integer" } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "post": { "tags": [ "App settings: SimpleBooks" ], "summary": "Create a company", "operationId": "post-v1-admin-simplebooks-companies", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" } } } } } }, "400": { "description": "Give the company a name" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "business_type": { "type": "string", "enum": [ "sole_trader", "partnership", "limited" ] }, "trading_name": { "type": "string" }, "owner_name": { "type": "string" }, "modules": { "type": "array", "items": {} } } } } } } } }, "/v1/admin/simplebooks/companies/{id}": { "put": { "tags": [ "App settings: SimpleBooks" ], "summary": "Rename, change business type, archive/unarchive, or switch modules on/off", "operationId": "put-v1-admin-simplebooks-companies-id", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Give the company a name" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "trading_name": { "type": "string" }, "business_type": { "type": "string", "enum": [ "sole_trader", "partnership", "limited" ] }, "archived": {}, "modules": { "type": "object" } } } } } } } }, "/v1/admin/simplebooks/principals": { "get": { "tags": [ "App settings: SimpleBooks" ], "summary": "Tenant users (with whether each has a SimpleBooks licence) and groups, for the access picker", "operationId": "get-v1-admin-simplebooks-principals", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "licensed": { "type": "boolean" } } } }, "groups": { "type": "array", "items": {} } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/simplebooks/companies/{id}/access": { "get": { "tags": [ "App settings: SimpleBooks" ], "summary": "Who can open this company, and with which role", "operationId": "get-v1-admin-simplebooks-companies-id-access", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "access": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "principal_type": { "type": "string", "enum": [ "user", "group" ] }, "principal_id": { "type": "integer" }, "role": { "type": "string", "enum": [ "owner", "bookkeeper", "submitter", "viewer" ] }, "created_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "email": { "nullable": true } } } } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "post": { "tags": [ "App settings: SimpleBooks" ], "summary": "Access a company", "operationId": "post-v1-admin-simplebooks-companies-id-access", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Choose a …" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "principal_type": { "type": "string" }, "principal_id": { "type": "number" }, "role": {} } } } } } } }, "/v1/admin/simplebooks/companies/{id}/access/{accessId}": { "put": { "tags": [ "App settings: SimpleBooks" ], "summary": "Update an access", "operationId": "put-v1-admin-simplebooks-companies-id-access-accessid", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "accessId", "in": "path", "required": true, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Unknown role" }, "404": { "description": "Access not found" }, "block.status": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "role": {} } } } } } }, "delete": { "tags": [ "App settings: SimpleBooks" ], "summary": "Delete an access", "operationId": "delete-v1-admin-simplebooks-companies-id-access-accessid", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "accessId", "in": "path", "required": true, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "block.status": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/simplebooks/email": { "get": { "tags": [ "App settings: SimpleBooks" ], "summary": "The SMTP account SimpleBooks emails invoices through (password never returned)", "operationId": "get-v1-admin-simplebooks-email", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "object", "properties": { "enabled": { "type": "integer" }, "smtp_port": { "type": "integer" }, "smtp_secure": { "type": "integer" }, "has_password": { "type": "boolean" } } } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "put": { "tags": [ "App settings: SimpleBooks" ], "summary": "Update the email", "operationId": "put-v1-admin-simplebooks-email", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Port must be a number, usually 587 or 465" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "smtp_host": { "type": "string" }, "smtp_port": { "type": "number" }, "smtp_secure": {}, "smtp_user": { "type": "string" }, "from_email": { "type": "string" }, "from_name": { "type": "string" }, "smtp_pass": { "type": "string" }, "clear_password": {} } } } } } } }, "/v1/admin/simplebooks/email/test": { "post": { "tags": [ "App settings: SimpleBooks" ], "summary": "Send a test email to the signed-in admin through the saved SMTP account", "operationId": "post-v1-admin-simplebooks-email-test", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Save the email settings first" }, "502": { "description": "The test email couldn't be sent: …" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/hr/overview": { "get": { "tags": [ "App settings: HR" ], "summary": "HR policy, leave types, closures, templates and licence counts in one call", "operationId": "get-v1-admin-hr-overview", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `hr.admin.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": {}, "types": { "type": "array", "items": {} }, "closures": { "type": "array", "items": {} }, "templates": { "type": "array", "items": {} }, "people": { "type": "integer" }, "licensed_users": { "type": "integer" }, "hr_admins": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "email": { "type": "string" } } } }, "groups": { "type": "array", "items": {} }, "removed": {} } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/hr/settings": { "put": { "tags": [ "App settings: HR" ], "summary": "Update the leave policy (leave year start, allowance, bank holidays, carry-over, half days, privacy)", "operationId": "put-v1-admin-hr-settings", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `hr.admin.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "description": "Choose the month the leave year starts" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "year_start_month": { "type": "number" }, "default_allowance": { "type": "number" }, "carry_over_max": { "type": "number" }, "bank_holidays": { "type": "string" }, "region": {}, "half_days": { "type": "integer" }, "show_leave_types": { "type": "array", "items": {} }, "overlap_mode": { "type": "string" } } } } } } } }, "/v1/admin/hr/people-scope": { "put": { "tags": [ "App settings: HR" ], "summary": "Who gets an HR record automatically — every staff account (scope all) or members of chosen groups (scope groups, groups = ids)", "operationId": "put-v1-admin-hr-people-scope", "description": "Who gets an HR record automatically — every staff account (scope all) or members of chosen groups (scope groups, groups = ids). BRM-HR applies it within a minute.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `hr.admin.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "description": "Choose at least one group" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string" }, "groups": { "type": "array", "items": {} } } } } } } } }, "/v1/admin/hr/removed/{employeeId}/restore": { "post": { "tags": [ "App settings: HR" ], "summary": "Restore a removed", "operationId": "post-v1-admin-hr-removed-employeeid-restore", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `hr.admin.manage`.", "parameters": [ { "name": "employeeId", "in": "path", "required": true, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "404": { "description": "That person was not found" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/hr/types": { "post": { "tags": [ "App settings: HR" ], "summary": "Add a leave type", "operationId": "post-v1-admin-hr-types", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `hr.admin.manage`.", "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "kind": { "type": "string" }, "deducts": { "type": "array", "items": {} }, "needs_approval": {}, "colour": {}, "icon": {}, "priority": { "type": "number" }, "is_absence": { "type": "boolean" }, "annual_limit": { "type": "string" } } } } } } } }, "/v1/admin/hr/types/{id}": { "put": { "tags": [ "App settings: HR" ], "summary": "Change a leave type, or archive / restore it ({ archived })", "operationId": "put-v1-admin-hr-types-id", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `hr.admin.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "404": { "description": "Leave type not found" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "archived": {} } } } } } } }, "/v1/admin/hr/closures": { "post": { "tags": [ "App settings: HR" ], "summary": "Add company closure days (a date range)", "operationId": "post-v1-admin-hr-closures", "description": "Add company closure days (a date range). Nobody books them; with { deducts } they also come out of everyone's allowance\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `hr.admin.manage`.", "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "added": { "type": "integer" } } } } } }, "400": { "description": "Give the closure a name, e.g. Christmas shutdown" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "from": {}, "to": {}, "deducts": { "type": "array", "items": {} } } } } } } } }, "/v1/admin/hr/closures/{id}": { "put": { "tags": [ "App settings: HR" ], "summary": "Switch one closure day between \"extra day off\" and \"comes out of the allowance\"", "operationId": "put-v1-admin-hr-closures-id", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `hr.admin.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "delete": { "tags": [ "App settings: HR" ], "summary": "Delete a closure", "operationId": "delete-v1-admin-hr-closures-id", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `hr.admin.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/hr/templates": { "post": { "tags": [ "App settings: HR" ], "summary": "Add an onboarding or offboarding checklist template with its tasks", "operationId": "post-v1-admin-hr-templates", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `hr.admin.manage`.", "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" } } } } } }, "400": { "description": "Give the checklist a name" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "kind": { "type": "string" }, "description": { "type": "string" }, "tasks": { "type": "array", "items": {} } } } } } } } }, "/v1/admin/hr/templates/{id}": { "put": { "tags": [ "App settings: HR" ], "summary": "Replace a template's name, description and tasks (checklists already started keep their own copy)", "operationId": "put-v1-admin-hr-templates-id", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `hr.admin.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "description": "Give the checklist a name" }, "404": { "description": "Checklist not found" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "tasks": { "type": "array", "items": {} } } } } } } }, "delete": { "tags": [ "App settings: HR" ], "summary": "Delete a template", "operationId": "delete-v1-admin-hr-templates-id", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `hr.admin.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/hr/people/{userId}": { "get": { "tags": [ "App settings: HR" ], "summary": "Get a people", "operationId": "get-v1-admin-hr-people-userid", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `hr.admin.manage`.", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "employee": { "type": "object", "properties": { "id": { "type": "integer" }, "manager_id": { "type": "integer" }, "work_days": { "type": "integer" }, "hours_per_week": {}, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" } } }, "allowance_changes": { "type": "array", "items": {} }, "this_year": {}, "managers": { "type": "array", "items": {} }, "reports": { "type": "array", "items": {} }, "policy": { "type": "object", "properties": { "default_allowance": {}, "bank_holidays": {}, "year_start_month": {} } } } } } } }, "404": { "description": "Only staff accounts have HR records" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "put": { "tags": [ "App settings: HR" ], "summary": "Update a people", "operationId": "put-v1-admin-hr-people-userid", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `hr.admin.manage`.", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "description": "Someone can't be their own manager" }, "404": { "description": "Only staff accounts have HR records" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "manager_id": { "type": "string" }, "work_days": { "type": "integer" }, "hours_per_week": {}, "start_date": { "type": "string", "format": "date" } } } } } } } }, "/v1/admin/hr/people/{userId}/allowance-changes": { "post": { "tags": [ "App settings: HR" ], "summary": "Change a user's holiday allowance from a leave year on (kind set = days a year, extra = days on top of the policy)", "operationId": "post-v1-admin-hr-people-userid-allowance-changes", "description": "Change a user's holiday allowance from a leave year on (kind set = days a year, extra = days on top of the policy). Replaces any change from the same year.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `hr.admin.manage`.", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "number" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "description": "Give a number of days" }, "404": { "description": "Only staff accounts have HR records" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string" }, "days": { "type": "number" }, "from": { "type": "string", "format": "date" }, "reason": { "type": "string" } }, "required": [ "days", "from" ] } } } } } }, "/v1/admin/hr/people/{userId}/allowance-changes/{id}": { "delete": { "tags": [ "App settings: HR" ], "summary": "Delete an allowance change", "operationId": "delete-v1-admin-hr-people-userid-allowance-changes-id", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `hr.admin.manage`.", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "number" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "404": { "description": "Only staff accounts have HR records" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/storage/overview": { "get": { "tags": [ "Storage" ], "summary": "The tenant's storage pool, where it comes from, and what each app uses", "operationId": "get-v1-admin-storage-overview", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `drive.admin.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/storage/apps/{app}/quota": { "put": { "tags": [ "Storage" ], "summary": "Cap how much of the pool one app may use (quota_bytes null removes the cap)", "operationId": "put-v1-admin-storage-apps-app-quota", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `drive.admin.manage`.", "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "400": { "description": "quota_bytes must be a whole number of bytes, or null for no limit" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "quota_bytes": { "type": "integer" } } } } } } } }, "/v1/admin/storage/users": { "get": { "tags": [ "Storage" ], "summary": "Staff users with their storage use across apps and their Drive personal quota", "operationId": "get-v1-admin-storage-users", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `drive.admin.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "default_personal_quota_bytes": { "type": "integer" }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "active": { "type": "boolean" }, "total_bytes": { "type": "integer" }, "drive_personal_bytes": { "type": "integer" }, "quota_override": { "type": "boolean" }, "drive_quota_bytes": { "type": "integer" } } } } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/storage/users/{userId}/quota": { "put": { "tags": [ "Storage" ], "summary": "Set one user's Drive personal quota (quota_bytes null = unlimited; use_default true = follow the tenant default)", "operationId": "put-v1-admin-storage-users-userid-quota", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `drive.admin.manage`.", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "description": "quota_bytes must be a whole number of bytes, or null for unlimited" }, "404": { "description": "User not found" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "use_default": {}, "quota_bytes": { "type": "integer" } } } } } } } }, "/v1/admin/storage/largest": { "get": { "tags": [ "Storage" ], "summary": "The biggest stored files across all apps (or one, with ?app=)", "operationId": "get-v1-admin-storage-largest", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `drive.admin.manage`.", "parameters": [ { "name": "app", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "object", "properties": { "owner_name": {} } } } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/storage/history": { "get": { "tags": [ "Storage" ], "summary": "Daily storage use per app (?days=, default 90)", "operationId": "get-v1-admin-storage-history", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `drive.admin.manage`.", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/storage/drive-settings": { "get": { "tags": [ "Storage" ], "summary": "Drive rules for this tenant (personal quota, versions kept, bin retention, link sharing, quick shares)", "operationId": "get-v1-admin-storage-drive-settings", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `drive.admin.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "put": { "tags": [ "Storage" ], "summary": "Update the drive settings", "operationId": "put-v1-admin-storage-drive-settings", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `drive.admin.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Personal quota must be a number of bytes, or empty for no limit" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "personal_quota_bytes": { "type": "integer" }, "version_limit": { "type": "number" }, "trash_days": { "type": "number" }, "link_max_days": { "type": "string" }, "temp_enabled": { "type": "boolean" }, "temp_max_days": { "type": "number" }, "links_enabled": {} } } } } } } }, "/v1/admin/sites/settings": { "get": { "tags": [ "App settings: Sites" ], "summary": "Who may create sites in this tenant", "operationId": "get-v1-admin-sites-settings", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `sites.admin.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "creation": { "type": "string" } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "put": { "tags": [ "App settings: Sites" ], "summary": "Update the settings", "operationId": "put-v1-admin-sites-settings", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `sites.admin.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "creation": {} } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "creation": {} } } } } } } }, "/v1/admin/sites": { "get": { "tags": [ "App settings: Sites" ], "summary": "Every site in the tenant with its owners, members, pages and library size", "operationId": "get-v1-admin-sites", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `sites.admin.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sites": { "type": "array", "items": {} } } } } } } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/sites/{id}/owners": { "post": { "tags": [ "App settings: Sites" ], "summary": "Make a tenant user an owner of a site (user_id; defaults to the calling admin)", "operationId": "post-v1-admin-sites-id-owners", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `sites.admin.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "404": { "description": "Site not found" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "integer" } } } } } } } }, "/v1/admin/sites/{id}/members": { "get": { "tags": [ "App settings: Sites" ], "summary": "List members of a site", "operationId": "get-v1-admin-sites-id-members", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `sites.admin.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "members": { "type": "array", "items": {} } } } } } }, "404": { "description": "Site not found" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "put": { "tags": [ "App settings: Sites" ], "summary": "Update the members of a site", "operationId": "put-v1-admin-sites-id-members", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `sites.admin.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "members": { "type": "array", "items": {} } } } } } }, "400": { "description": "Add a person or a group" }, "404": { "description": "Site not found" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user", "group" ] }, "role": { "type": "string" }, "id": { "type": "integer" } } } } } } } }, "/v1/admin/sites/{id}/members/{type}/{pid}": { "delete": { "tags": [ "App settings: Sites" ], "summary": "Delete a member", "operationId": "delete-v1-admin-sites-id-members-type-pid", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `sites.admin.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "user", "group" ] } }, { "name": "pid", "in": "path", "required": true, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "members": { "type": "array", "items": {} } } } } } }, "400": { "description": "Not a member" }, "404": { "description": "Site not found" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/sites/{id}": { "delete": { "tags": [ "App settings: Sites" ], "summary": "Delete a site (its libraries' files are purged by Drive after the bin period)", "operationId": "delete-v1-admin-sites-id", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `sites.admin.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "404": { "description": "Site not found" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/rmm/sites/{id}": { "put": { "tags": [ "RMM: sites, groups & enrolment" ], "summary": "Update an RMM site. Requires the GLOBAL_ADMIN role", "operationId": "put-v1-admin-rmm-sites-id", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.enrollment.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "name is required" }, "404": { "description": "Site not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "client_id": { "type": "integer" } }, "required": [ "name" ] } } } } }, "delete": { "tags": [ "RMM: sites, groups & enrolment" ], "summary": "Delete an RMM site. Requires the GLOBAL_ADMIN role", "operationId": "delete-v1-admin-rmm-sites-id", "description": "Requires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.enrollment.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "404": { "description": "Site not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/rmm/groups/{id}": { "put": { "tags": [ "RMM: sites, groups & enrolment" ], "summary": "Update an RMM device group", "operationId": "put-v1-admin-rmm-groups-id", "description": "Update an RMM device group. Requires the GLOBAL_ADMIN role.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.enrollment.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "name is required" }, "404": { "description": "Group not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } }, "required": [ "name" ] } } } } }, "delete": { "tags": [ "RMM: sites, groups & enrolment" ], "summary": "Delete an RMM device group", "operationId": "delete-v1-admin-rmm-groups-id", "description": "Delete an RMM device group. Requires the GLOBAL_ADMIN role.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.enrollment.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "404": { "description": "Group not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/rmm/enrollment-keys": { "get": { "tags": [ "RMM: sites, groups & enrolment" ], "summary": "List RMM device enrollment keys", "operationId": "get-v1-admin-rmm-enrollment-keys", "description": "List RMM device enrollment keys. Requires the GLOBAL_ADMIN role. Each key is resolved to its target site/group name for display.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.enrollment.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": {} } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "post": { "tags": [ "RMM: sites, groups & enrolment" ], "summary": "Create an RMM device enrollment key", "operationId": "post-v1-admin-rmm-enrollment-keys", "description": "Create an RMM device enrollment key. Requires the GLOBAL_ADMIN role. site_id is required; the key targets that site (and optionally a group + device type) for new agent installs.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.enrollment.manage`.", "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "id": { "type": "integer" }, "enrollment_key": { "type": "string" } } } } } }, "400": { "description": "site_id is required" }, "404": { "description": "Site not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "display_name": { "type": "string" }, "site_id": { "type": "integer" }, "group_id": { "type": "integer" }, "device_type": { "type": "string" } }, "required": [ "site_id" ] } } } } } }, "/v1/admin/rmm/enrollment-keys/{id}": { "put": { "tags": [ "RMM: sites, groups & enrolment" ], "summary": "Rename an enrollment key", "operationId": "put-v1-admin-rmm-enrollment-keys-id", "description": "Rename an enrollment key. Requires the GLOBAL_ADMIN role. Only display_name is editable — site_id/group_id/device_type are immutable post-creation (revoke and issue a new key to change scope).\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.enrollment.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Nothing to update" }, "404": { "description": "Key not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "display_name": { "type": "string" } }, "required": [ "display_name" ] } } } } }, "delete": { "tags": [ "RMM: sites, groups & enrolment" ], "summary": "Revoke an enrollment key", "operationId": "delete-v1-admin-rmm-enrollment-keys-id", "description": "Revoke an enrollment key. Requires the GLOBAL_ADMIN role.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `rmm.enrollment.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "404": { "description": "Key not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/delete-preview": { "get": { "tags": [ "Delete the organisation" ], "summary": "Preview what would be deleted if this tenant were purged", "operationId": "get-v1-admin-tenant-delete-preview", "description": "Preview what would be deleted if this tenant were purged. Requires the GLOBAL_ADMIN role. Read-only, no side effects — safe to call anytime.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/delete-request": { "post": { "tags": [ "Delete the organisation" ], "summary": "Request permanent deletion of this tenant", "operationId": "post-v1-admin-tenant-delete-request", "description": "Request permanent deletion of this tenant. Requires the GLOBAL_ADMIN role. confirm_text must exactly match the tenant's name. Doesn't delete anything immediately — emails a confirmation link (valid 24h) to the requester's recovery email; clicking it schedules a purge after a 14-day grace period, cancellable any time before then.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "preview": {} } } } } }, "400": { "description": "The organisation name you typed doesn't match" }, "404": { "description": "Tenant not found" }, "409": { "description": "A deletion request is already pending for this organisation" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "confirm_text": { "type": "string", "description": "The organisation's exact name, as a typed confirmation." } } } } } } } }, "/v1/admin/tenant/delete-confirm": { "get": { "tags": [ "Delete the organisation" ], "summary": "Confirm a pending tenant deletion via emailed token", "operationId": "get-v1-admin-tenant-delete-confirm", "description": "The link emailed after a deletion request. It needs no sign-in (the token is the proof), schedules the purge after the grace period, and redirects to the Admin Centre.\n\n\nRequires: None: public, or protected by a token in the address or body.", "parameters": [ { "name": "token", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "File, page or redirect" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/delete-cancel": { "post": { "tags": [ "Delete the organisation" ], "summary": "Cancel a pending tenant deletion request", "operationId": "post-v1-admin-tenant-delete-cancel", "description": "Cancel a pending tenant deletion request. Requires the GLOBAL_ADMIN role. Cancels any request still in pending_confirmation or pending_purge status.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "404": { "description": "No pending deletion request found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/tenant/delete-status": { "get": { "tags": [ "Delete the organisation" ], "summary": "Check for an active deletion request on this tenant", "operationId": "get-v1-admin-tenant-delete-status", "description": "Check for an active deletion request on this tenant. Requires the GLOBAL_ADMIN role. Powers the BRM-Admin danger-zone banner.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Role: `GLOBAL_ADMIN`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "request": { "type": "object", "nullable": true, "properties": { "status": { "type": "string", "enum": [ "pending_confirmation", "pending_purge", "cancelled", "completed" ] }, "requested_at": { "type": "string", "format": "date-time", "nullable": true }, "confirmed_at": { "type": "string", "format": "date-time", "nullable": true }, "purge_after": { "type": "string", "format": "date-time", "nullable": true } } } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/psa/templates": { "get": { "tags": [ "App settings: PSA" ], "summary": "List PSA email templates", "operationId": "get-v1-admin-psa-templates", "description": "List PSA email templates. Requires the GLOBAL_ADMIN role. This is the only place templates can be created/edited/deleted — PSA's own app keeps a read-only copy (GET /v1/app/psa/templates) so ticket.html's reply picker still works.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `psa.admin.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "templates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "tenant_id": { "type": "integer" }, "name": { "type": "string" }, "subject": { "type": "string", "nullable": true }, "body": { "type": "string" }, "category": { "type": "string", "nullable": true }, "is_active": { "type": "integer", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } } } } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "post": { "tags": [ "App settings: PSA" ], "summary": "Create a PSA email template", "operationId": "post-v1-admin-psa-templates", "description": "Create a PSA email template. Requires the GLOBAL_ADMIN role. name and body are required; category defaults to \"reply\".\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `psa.admin.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "template": {} } } } } }, "400": { "description": "name and body required" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "subject": {}, "body": {}, "category": {}, "is_active": { "type": "boolean" } }, "required": [ "name", "body" ] } } } } } }, "/v1/admin/psa/templates/{id}": { "post": { "tags": [ "App settings: PSA" ], "summary": "Update a PSA email template", "operationId": "post-v1-admin-psa-templates-id", "description": "Update a PSA email template. Requires the GLOBAL_ADMIN role.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `psa.admin.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "template": {} } } } } }, "404": { "description": "Template not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "subject": {}, "body": {}, "category": {}, "is_active": { "type": "boolean" } } } } } } } }, "/v1/admin/psa/templates/{id}/delete": { "post": { "tags": [ "App settings: PSA" ], "summary": "Delete a PSA email template", "operationId": "post-v1-admin-psa-templates-id-delete", "description": "Delete a PSA email template. Requires the GLOBAL_ADMIN role.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `psa.admin.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/psa/statuses": { "get": { "tags": [ "App settings: PSA" ], "summary": "List PSA statuses with their behaviours and ticket counts", "operationId": "get-v1-admin-psa-statuses", "description": "List PSA statuses with their behaviours and ticket counts. Requires the GLOBAL_ADMIN role. The defaults are added on first use.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `psa.admin.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "statuses": { "type": "array", "items": { "type": "object", "properties": { "ticket_count": { "type": "integer" } } } }, "groups": { "type": "array", "items": {} } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "post": { "tags": [ "App settings: PSA" ], "summary": "Add a PSA status. Requires the GLOBAL_ADMIN role", "operationId": "post-v1-admin-psa-statuses", "description": "Add a PSA status. Requires the GLOBAL_ADMIN role. Body name, group_key (new/open/waiting/paused/closed), color, and optional behaviours (on_enter_template_id, on_reply_status_id, auto_after_hours + auto_to_status_id, remind_after_hours + remind_template_id, pauses_sla, is_default).\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `psa.admin.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" } } } } } }, "400": { "description": "Give the status a name" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/psa/statuses/{id}": { "post": { "tags": [ "App settings: PSA" ], "summary": "Update a PSA status. Requires the GLOBAL_ADMIN role", "operationId": "post-v1-admin-psa-statuses-id", "description": "Update a PSA status. Requires the GLOBAL_ADMIN role. Same fields as creating one, plus sort_order. Changing the group moves its tickets' basic status with it.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `psa.admin.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "400": { "description": "Keep at least one turned-on status in the … group" }, "404": { "description": "Status not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "group_key": { "type": "string" }, "color": {}, "sort_order": { "type": "integer" } } } } } } } }, "/v1/admin/psa/statuses/{id}/delete": { "post": { "tags": [ "App settings: PSA" ], "summary": "Delete a PSA status. Requires the GLOBAL_ADMIN role", "operationId": "post-v1-admin-psa-statuses-id-delete", "description": "Delete a PSA status. Requires the GLOBAL_ADMIN role. Body { move_to } (a status id) is required when tickets are in it; they move there without emails.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `psa.admin.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "moved": { "type": "number" } } } } } }, "400": { "description": "Keep at least one turned-on status in the … group" }, "404": { "description": "Status not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "move_to": { "type": "number" } } } } } } } }, "/v1/admin/psa/workflows": { "get": { "tags": [ "App settings: PSA" ], "summary": "List PSA workflow rules", "operationId": "get-v1-admin-psa-workflows", "description": "List PSA workflow rules. Requires the GLOBAL_ADMIN role. Includes how often each rule ran and errored in the last 30 days.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `psa.admin.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "workflows": { "type": "array", "items": { "type": "object", "properties": { "runs_30d": { "type": "number" }, "errors_30d": { "type": "number" } } } }, "events": { "type": "array", "items": {} }, "actions": { "type": "array", "items": {} } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "post": { "tags": [ "App settings: PSA" ], "summary": "Create a PSA workflow rule", "operationId": "post-v1-admin-psa-workflows", "description": "Create a PSA workflow rule. Requires the GLOBAL_ADMIN role. Body name, trigger_event, trigger_config, match_mode (all/any), conditions [{field, op, value}], actions [{type, ...}], stop_further, is_active.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `psa.admin.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "trigger_event": { "type": "string" }, "trigger_config": { "type": "object" }, "conditions": { "type": "array", "items": {} }, "actions": { "type": "array", "items": {} }, "match_mode": { "type": "string" }, "stop_further": {}, "is_active": { "type": "boolean" } } } } } } } }, "/v1/admin/psa/workflows/{id}": { "post": { "tags": [ "App settings: PSA" ], "summary": "Update a PSA workflow rule", "operationId": "post-v1-admin-psa-workflows-id", "description": "Update a PSA workflow rule. Requires the GLOBAL_ADMIN role. Send the whole rule, or just { is_active } or { sort_order }.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `psa.admin.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "404": { "description": "Workflow not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "is_active": { "type": "boolean" }, "sort_order": { "type": "integer" } } } } } } } }, "/v1/admin/psa/workflows/{id}/delete": { "post": { "tags": [ "App settings: PSA" ], "summary": "Delete a PSA workflow rule and its run log", "operationId": "post-v1-admin-psa-workflows-id-delete", "description": "Delete a PSA workflow rule and its run log. Requires the GLOBAL_ADMIN role.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `psa.admin.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "404": { "description": "Workflow not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/psa/workflow-test": { "post": { "tags": [ "App settings: PSA" ], "summary": "Dry-run a PSA workflow rule against a ticket", "operationId": "post-v1-admin-psa-workflow-test", "description": "Dry-run a PSA workflow rule against a ticket. Requires the GLOBAL_ADMIN role. Body { rule, ticket_id }. Says whether the conditions match and why; nothing is changed.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `psa.admin.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": {} } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "rule": {}, "ticket_id": { "type": "integer" } } } } } } } }, "/v1/admin/psa/workflow-runs": { "get": { "tags": [ "App settings: PSA" ], "summary": "Recent PSA workflow runs (last 30 days)", "operationId": "get-v1-admin-psa-workflow-runs", "description": "Recent PSA workflow runs (last 30 days). Requires the GLOBAL_ADMIN role. Optional ?workflow_id, ?errors=1, ?limit (max 200).\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `psa.admin.manage`.", "parameters": [ { "name": "workflow_id", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "errors", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "runs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "tenant_id": { "type": "integer" }, "workflow_id": { "type": "integer" }, "ticket_id": { "type": "integer" }, "trigger_event": { "type": "string" }, "outcome": { "type": "string" }, "detail": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "workflow_name": { "type": "string" }, "ticket_subject": { "type": "string" } } } } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/psa/sla": { "get": { "tags": [ "App settings: PSA" ], "summary": "PSA business hours and SLA policies", "operationId": "get-v1-admin-psa-sla", "description": "PSA business hours and SLA policies. Requires the GLOBAL_ADMIN role. Also counts open tickets on each policy and how many are breached.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `psa.admin.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "hours": { "type": "array", "items": {} }, "policies": { "type": "array", "items": { "type": "object", "properties": { "open_count": { "type": "number" }, "breached": { "type": "number" } } } } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/psa/sla/hours": { "post": { "tags": [ "App settings: PSA" ], "summary": "Add PSA business hours", "operationId": "post-v1-admin-psa-sla-hours", "description": "Add PSA business hours. Requires the GLOBAL_ADMIN role. Body name, timezone, schedule {\"1\":[[\"09:00\",\"17:30\"]],…} (0 = Sunday), holidays [\"YYYY-MM-DD\"], bank_holidays (england-and-wales / scotland / northern-ireland or null).\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `psa.admin.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "timezone": {}, "schedule": {}, "holidays": { "type": "array", "items": {} }, "bank_holidays": { "type": "string", "enum": [ "england-and-wales", "scotland", "northern-ireland" ] } } } } } } } }, "/v1/admin/psa/sla/hours/{id}": { "post": { "tags": [ "App settings: PSA" ], "summary": "Update PSA business hours", "operationId": "post-v1-admin-psa-sla-hours-id", "description": "Update PSA business hours. Requires the GLOBAL_ADMIN role. Same body as adding them.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `psa.admin.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "404": { "description": "Business hours not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "timezone": {}, "schedule": {}, "holidays": { "type": "array", "items": {} }, "bank_holidays": { "type": "string", "enum": [ "england-and-wales", "scotland", "northern-ireland" ] } } } } } } } }, "/v1/admin/psa/sla/hours/{id}/delete": { "post": { "tags": [ "App settings: PSA" ], "summary": "Delete PSA business hours", "operationId": "post-v1-admin-psa-sla-hours-id-delete", "description": "Delete PSA business hours. Requires the GLOBAL_ADMIN role. Policies using them switch to round the clock.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `psa.admin.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "404": { "description": "Business hours not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/psa/sla/policies": { "post": { "tags": [ "App settings: PSA" ], "summary": "Add a PSA SLA policy", "operationId": "post-v1-admin-psa-sla-policies", "description": "Add a PSA SLA policy. Requires the GLOBAL_ADMIN role. Body name, business_hours_id, targets {priority: {response, resolution}} in minutes, warn_percent, customer_ids, queue_ids, type_ids (empty = all), is_active.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `psa.admin.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "targets": { "type": "array", "items": {} }, "is_active": { "type": "boolean" }, "business_hours_id": { "type": "number" }, "warn_percent": { "type": "integer" }, "customer_ids": { "type": "array", "items": {} }, "queue_ids": { "type": "array", "items": {} }, "type_ids": { "type": "array", "items": {} } } } } } } } }, "/v1/admin/psa/sla/policies/{id}": { "post": { "tags": [ "App settings: PSA" ], "summary": "Update a PSA SLA policy", "operationId": "post-v1-admin-psa-sla-policies-id", "description": "Update a PSA SLA policy. Requires the GLOBAL_ADMIN role. The whole policy, or just { is_active } or { sort_order }.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `psa.admin.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "404": { "description": "Policy not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "is_active": { "type": "boolean" }, "sort_order": { "type": "integer" } } } } } } } }, "/v1/admin/psa/sla/policies/{id}/delete": { "post": { "tags": [ "App settings: PSA" ], "summary": "Delete a PSA SLA policy", "operationId": "post-v1-admin-psa-sla-policies-id-delete", "description": "Delete a PSA SLA policy. Requires the GLOBAL_ADMIN role. Open tickets move to the next policy that covers them, if any.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `psa.admin.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "404": { "description": "Policy not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } }, "/v1/admin/psa/types": { "get": { "tags": [ "App settings: PSA" ], "summary": "List PSA ticket types", "operationId": "get-v1-admin-psa-types", "description": "List PSA ticket types. Requires the GLOBAL_ADMIN role. Includes inactive types.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `psa.admin.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "types": { "type": "array", "items": { "type": "object", "properties": { "ticket_count": { "type": "integer" } } } } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] }, "post": { "tags": [ "App settings: PSA" ], "summary": "Add a PSA ticket type", "operationId": "post-v1-admin-psa-types", "description": "Add a PSA ticket type. Requires the GLOBAL_ADMIN role. Body { name }.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `psa.admin.manage`.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" } } } } } }, "400": { "description": "Give the type a name" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } } } } } } } }, "/v1/admin/psa/types/{id}": { "post": { "tags": [ "App settings: PSA" ], "summary": "Rename, turn on/off or reorder a PSA ticket type", "operationId": "post-v1-admin-psa-types-id", "description": "Rename, turn on/off or reorder a PSA ticket type. Requires the GLOBAL_ADMIN role. Body { name?, is_active?, sort_order? }. Inactive types stay on existing tickets but can't be picked.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `psa.admin.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "400": { "description": "Give the type a name" }, "404": { "description": "Type not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "is_active": { "type": "boolean" }, "sort_order": { "type": "integer" } } } } } } } }, "/v1/admin/psa/types/{id}/delete": { "post": { "tags": [ "App settings: PSA" ], "summary": "Delete a PSA ticket type", "operationId": "post-v1-admin-psa-types-id-delete", "description": "Delete a PSA ticket type. Requires the GLOBAL_ADMIN role. Tickets of this type are left without one.\n\nRequires: Signed-in session, `X-API-Key`, or a Bramble app access token (`Authorization: Bearer`). Permission (any of): `psa.admin.manage`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "404": { "description": "Type not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "apiKey": [] }, { "session": [] }, { "bearer": [] } ] } } } }