brands
orc brands manages owned and competing brands and their profiles in a Workspace. Retrieve lists and details, and create or update brand names, domains, aliases, offerings, audiences, and visual identities. Review generated brand suggestions before accepting or rejecting them.
Configure CLI authentication first and select the target with --workspace. Retrieve owned brands with --relation owned. Use returned brand IDs with get and update; they are different from Workspace IDs. A brand’s domain registry is managed separately from the ownership-verification and ingestion resources in orc domains.
Usage
orc brands list --relation owned --workspace <workspace-id>Inspect owned brand IDs and profiles.
Profile fields
| UI field | Input field |
|---|---|
| Description and industry | notes, industry |
| Brand identity | tags |
| Products and services | offerings, products_and_services |
| Audience composition | audience |
| Brand and display names | name, display_name |
| Domains and aliases | domain, domains, aliases |
| Colors and icons | color_token, color_hex, identity_kind, icon_token, emoji, image_file_id |
products_and_services is a structured list with a required name per entry and takes precedence over offerings in the same request. Name-only edits through offerings retain existing details for matching names. Both lists support up to 100 entries.
audience contains up to 20 entries with id, label, description, percentage, and enabled. Preserve existing audience IDs while editing. Each percentage is between 0 and 100. For a meaningful composition, arrange enabled entries to total 100%; the API does not validate the sum.
domains rejects duplicates after normalization and uses the first value as domain. Pass values containing commas as JSON arrays through standard input rather than CSV. color_token takes precedence over color_hex. profile_suggestion_decisions maps suggestion keys to accepted or rejected.
See Set up brand information for an editing workflow.
Subcommands
list
List brands. Filter --relation by owned, direct_competitor, indirect_competitor, or ignored. Omitting it includes owned brands and direct competitors. Keep filters unchanged when following a returned cursor.
orc brands list [options]Unique options
--relation
Filter by relation. When omitted, owned and direct_competitor are returned by default.; enum: owned|direct_competitor|indirect_competitor|ignored
Type: string. Optional.
orc brands list --relation <value>create
Create a brand with name and domain. relation defaults to direct_competitor and status to active. When domains is supplied, its first entry becomes the primary domain. This does not create a verification or ingestion Domain resource.
orc brands create [options]Unique options
--idempotency-key
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.
orc brands create --idempotency-key <value>--name
(required) Human-readable brand name.; max 255 chars
Type: string. Optional.
orc brands create --name <value>--domain
(required) Primary normalized domain in the brand registry. This field does not create a verification or ingestion Domain resource. Used when domains is omitted; otherwise the first domains entry takes precedence.; max 255 chars
Type: string. Optional.
orc brands create --domain <value>--relation
Single-axis brand relation. Intent-specific labels can be reserved in tags using intent:* when needed.; enum: owned|direct_competitor|indirect_competitor|ignored
Type: string. Optional.
orc brands create --relation <value>Labels attached to the brand. Strings are trimmed and empty strings are removed. Defaults to an empty array.; csv
Type: string. Optional.
orc brands create --tags <value>--logo-url
Logo URL or file reference; null when none is stored.; (use "null" or "reset" to clear)
Type: string. Optional.
orc brands create --logo-url <value>--display-name
Display name distinct from the stored brand name; null when unset.; (use "null" or "reset" to clear)
Type: string. Optional.
orc brands create --display-name <value>--industry
Industry label stored on the brand; null when unset.; (use "null" or "reset" to clear)
Type: string. Optional.
orc brands create --industry <value>--status
Lifecycle status. Defaults to active; disabled preserves history and stops future execution.; enum: active|disabled
Type: string. Optional.
orc brands create --status <value>--domains
Full brand domain registry. Values are trimmed, lowercased and stripped of an HTTP(S) scheme, leading www. and trailing slash. The first value becomes domain. Duplicate normalized values are rejected. When omitted, the registry contains domain only.; csv
Type: string. Optional.
orc brands create --domains <value>--aliases
Alternate brand names used for matching. Strings are trimmed and empty strings are removed. Defaults to an empty array.; csv
Type: string. Optional.
orc brands create --aliases <value>--color-hex
Six-digit hexadecimal display color. color_token takes precedence when both are supplied.; (use "null" or "reset" to clear)
Type: string. Optional.
orc brands create --color-hex <value>--color-token
Named display color. Writing this field also sets its corresponding color_hex. Defaults to default when neither color field is supplied.; enum: default|gray|brown|orange|yellow|green|blue|purple|pink|red
Type: string. Optional.
orc brands create --color-token <value>--identity-kind
Presentation style for the brand identity. Defaults to initial unless an image file selects image mode.; enum: color|initial|icon|emoji|image
Type: string. Optional.
orc brands create --identity-kind <value>--icon-token
Icon reference used for an icon identity; null when unset.; (use "null" or "reset" to clear)
Type: string. Optional.
orc brands create --icon-token <value>--emoji
Emoji used for an emoji identity; null when unset.; (use "null" or "reset" to clear)
Type: string. Optional.
orc brands create --emoji <value>--image-file-id
File reference used for an image identity. Writing this field also sets logo_url; null clears both and switches identity_kind to initial.; (use "null" or "reset" to clear)
Type: string. Optional.
orc brands create --image-file-id <value>--notes
Free-form brand profile notes; null when unset.; (use "null" or "reset" to clear)
Type: string. Optional.
orc brands create --notes <value>--regex-pattern
Stored regular expression for advanced brand matching; null when unset.; (use "null" or "reset" to clear)
Type: string. Optional.
orc brands create --regex-pattern <value>--products-and-services
Full replacement product and service list, with a required name per entry. Also replaces offerings with those names and takes precedence over offerings in the same request. An empty array clears the list. Defaults to an empty array when neither product list nor offerings is supplied.; JSON array of objects (use --stdin for large resources)
Type: string. Optional.
orc brands create --products-and-services <value>--offerings
Product and service names. Name-only edits retain stored details for matching names; products_and_services takes precedence when supplied. Defaults to an empty array.; csv
Type: string. Optional.
orc brands create --offerings <value>--audience
Audience segment list, up to 20 entries. Each percentage must be 0 to 100; this endpoint does not validate their sum. Defaults to an empty array when omitted.; JSON array of objects (use --stdin for large resources)
Type: string. Optional.
orc brands create --audience <value>--profile-suggestion-decisions
Map from generated profile suggestion keys to accepted or rejected decisions. Defaults to an empty object.; (JSON object, e.g. '{"custom_id":"x"}')
Type: string. Optional.
orc brands create --profile-suggestion-decisions <value>Examples
orc brands create --name "Acme" --domain acme.example --relation owned --workspace <workspace-id>Create an owned brand
suggestions list
List stored brand suggestions. Filter by pending, accepted, or rejected with --status. Reading the list does not generate suggestions.
orc brands suggestions list [options]Unique options
--status
Filter by suggestion status. Omit to include all statuses.; enum: pending|accepted|rejected
Type: string. Optional.
orc brands suggestions list --status <value>suggestions refresh
Start asynchronous brand suggestion generation. --wait waits for completion; adjust waiting with --timeout and --poll-interval. Generation and acceptance are separate operations.
orc brands suggestions refresh [options]Unique options
--idempotency-key
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.
orc brands suggestions refresh --idempotency-key <value>suggestions generations get
Retrieve asynchronous generation status using the ID returned when generation started. This is not a brand ID or suggestion ID.
orc brands suggestions generations get <id> [options]suggestions accept
Accept a pending suggestion by ID. Adjust the name with --edit-name and set the brand relationship with --relation.
orc brands suggestions accept <id> [options]Unique options
--idempotency-key
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.
orc brands suggestions accept <id> --idempotency-key <value>--edit-name
Name for the created resource. When omitted, uses the suggestion name.; max 255 chars
Type: string. Optional.
orc brands suggestions accept <id> --edit-name <value>--relation
Single-axis brand relation. Intent-specific labels can be reserved in tags using intent:* when needed.; enum: owned|direct_competitor|indirect_competitor|ignored
Type: string. Optional.
orc brands suggestions accept <id> --relation <value>suggestions reject
Reject a suggestion by ID. This does not create a brand.
orc brands suggestions reject <id> [options]Unique options
--idempotency-key
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.
orc brands suggestions reject <id> --idempotency-key <value>get
Retrieve details, including the profile, using a brand ID from the list. The brand must be in the current Workspace.
orc brands get <id> [options]update
Change only supplied fields. Arrays and suggestion-decision maps replace their entire stored values. Pass long descriptions or structured products_and_services and audience through JSON with --stdin. Nullable fields can be cleared with null. disabled preserves history and stops future execution; reactivation does not backfill the inactive interval.
orc brands update <id> [options]Unique options
--name
Human-readable brand name. Omit to retain the current value.; max 255 chars
Type: string. Optional.
orc brands update <id> --name <value>--domain
Primary normalized domain in the brand registry. This field does not create a verification or ingestion Domain resource. Omit to retain the current value. When domains is omitted, supplying domain replaces the registry with this single value.; max 255 chars
Type: string. Optional.
orc brands update <id> --domain <value>--relation
Single-axis brand relation. Intent-specific labels can be reserved in tags using intent:* when needed.; enum: owned|direct_competitor|indirect_competitor|ignored
Type: string. Optional.
orc brands update <id> --relation <value>Labels attached to the brand. Strings are trimmed and empty strings are removed. Omit to retain the current value. Send [] to clear.; csv
Type: string. Optional.
orc brands update <id> --tags <value>--logo-url
Logo URL or file reference; null when none is stored. Omit to retain the current value.; (use "null" or "reset" to clear)
Type: string. Optional.
orc brands update <id> --logo-url <value>--display-name
Display name distinct from the stored brand name; null when unset. Omit to retain the current value.; (use "null" or "reset" to clear)
Type: string. Optional.
orc brands update <id> --display-name <value>--industry
Industry label stored on the brand; null when unset. Omit to retain the current value.; (use "null" or "reset" to clear)
Type: string. Optional.
orc brands update <id> --industry <value>--status
Lifecycle transition. disabled preserves history and stops future execution; returning to active does not backfill the disabled interval.; enum: active|disabled
Type: string. Optional.
orc brands update <id> --status <value>--domains
Full brand domain registry. Values are trimmed, lowercased and stripped of an HTTP(S) scheme, leading www. and trailing slash. The first value becomes domain. Duplicate normalized values are rejected. Omit to retain the current value.; csv
Type: string. Optional.
orc brands update <id> --domains <value>--aliases
Alternate brand names used for matching. Strings are trimmed and empty strings are removed. Omit to retain the current value. Send [] to clear.; csv
Type: string. Optional.
orc brands update <id> --aliases <value>--color-hex
Six-digit hexadecimal display color. color_token takes precedence when both are supplied. Omit to retain the current value.; (use "null" or "reset" to clear)
Type: string. Optional.
orc brands update <id> --color-hex <value>--notes
Free-form brand profile notes; null when unset. Omit to retain the current value.; (use "null" or "reset" to clear)
Type: string. Optional.
orc brands update <id> --notes <value>--regex-pattern
Stored regular expression for advanced brand matching; null when unset. Omit to retain the current value.; (use "null" or "reset" to clear)
Type: string. Optional.
orc brands update <id> --regex-pattern <value>--color-token
Named display color. Writing this field also sets its corresponding color_hex. Omit to retain the current value.; enum: default|gray|brown|orange|yellow|green|blue|purple|pink|red
Type: string. Optional.
orc brands update <id> --color-token <value>--identity-kind
Presentation style for the brand identity. Omit to retain the current value.; enum: color|initial|icon|emoji|image
Type: string. Optional.
orc brands update <id> --identity-kind <value>--icon-token
Icon reference used for an icon identity; null when unset. Omit to retain the current value.; (use "null" or "reset" to clear)
Type: string. Optional.
orc brands update <id> --icon-token <value>--emoji
Emoji used for an emoji identity; null when unset. Omit to retain the current value.; (use "null" or "reset" to clear)
Type: string. Optional.
orc brands update <id> --emoji <value>--image-file-id
File reference used for an image identity. Writing this field also sets logo_url; null clears both and switches identity_kind to initial. Omit to retain the current value.; (use "null" or "reset" to clear)
Type: string. Optional.
orc brands update <id> --image-file-id <value>--products-and-services
Full replacement product and service list, with a required name per entry. Also replaces offerings with those names and takes precedence over offerings in the same request. An empty array clears the list. Omit to retain stored details unless offerings is supplied.; JSON array of objects (use --stdin for large resources)
Type: string. Optional.
orc brands update <id> --products-and-services <value>--offerings
Product and service names. Name-only edits retain stored details for matching names; products_and_services takes precedence when supplied. Omit to retain the current value. Send [] to clear.; csv
Type: string. Optional.
orc brands update <id> --offerings <value>--audience
Audience segment list, up to 20 entries. Each percentage must be 0 to 100; this endpoint does not validate their sum. Supplying the array replaces all stored segments; an empty array clears them. Omit to retain the current list.; JSON array of objects (use --stdin for large resources)
Type: string. Optional.
orc brands update <id> --audience <value>--profile-suggestion-decisions
Map from generated profile suggestion keys to accepted or rejected decisions. Omit to retain the current value.; (JSON object, e.g. '{"custom_id":"x"}')
Type: string. Optional.
orc brands update <id> --profile-suggestion-decisions <value>Examples
Omitted fields are preserved. Sending one array entry replaces that array with a single entry.
orc brands update <brand-id> --stdin --workspace <workspace-id> < brand-profile.patch.jsonUpdate a profile from JSON
delete
Soft-delete the specified brand. Check the target ID and Workspace before running the command.
orc brands delete <id> [options]Examples
Profile update input
{
"notes": "Enterprise search software.",
"offerings": [
"Acme Search"
],
"audience": [
{
"id": "developers",
"label": "Developers",
"description": "Software teams",
"percentage": 100,
"enabled": true
}
]
}Profile update input
Permissions
Access to the target Workspace is required. Changes require the corresponding write permissions.
Global Options
The following global options can be used with orc brands:
For details and examples, see global options.