Workspace

Get current workspace

Returns the workspace associated with the X-Api-Key request header. Workspace IDs do not need to be sent in request bodies. is_beta is a read-only workspace flag, disabled by default. Contact the platform to enable access; neither PATCH nor metadata can change it.

GEThttps://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 parameters

Headers

X-Api-Key

stringrequired

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

Request body

This endpoint does not require a JSON request body.

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": {
      "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.

When it occurs: Applies when a non-empty request body is sent with a Content-Type other than application/json.

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": "Content-Type must be application/json"
  }
}

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"
  }
}

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"
  }
}

get_workspace_failed · 41000 · 500

Get current workspace: the service could not produce a valid query result.

What to do: Keep request_id and check the requested identifiers and account access. Retry this read only after checking the cause; a failed query does not prove an empty or missing resource.

Illustrative JSON; message varies with the actual cause · 500 · 41000

{
  "request_id": "req_example",
  "error": {
    "code": "get_workspace_failed",
    "numeric_code": "41000",
    "message": "Failed to get workspace"
  }
}