Workspace

Update current workspace

Updates the workspace name and status. Both name and status are required; status accepts active or inactive, and inactive prevents every API key in the workspace from authenticating. Omit metadata to retain its current value, send metadata={} to clear it, and do not send null. is_beta is a read-only workspace flag, disabled by default. Contact the platform to enable access; neither PATCH nor metadata can change it.

PATCHhttps://api.unifyport.ai/v1/workspace

Supported channels

all

Before you call

Use a server-side X-Api-Key for the workspace that owns the resource. Replace every placeholder before running a sample.

Request

curl -X PATCH "https://api.unifyport.ai/v1/workspace" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Production Workspace",
  "status": "active",
  "metadata": {
    "region": "global",
    "env": "production"
  }
}'

Request parameters

Headers

X-Api-Key

stringrequired

Workspace API key. The workspace is resolved from this header.

Content-Type

stringrequired

Use application/json when sending a JSON request body.

Request body

name

stringrequired

Workspace display name.

minLength: 1

status

stringrequired

Workspace status: active or inactive. An inactive workspace prevents all of its API keys from authenticating.

enum: active, inactive

metadata

object

Workspace metadata. On PATCH, omit it to retain the current value or send {} to clear it; null is invalid.

Understand the result

Read the documented response fields and HTTP status, then follow the related operations for your next step.

Response 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "name": "Production Workspace",
    "status": "active",
    "metadata": {
      "region": "global",
      "env": "production"
    },
    "account_quota": 10,
    "account_quota_used": 1,
    "account_quota_unlimited": false,
    "is_beta": false
  }
}

Response body

is_beta

boolean

is_beta is a read-only workspace flag, disabled by default. Contact the platform to enable access; neither PATCH nor metadata can change it.

name

string

Workspace display name.

status

string

Workspace status: active or inactive. Inactive workspaces reject authentication by all of their API keys.

enum: active, inactive

metadata

object

Your own environment labels stored on the workspace.

account_quota

integer

Current effective read-only account capacity, including the free quota and paid quota that is still valid, without subtracting used accounts; expired paid quota is not counted.

format: uint64

account_quota_used

integer

Read-only account quota currently in use. Creating an account consumes quota; deleting it releases quota. Accounts awaiting authorization, stopped, or disconnected still count. After paid quota expires, usage may exceed account_quota; the actual usage is returned.

format: uint64

account_quota_unlimited

boolean

Compatibility read-only field; the current quota mode always returns false. Use account_quota as the account capacity.

Responses

200

200 OK

Request succeeded. See the example response body.

400

Bad Request

The request body, path, or parameters are invalid.

401

Unauthorized

The X-Api-Key header is missing or invalid.

403

Forbidden

The request is authenticated but is not allowed.

404

Not Found

The requested resource was not found. Check error.code and the current operation.

500

Internal Server Error

The service encountered an unexpected error.

If the request fails

Inspect HTTP status and error.code/numeric_code, and keep request_id for diagnosis. Correct invalid parameters, complete required authorization or check runtime state as appropriate. Confirm the outcome before retrying a send or another write. Error reference

Read HTTP status, error.code and error.numeric_code together in the context of the current operation. Numeric codes are strings. Keep request_id for diagnosis; it is not an idempotency key or a task identifier.

invalid_request · 10000 · 400

Check the JSON body and required fields.

What to do: Correct the parameters for this operation and channel before requesting again. Repeating an unchanged invalid request will not resolve the error.

Illustrative JSON; message varies with the actual cause · 400 · 10000

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_request",
    "numeric_code": "10000",
    "message": "Invalid request parameters"
  }
}

invalid_target_workspace · 11003 · 400

The workspace override target is empty or malformed. Remove the override header and use the API key belonging to the intended workspace.

When it occurs: Applies when the request includes the X-Workspace-Id workspace override header.

What to do: Correct the parameters for this operation and channel before requesting again. Repeating an unchanged invalid request will not resolve the error.

Illustrative JSON; message varies with the actual cause · 400 · 11003

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_target_workspace",
    "numeric_code": "11003",
    "message": "Invalid target workspace"
  }
}

update_workspace_failed · 41001 · 400

The operation was rejected. Check the request and keep request_id for diagnosis.

What to do: Read the current resource state and confirm the previous outcome before repeating this change. Keep request_id; do not automatically repeat a write whose outcome is unknown.

Illustrative JSON; message varies with the actual cause · 400 · 41001

{
  "request_id": "req_example",
  "error": {
    "code": "update_workspace_failed",
    "numeric_code": "41001",
    "message": "Failed to update workspace"
  }
}

invalid_api_key · 11001 · 401

Check whether the API key is correct and enabled.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

Illustrative JSON; message varies with the actual cause · 401 · 11001

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_api_key",
    "numeric_code": "11001",
    "message": "Invalid API key"
  }
}

missing_api_key · 11000 · 401

Add the X-Api-Key header.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

Example · 401 · 11000

{
  "request_id": "req_xxx",
  "error": {
    "code": "missing_api_key",
    "numeric_code": "11000",
    "message": "Missing X-Api-Key header"
  }
}

workspace_override_forbidden · 11002 · 403

The request attempts a workspace override that this API key is not allowed to use. Remove the override header and use the API key belonging to the intended workspace.

When it occurs: Applies when the request includes the X-Workspace-Id workspace override header.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

Illustrative JSON; message varies with the actual cause · 403 · 11002

{
  "request_id": "req_example",
  "error": {
    "code": "workspace_override_forbidden",
    "numeric_code": "11002",
    "message": "Workspace override is not allowed"
  }
}

target_workspace_not_found · 11004 · 404

The overridden workspace was not found or is unavailable. Verify workspace ownership, remove the override header and use the intended workspace’s API key; repeated requests do not grant access.

When it occurs: Applies when the request includes the X-Workspace-Id workspace override header.

What to do: Check the target identifier, resource ownership and current workspace. Do not treat a confirmed missing or inaccessible target as a temporary service failure to retry automatically.

Illustrative JSON; message varies with the actual cause · 404 · 11004

{
  "request_id": "req_example",
  "error": {
    "code": "target_workspace_not_found",
    "numeric_code": "11004",
    "message": "Target workspace not found"
  }
}