CloudrawAPI v0
Menu

API reference

Workspace

Your workspace record: name, plan limits and usage.

Get the workspace

GET/v0/tenants/{tenant_id}

read-only token

Returns your workspace: its name, plan limits, current usage and provisioning status. A cheap call that is handy as a token check.

Token: read-only or full access · Created by: owner or security admin

Path parameters

  • tenant_idstringrequired

    Your workspace id (Settings → Workspace in the console; it is also in every console URL).

    Example: tq7x2m9k4ab

Responses

200 The workspace.

application/json

  • idstringrequired

    Workspace id.

  • namestringrequired

    Display name, 1-80 characters.

  • tierstring

    Hosting tier (shared for most workspaces).

  • external_refstring | null

    Your own reference for this workspace, if set by Cloudraw at creation.

  • quotasobject

    Plan limits. Changed by Cloudraw (billing), not through the API.

    quotas fields
    • max_usersinteger

      Seats in the plan.

    • max_devicesinteger
    • max_connectionsinteger
    • max_connectorsinteger
    • max_private_networksinteger
  • usageobject

    What the workspace uses now.

    usage fields
    • usersinteger
    • devicesinteger
    • connectionsinteger
    • connectorsinteger
    • private_networksinteger
  • statusobject
    status fields
    • phasestring

      ready when the workspace is fully provisioned.

    • observed_atstring (date-time)
    • messagestring | null
  • versionintegerrequired

    Increases on every change; send it as If-Match on PATCH to avoid overwriting a concurrent change.

  • created_atstring (date-time)
401 unauthorized invalid-token token-expired

unauthorized: No Authorization: Bearer crw_… header was sent.

invalid-token: The token is unknown or was revoked.

token-expired: The token is past its expiry date. Create a new one.

403 insufficient-role tenant-assertion-mismatch

insufficient-role: The token's role ceiling does not allow this call.

tenant-assertion-mismatch: The token belongs to another workspace than {tenant_id}.

404 tenant-not-found

tenant-not-found: No workspace with this id.

curl
curl -sS -X GET "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab" \
  -H "Authorization: Bearer $CLOUDRAW_TOKEN"
PowerShell
$headers = @{ Authorization = "Bearer $env:CLOUDRAW_TOKEN" }
Invoke-RestMethod -Method Get -Uri "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab" -Headers $headers
Python
import os, uuid, requests

r = requests.get(
    "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab",
    headers={"Authorization": f"Bearer {os.environ['CLOUDRAW_TOKEN']}"},
    timeout=30,
)
r.raise_for_status()
print(r.json())
Node.js
const res = await fetch("https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CLOUDRAW_TOKEN}`,
  },
});
if (!res.ok) throw new Error((await res.json()).code);
console.log(await res.json());
Response 200 · application/json
{
  "id": "tq7x2m9k4ab",
  "name": "Northwind Logistics",
  "tier": "shared",
  "external_ref": null,
  "quotas": {
    "max_users": 50,
    "max_devices": 100,
    "max_connections": 25,
    "max_connectors": 5,
    "max_private_networks": 3
  },
  "usage": {
    "users": 18,
    "devices": 23,
    "connections": 7,
    "connectors": 2,
    "private_networks": 1
  },
  "status": {
    "phase": "ready",
    "observed_at": "2026-10-01T08:00:00.000Z",
    "message": null
  },
  "version": 42,
  "created_at": "2026-09-14T10:12:00.000Z"
}

Rename the workspace

PATCH/v0/tenants/{tenant_id}

full-access token

Changes the workspace display name. Plan limits (quotas) cannot be changed with an API token. Send If-Match: <version> to fail instead of overwriting a change made in the meantime.

Token: full access · Created by: owner

Path parameters

  • tenant_idstringrequired

    Your workspace id (Settings → Workspace in the console; it is also in every console URL).

    Example: tq7x2m9k4ab

Request body application/json

  • namestringrequired

    New display name, 1-80 characters, without < > " ' & \`.

Responses

200 The updated workspace.

application/json

  • idstringrequired

    Workspace id.

  • namestringrequired

    Display name, 1-80 characters.

  • tierstring

    Hosting tier (shared for most workspaces).

  • external_refstring | null

    Your own reference for this workspace, if set by Cloudraw at creation.

  • quotasobject

    Plan limits. Changed by Cloudraw (billing), not through the API.

    quotas fields
    • max_usersinteger

      Seats in the plan.

    • max_devicesinteger
    • max_connectionsinteger
    • max_connectorsinteger
    • max_private_networksinteger
  • usageobject

    What the workspace uses now.

    usage fields
    • usersinteger
    • devicesinteger
    • connectionsinteger
    • connectorsinteger
    • private_networksinteger
  • statusobject
    status fields
    • phasestring

      ready when the workspace is fully provisioned.

    • observed_atstring (date-time)
    • messagestring | null
  • versionintegerrequired

    Increases on every change; send it as If-Match on PATCH to avoid overwriting a concurrent change.

  • created_atstring (date-time)
400 invalid-name

invalid-name: The name is empty, longer than 80 characters or contains a forbidden character.

401 unauthorized invalid-token token-expired

unauthorized: No Authorization: Bearer crw_… header was sent.

invalid-token: The token is unknown or was revoked.

token-expired: The token is past its expiry date. Create a new one.

403 platform-scope-required insufficient-scope insufficient-role tenant-assertion-mismatch

platform-scope-required: The body tried to change quotas (plan limits are changed by Cloudraw).

insufficient-scope: The token is read-only and this call changes something.

insufficient-role: The token's role ceiling does not allow this call.

tenant-assertion-mismatch: The token belongs to another workspace than {tenant_id}.

404 tenant-not-found

tenant-not-found: No workspace with this id.

409 version-conflict

version-conflict: If-Match does not match the current version.

503 busy

busy: Cloudraw is switching servers or cannot save right now. Retry after Retry-After seconds.

curl
curl -sS -X PATCH "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab" \
  -H "Authorization: Bearer $CLOUDRAW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Northwind Logistics IL"
}'
PowerShell
$body = @'
{
  "name": "Northwind Logistics IL"
}
'@
$headers = @{ Authorization = "Bearer $env:CLOUDRAW_TOKEN" }
Invoke-RestMethod -Method Patch -Uri "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab" -Headers $headers -ContentType "application/json" -Body $body
Python
import os, uuid, requests

r = requests.patch(
    "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab",
    headers={"Authorization": f"Bearer {os.environ['CLOUDRAW_TOKEN']}"},
    json={
        "name": "Northwind Logistics IL"
    },
    timeout=30,
)
r.raise_for_status()
print(r.json())
Node.js
const res = await fetch("https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.CLOUDRAW_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Northwind Logistics IL"
  }),
});
if (!res.ok) throw new Error((await res.json()).code);
console.log(await res.json());
Response 200 · application/json
{
  "id": "tq7x2m9k4ab",
  "name": "Northwind Logistics IL",
  "tier": "shared",
  "external_ref": null,
  "quotas": {
    "max_users": 50,
    "max_devices": 100,
    "max_connections": 25,
    "max_connectors": 5,
    "max_private_networks": 3
  },
  "usage": {
    "users": 18,
    "devices": 23,
    "connections": 7,
    "connectors": 2,
    "private_networks": 1
  },
  "status": {
    "phase": "ready",
    "observed_at": "2026-10-01T08:00:00.000Z",
    "message": null
  },
  "version": 43,
  "created_at": "2026-09-14T10:12:00.000Z"
}

Get monthly usage

GET/v0/tenants/{tenant_id}/usage

read-only token

What the workspace used in one month: peak and average seats, monthly active users, devices, connectors, apps, private networks, recording and audit log storage, sign-in SMS, remote assist, protected file scans, web filtering and bandwidth (a lower bound from connector reports, not a meter).Cloudraw measures every hour and keeps one row per day; when a month is over it is closed into final figures (state: closed). The current month is answered with the figures so far (state: open). These are the numbers your invoice is based on.

Token: read-only or full access · Created by: owner

Path parameters

  • tenant_idstringrequired

    Your workspace id (Settings → Workspace in the console; it is also in every console URL).

    Example: tq7x2m9k4ab

Query parameters

  • monthstring

    Month, YYYY-MM (UTC). Default: the current month.

    Example: 2026-09

  • dailystring

    1 adds the day rows of the month (daily).

Responses

200 The month.

application/json

  • tenant_idstringrequired

    Workspace id.

  • monthstringrequired

    YYYY-MM (UTC).

  • statestringrequired

    open = the current month, figures so far; closed = final figures written at month close; not_closed = a past month whose close has not run yet (figures computed from the daily rows).

    One of: open, closed, not_closed.

  • closed_atstring | null (date-time)

    When the month was closed (the latest run).

  • close_runsinteger

    How many times the month was closed. Closing again recomputes the same figures from the same daily rows.

  • days_sampledinteger

    Days of the month with a measurement.

  • days_in_monthinteger
  • first_daystring | null
  • last_daystring | null
  • seats_peakinteger

    Highest number of people holding a seat on any day (the plan seat count).

  • seats_avgnumber

    Average seats over the days sampled.

  • seats_lastinteger

    Seats on the last day sampled.

  • active_usersinteger

    Monthly active users: distinct people who signed in, used an app or had a Cloudraw Connect device online during the month.

  • active_users_peak_dayinteger

    Most active people on one day.

  • devices_peakinteger
  • devices_lastinteger
  • connectors_peakinteger
  • connectors_lastinteger
  • connections_peakinteger

    Apps (connections).

  • connections_lastinteger
  • private_networks_peakinteger
  • private_networks_lastinteger
  • recording_gb_maxnumber

    Recording storage, highest day (GB, 10^9 bytes).

  • recording_gb_avgnumber

    Recording storage, average over the days sampled (GB).

  • recording_count_maxinteger
  • audit_gb_maxnumber

    Audit and access log storage, highest day (GB).

  • audit_gb_avgnumber
  • sms_sentinteger

    Sign-in SMS codes sent.

  • sms_failedinteger

    Sign-in SMS codes that could not be sent.

  • remote_assist_sessionsinteger

    Remote assist sessions requested.

  • remote_assist_minutesinteger

    Minutes of active remote assist.

  • remote_assist_techniciansinteger

    Distinct admins who started a remote assist session.

  • file_scans_totalinteger
  • file_scansobject

    Protected file server decisions by outcome (every operation except folder listings).

    file_scans fields
    • okinteger
    • blockedinteger
    • quarantinedinteger
    • heldinteger
    • deniedinteger
    • errorinteger
  • web_filter_devices_peakinteger

    Devices with web filtering on (module granted, filtering switched on, a profile applied).

  • web_filter_devices_lastinteger
  • secure_browser_hoursnumber

    Secure Browser session hours. 0 until Secure Browser is available (secure_browser_metered: false).

  • secure_browser_meteredboolean
  • bandwidth_bytes_lower_boundinteger

    Bytes in both directions that your connectors reported per session. A LOWER BOUND, not a meter: traffic of sessions whose connector does not report bytes is missing, so it is always at or below what your own meters show. Show it with bandwidth_label ("lower bound, from connector reports").

  • bandwidth_in_bytes_lower_boundinteger

    Lower bound of bytes from apps to users (connector reports).

  • bandwidth_out_bytes_lower_boundinteger

    Lower bound of bytes from users to apps (connector reports).

  • bandwidth_sourcestring

    connector_session_reports: only sessions your connectors report bytes for (a lower bound). overlay_fabric_usage: every byte through Cloudraw (coming).

    One of: connector_session_reports, overlay_fabric_usage.

  • bandwidth_labelstring

    Text to show next to the bandwidth figures on any page or invoice: lower bound, from connector reports.

  • dailyarray of object

    With daily=1 only: the day rows of the month.

    daily fields
    • daystringrequired

      UTC day, YYYY-MM-DD.

    • seatsinteger
    • active_usersinteger
    • devicesinteger
    • connectorsinteger
    • connectionsinteger
    • private_networksinteger
    • recording_bytesinteger
    • recording_countinteger
    • audit_bytesinteger
    • audit_rowsinteger
    • sms_sentinteger
    • sms_failedinteger
    • ra_sessionsinteger
    • ra_minutesinteger
    • ra_techniciansinteger
    • file_scansobject

      Protected file server decisions by outcome (every operation except folder listings).

      file_scans fields
      • okinteger
      • blockedinteger
      • quarantinedinteger
      • heldinteger
      • deniedinteger
      • errorinteger
    • file_scans_totalinteger
    • web_filter_devicesinteger
    • secure_browser_hoursnumber
    • bandwidth_bytes_lower_boundinteger

      Lower bound, from connector reports.

    • bandwidth_in_bytes_lower_boundinteger
    • bandwidth_out_bytes_lower_boundinteger
    • samplesinteger

      Measurements taken that day.

    • sampled_atstring (date-time)

      Last measurement.

400 invalid-month month-in-future

invalid-month: month is not YYYY-MM with a month from 01 to 12.

month-in-future: month has not started yet.

401 unauthorized invalid-token token-expired

unauthorized: No Authorization: Bearer crw_… header was sent.

invalid-token: The token is unknown or was revoked.

token-expired: The token is past its expiry date. Create a new one.

403 insufficient-role tenant-assertion-mismatch

insufficient-role: The token's role ceiling does not allow this call.

tenant-assertion-mismatch: The token belongs to another workspace than {tenant_id}.

404 tenant-not-found

tenant-not-found: No workspace with this id.

503 usage-unavailable

usage-unavailable: Usage figures cannot be read right now. Retry in a minute.

curl
curl -sS -X GET "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/usage" \
  -H "Authorization: Bearer $CLOUDRAW_TOKEN"
PowerShell
$headers = @{ Authorization = "Bearer $env:CLOUDRAW_TOKEN" }
Invoke-RestMethod -Method Get -Uri "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/usage" -Headers $headers
Python
import os, uuid, requests

r = requests.get(
    "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/usage",
    headers={"Authorization": f"Bearer {os.environ['CLOUDRAW_TOKEN']}"},
    timeout=30,
)
r.raise_for_status()
print(r.json())
Node.js
const res = await fetch("https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/usage", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CLOUDRAW_TOKEN}`,
  },
});
if (!res.ok) throw new Error((await res.json()).code);
console.log(await res.json());
Response 200 · application/json
{
  "tenant_id": "tq7x2m9k4ab",
  "month": "2026-09",
  "state": "closed",
  "closed_at": "2026-10-01T06:00:12.000Z",
  "close_runs": 1,
  "days_sampled": 30,
  "days_in_month": 30,
  "first_day": "2026-09-01",
  "last_day": "2026-09-30",
  "seats_peak": 48,
  "seats_avg": 46.2,
  "seats_last": 47,
  "active_users": 41,
  "active_users_peak_day": 33,
  "devices_peak": 61,
  "devices_last": 60,
  "connectors_peak": 2,
  "connectors_last": 2,
  "connections_peak": 9,
  "connections_last": 9,
  "private_networks_peak": 1,
  "private_networks_last": 1,
  "recording_gb_max": 18.4,
  "recording_gb_avg": 15.9,
  "recording_count_max": 812,
  "audit_gb_max": 0.21,
  "audit_gb_avg": 0.18,
  "sms_sent": 130,
  "sms_failed": 2,
  "remote_assist_sessions": 14,
  "remote_assist_minutes": 236,
  "remote_assist_technicians": 3,
  "file_scans_total": 5230,
  "file_scans": {
    "ok": 5190,
    "blocked": 31,
    "quarantined": 2,
    "held": 1,
    "denied": 6,
    "error": 0
  },
  "web_filter_devices_peak": 55,
  "web_filter_devices_last": 55,
  "secure_browser_hours": 0,
  "secure_browser_metered": false,
  "bandwidth_bytes_lower_bound": 110269022468,
  "bandwidth_in_bytes_lower_bound": 98234511234,
  "bandwidth_out_bytes_lower_bound": 12034511234,
  "bandwidth_source": "connector_session_reports",
  "bandwidth_label": "lower bound, from connector reports"
}