​

workspaces

orc workspaces creates and inspects Workspaces and manages settings, member access, and measurement pause/resume. You can also check initial setup progress, measurement countries and languages, model configuration, and revision history.

Authentication is required. Settings operations for the current Workspace use the CLI selection; operations targeting a particular Workspace take its ID. Credentials for organization capacity, creation, and access grants have a different scope from credentials that read an individual Workspace’s measurement data.

List accessible Workspaces.

Retrieves the saved initial setup checkpoint. Use --wait to wait until setup and first observation reach a terminal state, and --timeout and --poll-interval to control the wait duration and polling interval. The default polling interval is 5s.

Retrieves saved measurement countries and languages, defaults, selectable codes, and contract limits including add-on capacity.

Updates country and language arrays. Each array replaces the whole stored value, and its first entry becomes the default. Include existing values when adding entries. Limits are checked against countries and languages used by active prompts too; this operation does not purchase add-on capacity.

Configured measurement countries. The first entry is the default. Limited by the workspace contract and add-ons.; csv

Type: string. Optional.

Configured measurement languages. The first entry is the default. Base languages count toward the workspace allowance.; csv

Type: string. Optional.

Workspace measurement target country; browser runs use managed proxy geolocation.

Type: string. Optional.

Workspace measurement language applied to subsequent measurements.

Type: string. Optional.

Lists accessible Workspaces. Include archived entries with --include-archived, or brand, monitoring configuration, and production prompt entitlement summaries with --include-management.

Include archived workspaces in the response.; enum: true|false

Type: string. Optional.

Include brand, monitoring configuration, and production prompt entitlement summaries for accessible workspaces.; enum: true|false

Type: string. Optional.

Creates a Workspace from its name and other settings. A supplied brand is registered as an active owned brand without separate activation. setup_mode of empty skips candidate generation and measurement, suggestions stops after generation, and measure generates and measures. Activate manually created draft prompts before measuring them.

Retry identity for operations that support idempotency. Use a unique key for each new operation, and reuse it only when retrying the same HTTP method, path, query values and exact request body. JSON whitespace changes can count as a different body. Keys contain 1–255 characters after trimming and expire after 24 hours. A completed JSON response is replayed without repeating the operation. A different request using the same key returns 409 idempotency_error. An in-progress request returns 409 idempotency_in_progress with Retry-After: 2. Whether this header is required depends on the operation.

Type: string. Optional.

(required) Workspace display name after trimming surrounding whitespace. Must contain 1 to 120 characters.; max 120 chars

Type: string. Optional.

Preferred workspace URL slug. Omit or send an empty string to derive it from name. The server normalizes to lowercase letters, digits and hyphens and resolves conflicts within the organization.

Type: string. Optional.

Workspace type. Omission creates a team workspace.; enum: personal|team

Type: string. Optional.

Optional client-facing label. Surrounding whitespace is removed; omitted, null or empty values store no label.; (use "null" or "reset" to clear)

Type: string. Optional.

Commercial workspace purpose, defaulting to client in the extended flow. Supplying this field selects extended creation. pitch requires an agency organization and consumes monthly and active pitch quotas.; enum: client|pitch

Type: string. Optional.

Creation stopping point. A supplied owned brand is initialized active in every mode; no separate brand activation is required. Brand readiness does not start measurement. empty skips setup generation and measurement; brand is optional. suggestions generates review candidates without starting measurement. measure generates and measures. Omission uses measure if any extended setup field is present; otherwise creation is empty. Pitch quotas and seven-day expiry begin at creation in every mode.; enum: empty|suggestions|measure

Type: string. Optional.

Managed brand to initialize. Required for suggestions and measure. Optional for empty; when provided, both name and domain are required. Supplying brand without setup_mode starts the measure flow.; (JSON object, e.g. '{"custom_id":"x"}')

Type: string. Optional.

Two-letter default observation country code. Trimmed and uppercased. Defaults to JP in the extended flow. Supplying this field selects extended creation even without setup_mode.

Type: string. Optional.

Default observation language code, optionally with a regional suffix. Trimmed and lowercased, for example ja or en-us. Defaults to ja in the extended flow. Supplying this field selects extended creation even without setup_mode.

Type: string. Optional.

Retrieves organization Workspace capacity. A Workspace-scoped key receives 403 insufficient_scope; this does not mean the capacity is empty.

Retrieves information for a Workspace ID.

Updates a Workspace’s name, URL slug, appearance, and other settings by ID. Also supports converting a non-archived pitch Workspace to purpose: client.

Retry identity for operations that support idempotency. Use a unique key for each new operation, and reuse it only when retrying the same HTTP method, path, query values and exact request body. JSON whitespace changes can count as a different body. Keys contain 1–255 characters after trimming and expire after 24 hours. A completed JSON response is replayed without repeating the operation. A different request using the same key returns 409 idempotency_error. An in-progress request returns 409 idempotency_in_progress with Retry-After: 2. Whether this header is required depends on the operation.

Type: string. Optional.

Set this workspace as the organization default. Must be true and the only field in the body. Requires a human organization owner or admin; machine credentials cannot perform this change.; enum: true

Type: string. Optional.

Replacement workspace display name. Omit to retain the current value.; max 120 chars

Type: string. Optional.

Replacement preferred slug. Normalized and made unique within the organization. Omit to retain the current slug.

Type: string. Optional.

Replacement client-facing label. Omit to retain it; null or an empty string clears it. Nonempty strings are trimmed.; (use "null" or "reset" to clear)

Type: string. Optional.

Workspace visual identity color. Omit to retain the current token.; enum: default|gray|brown|orange|yellow|green|blue|purple|pink|red

Type: string. Optional.

Workspace visual identity rendering mode. Omit to retain the current mode. Set the corresponding icon, emoji or image value separately when needed.; enum: color|initial|icon|emoji|image

Type: string. Optional.

Icon identifier used by icon identity mode. Omit to retain it; null or an empty string clears it. Does not change identity_kind.; (use "null" or "reset" to clear); max 64 chars

Type: string. Optional.

Emoji value used by emoji identity mode. Omit to retain it; null or an empty string clears it. Does not change identity_kind.; (use "null" or "reset" to clear); max 32 chars

Type: string. Optional.

File ID used by image identity mode. Omit to retain it; null or an empty string clears it. Does not change identity_kind.; (use "null" or "reset" to clear)

Type: string. Optional.

Set client to convert an unarchived pitch workspace. Submit only purpose and optional dry_run. The conversion is irreversible. A request to convert to pitch is rejected.; enum: client|pitch

Type: string. Optional.

Archives a Workspace by ID. Use restore to restore it.

Retry identity for operations that support idempotency. Use a unique key for each new operation, and reuse it only when retrying the same HTTP method, path, query values and exact request body. JSON whitespace changes can count as a different body. Keys contain 1–255 characters after trimming and expire after 24 hours. A completed JSON response is replayed without repeating the operation. A different request using the same key returns 409 idempotency_error. An in-progress request returns 409 idempotency_in_progress with Retry-After: 2. Whether this header is required depends on the operation.

Type: string. Optional.

Restores an archived Workspace by ID.

Retry identity for operations that support idempotency. Use a unique key for each new operation, and reuse it only when retrying the same HTTP method, path, query values and exact request body. JSON whitespace changes can count as a different body. Keys contain 1–255 characters after trimming and expire after 24 hours. A completed JSON response is replayed without repeating the operation. A different request using the same key returns 409 idempotency_error. An in-progress request returns 409 idempotency_in_progress with Retry-After: 2. Whether this header is required depends on the operation.

Type: string. Optional.

Pauses measurement for the specified Workspace. --dry-run returns the resulting response without persisting the change.

Retry identity for operations that support idempotency. Use a unique key for each new operation, and reuse it only when retrying the same HTTP method, path, query values and exact request body. JSON whitespace changes can count as a different body. Keys contain 1–255 characters after trimming and expire after 24 hours. A completed JSON response is replayed without repeating the operation. A different request using the same key returns 409 idempotency_error. An in-progress request returns 409 idempotency_in_progress with Retry-After: 2. Whether this header is required depends on the operation.

Type: string. Optional.

Resumes measurement for a paused Workspace.

Retry identity for operations that support idempotency. Use a unique key for each new operation, and reuse it only when retrying the same HTTP method, path, query values and exact request body. JSON whitespace changes can count as a different body. Keys contain 1–255 characters after trimming and expire after 24 hours. A completed JSON response is replayed without repeating the operation. A different request using the same key returns 409 idempotency_error. An in-progress request returns 409 idempotency_in_progress with Retry-After: 2. Whether this header is required depends on the operation.

Type: string. Optional.

Lists members for a Workspace ID.

Grants access using the target Workspace ID and an active human user ID in the same organization in --user-id. API key synthetic IDs are not valid human user IDs.

Retry identity for operations that support idempotency. Use a unique key for each new operation, and reuse it only when retrying the same HTTP method, path, query values and exact request body. JSON whitespace changes can count as a different body. Keys contain 1–255 characters after trimming and expire after 24 hours. A completed JSON response is replayed without repeating the operation. A different request using the same key returns 409 idempotency_error. An in-progress request returns 409 idempotency_in_progress with Retry-After: 2. Whether this header is required depends on the operation.

Type: string. Optional.

(required) User ID of an active member of the workspace organization. This is not a workspace-member assignment ID. The user must already belong to the organization.

Type: string. Optional.

Workspace role to assign, defaulting to member. If the assignment already exists, this role replaces its current role and the assignment becomes active.; enum: owner|member

Type: string. Optional.

Removes a member’s access using a Workspace ID and user ID.

Retrieves the current Workspace’s measurement configuration, including the configured location, language, and model selection.

Updates configuration using JSON objects in default_location and platform_selection and a language code in default_language. Send complete JSON with --stdin to submit all three settings as one resource.

(required) Execution location. Choose global without code, or country with an uppercase two-letter code. Region and city locations are not accepted for execution.

Type: string. Optional.

(required) Default execution language tag, such as ja-JP. Used when a measurement inherits the workspace language.

Type: string. Optional.

(required) Choose all eligible observation channels, or provide a non-empty explicit set. Direct provider API channels are not supported for saved measurement configuration.

Type: string. Optional.

Preferred cadence; weekly billing entitlements remain weekly.; enum: daily|weekly

Type: string. Optional.

Lists append-only measurement configuration revisions. Paginate with --limit and --cursor.

Wait for setup and first observation to finish.

Retrieve saved measurement countries and languages.

Replace countries and languages, including existing values.

Update measurement configuration with complete JSON.

Grant human access to a Workspace after creation.

Access grants target an active human Organization user ID in the same organization. An organization-scoped write API key or a Workspace owner/admin can perform the operation. Do not pass an API key’s apikey:... synthetic ID as a human ID.

A Workspace created with an organization key does not automatically create human workspace_members, so run members create after creation. A target outside the organization boundary returns 404; read-only keys or humans without permission receive 403. After the grant, use orc workspace use <id> in the human profile, or --workspace <id> on data commands.

Use the organization key for capacity, Workspace creation, and access grants. Read setup, brands, prompts, and reports with the granted human or Workspace-scoped credentials.

The measurement target APIs are GET /v1/workspaces/current/measurement-targets and PATCH /v1/workspaces/current/measurement-targets. Specify Authorization: Bearer <API key> and X-Workspace-ID for API requests. Retrieval requires read scope; updates require write scope.

For MCP, use workspace_measurement_targets_get and workspace_measurement_targets_update. Enable the write profile for updates and provide idempotency_key and the arrays to change. After the user approves, resend the same input with the approval_id from the initial approval_required response as approval_receipt. Nothing is saved before approval.

The following global options can be used with orc workspaces:

For details and examples, see global options.