AbuseZeroAbuseZero

Workspace settings

Read and change the workspace's name, icon, time zone, website, product type and data retention, follow setup progress and leave a workspace.

The workspace settings are the ones in the dashboard's Workspace settings → General and Data & privacy. Every change records the same audit event as the dashboard's. The endpoints on this page act on the workspace the request names: an API key's or machine client's own workspace, or the one in the AbuseZero-Workspace header for an OAuth token.

With an OAuth token, only the workspace owner and admins change settings, as in the dashboard. An API key or machine client has no person behind it, so its scope is its permission.

Examples on this page use a server client signed in with OAuth:

import { AbuseZero } from "abusezero/server";

const abusezero = new AbuseZero({
  accessToken: process.env.ABUSEZERO_ACCESS_TOKEN!,
  workspace: "95082035373438252677",
  outage: "throw",
});

The workspace settings object

{
  "object": "workspace_settings",
  "id": "95082035373438252677",
  "name": "Acme Analytics",
  "icon": { "updated_at": "2026-11-10T12:00:00.000Z" },
  "time_zone": "Europe/London",
  "website": "https://acme.example.com",
  "product_type": { "type": "b2b_saas" },
  "data_retention": { "evidence_days": 30, "max_days": 90, "options": [7, 30, 90] }
}
FieldTypeDescription
object"workspace_settings"The object type.
idstringThe workspace ID.
namestringThe workspace's name.
iconobject or nullWhen the workspace icon last changed, or null when it has none. The icon itself shows only in the dashboard.
time_zonestring or nullThe IANA time zone the dashboard and emails show times in, or null for UTC.
websitestring or nullThe product's website.
product_typeobject or nullWhat the workspace protects. See Product types.
data_retentionobjectHow many days evaluation evidence is kept (evidence_days), the longest period the plan allows (max_days) and the periods you can choose (options).

Product types

product_type.type is one of ai_app, media_generation, developer_tool, b2b_saas, consumer_app, marketplace, game or other. With other, product_type.other holds a short description of up to 100 characters.

Retrieve the workspace settings

MethodPathScopeIdempotency-Key
GET/v1/workspaceoperations:generalNot used

Also available as abusezero workspace get in the AbuseZero CLI, abusezero_get_workspace_settings on the AbuseZero MCP server and workspaceSettings() in the AbuseZero Node.js SDK.

Example

const settings = await abusezero.workspaceSettings();

Response

Returns 200 with the workspace settings object.

Update the workspace settings

Renames the workspace, or changes its website, product type or time zone. Send only the settings that change. Every value is checked first, so one that isn't valid changes nothing.

MethodPathScopeIdempotency-Key
PATCH/v1/workspaceoperations:configurationRequired

Also available as abusezero workspace update in the AbuseZero CLI, abusezero_update_workspace_settings on the AbuseZero MCP server and updateWorkspaceSettings() in the AbuseZero Node.js SDK.

Request body

FieldTypeRequiredLimitsDescription
namestringNo1 to 64 charactersThe workspace's new name.
websitestring or nullNoAn https addressThe product's website. null clears it.
product_typeobject or nullNoSee Product typesWhat the workspace protects. null clears it.
time_zonestringNoAn IANA time zoneSuch as America/New_York.

Example

await abusezero.updateWorkspaceSettings({ name: "Acme Analytics", time_zone: "Europe/London" }, "workspace-settings-2026-11-10");

Response

Returns 200 with the updated workspace settings object.

Errors

CodeStatusMeaning
INVALID_FIELD422The request has no setting to change, or a value is out of its limits.
INVALID_WEBSITE422website isn't a public https address.
INVALID_TIMEZONE422time_zone isn't a time zone AbuseZero recognizes.
PERMISSION_REQUIRED403With an OAuth token, the signed-in member isn't the workspace owner or an admin.

For every other code, see REST API errors.

Upload a workspace icon

Uploads a new icon. Like every file sent to AbuseZero, it's checked before it's used: the response names the upload, and the icon replaces the old one once its state is ready.

MethodPathScopeIdempotency-Key
PUT/v1/workspace/iconoperations:configurationRequired

Also available as abusezero workspace upload-icon in the AbuseZero CLI, abusezero_upload_workspace_icon on the AbuseZero MCP server and uploadWorkspaceIcon() in the AbuseZero Node.js SDK.

Request body

FieldTypeRequiredLimitsDescription
imagestringYesUp to 64 KB before encodingThe icon as a 256 × 256 WebP image, base64-encoded.

Example

import { readFile } from "node:fs/promises";

const image = (await readFile("icon.webp")).toString("base64");
const upload = await abusezero.uploadWorkspaceIcon(image, "workspace-icon-2026-11-10");

Response

Returns 200.

{
  "object": "workspace_icon_upload",
  "id": "73492810562018437529",
  "state": "pending"
}
FieldTypeDescription
object"workspace_icon_upload"The object type.
idstringThe upload ID.
statepending, ready or failedpending is still being checked. ready is the workspace's icon now. failed wasn't accepted: upload a 256 × 256 WebP image.

A newer upload, or removing the icon, ends an upload that's still pending.

Errors

CodeStatusMeaning
ICON_TOO_LARGE413The image is over 64 KB.
ICON_FORMAT422image is empty.
PERMISSION_REQUIRED403With an OAuth token, the signed-in member isn't the workspace owner or an admin.
RATE_LIMITED429Too many icon uploads in the workspace. Wait for the number of seconds in Retry-After.

Retrieve an icon upload

MethodPathScopeIdempotency-Key
GET/v1/workspace/icon/uploads/{id}operations:generalNot used

Also available as abusezero workspace icon-upload in the AbuseZero CLI, abusezero_get_workspace_icon_upload on the AbuseZero MCP server and workspaceIconUpload() in the AbuseZero Node.js SDK.

Returns 200 with the upload. Check it every few seconds until state is ready or failed. An unknown upload returns ICON_UPLOAD_NOT_FOUND (404).

Remove the workspace icon

MethodPathScopeIdempotency-Key
DELETE/v1/workspace/iconoperations:configurationRequired

Also available as abusezero workspace remove-icon in the AbuseZero CLI, abusezero_remove_workspace_icon on the AbuseZero MCP server and removeWorkspaceIcon() in the AbuseZero Node.js SDK.

Returns 200 with the workspace settings object, with icon set to null.

Change data retention

Sets how many days evaluation evidence is kept. Shortening it deletes older evidence and analytics history for good. Claim history stays, so eligibility for your benefits isn't affected. The dashboard asks you to type a confirmation word first; over the API, the scope is the permission.

MethodPathScopeIdempotency-Key
PUT/v1/workspace/data-retentionoperations:managementRequired

Also available as abusezero workspace set-retention in the AbuseZero CLI, abusezero_set_data_retention on the AbuseZero MCP server and setDataRetention() in the AbuseZero Node.js SDK.

No API key holds operations:management. Use an OAuth sign-in or a machine client.

Request body

FieldTypeRequiredLimitsDescription
evidence_daysintegerYesOne of data_retention.optionsDays to keep evaluation evidence.

Example

await abusezero.setDataRetention(30, "retention-2026-11-10");

Response

Returns 200 with the updated workspace settings object.

Errors

CodeStatusMeaning
RETENTION_UNAVAILABLE422The plan doesn't include this period. Choose one of data_retention.options.
KEY_PERMISSION_DENIED403The request used an API key. Use an OAuth sign-in or a machine client.
PERMISSION_REQUIRED403With an OAuth token, the signed-in member isn't the workspace owner or an admin.

Setup progress

Setup progress is what the dashboard's Get started guide shows: four steps, each done once the workspace has it.

{
  "object": "setup_progress",
  "steps": [
    { "step": "benefit", "done": true },
    { "step": "server_key", "done": true },
    { "step": "first_evaluation", "done": false },
    { "step": "browser_script", "done": false }
  ],
  "complete": false,
  "finished": true,
  "dismissed": false
}
FieldTypeDescription
object"setup_progress"The object type.
stepsarraybenefit (create a benefit), server_key (create a server key), first_evaluation (send your first evaluation) and browser_script (add the browser script), each with done.
completebooleanEvery step is done.
finishedbooleanThe owner finished setting up the workspace, with its website, product type and time zone.
dismissedboolean or nullGet started no longer opens by itself for the signed-in person. null for an API key or machine client.

Retrieve setup progress

MethodPathScopeIdempotency-Key
GET/v1/workspace/setupoperations:generalNot used

Also available as abusezero workspace setup in the AbuseZero CLI, abusezero_get_setup_progress on the AbuseZero MCP server and setupProgress() in the AbuseZero Node.js SDK.

Returns 200 with setup progress.

Finish setting up

Saves the website, product type and time zone the owner gives, and ends the dashboard's Finish setting up prompt. It runs once: a second call changes nothing. Only the workspace owner can finish setting up, so it needs the owner's OAuth sign-in.

MethodPathScopeIdempotency-Key
POST/v1/workspace/setup/finishoperations:generalRequired

Also available as abusezero workspace finish-setup in the AbuseZero CLI, abusezero_finish_setup on the AbuseZero MCP server and finishSetup() in the AbuseZero Node.js SDK.

FieldTypeRequiredDescription
websitestring or nullNoThe product's website.
product_typeobject or nullNoSee Product types.
time_zonestring or nullNoAn IANA time zone.

Returns 201 with setup progress. With an API key or machine client, returns MEMBER_SIGN_IN_REQUIRED (403); with anyone but the owner, PERMISSION_REQUIRED (403).

Dismiss Get started

Stops Get started opening by itself for the signed-in person, as its Never show this again does. It needs a person's OAuth sign-in.

MethodPathScopeIdempotency-Key
POST/v1/workspace/setup/dismissoperations:generalRequired

Also available as abusezero workspace dismiss-setup in the AbuseZero CLI, abusezero_dismiss_setup_guide on the AbuseZero MCP server and dismissSetupGuide() in the AbuseZero Node.js SDK.

Returns 201 with setup progress.

Leave the workspace

Ends the signed-in person's access to the workspace. Their OAuth sign-ins for it end too, including the one that sent this request. The owner can't leave: they transfer ownership or delete the workspace in the dashboard. It needs a person's OAuth sign-in.

MethodPathScopeIdempotency-Key
POST/v1/workspace/leaveoperations:generalRequired

Also available as abusezero workspace leave in the AbuseZero CLI, abusezero_leave_workspace on the AbuseZero MCP server and leaveWorkspace() in the AbuseZero Node.js SDK.

Response

Returns 201.

{
  "object": "workspace_left",
  "workspace": "95082035373438252677"
}

Errors

CodeStatusMeaning
OWNER_CANNOT_LEAVE409The signed-in person owns the workspace.
MEMBER_SIGN_IN_REQUIRED403The request used an API key or machine client.

How is this guide?

Last updated on