--- title: topics description: Manage brand monitoring topics and suggestions. canonical_url: https://orchestor.io/docs/en/cli/topic markdown_url: https://orchestor.io/docs/en/cli/topic.md contentType: reference --- # topics `orc topics` manages monitoring topics associated with brands. Retrieve lists and details, create or change names, archive or unarchive topics, and soft-delete them. Review topic candidates generated from Workspace brand information before accepting or rejecting them. Configure authentication and select the target Workspace. Creation requires a topic name and a brand ID in that Workspace. Creating a topic does not create prompts. Attach subsequent questions through `topic_id` in [`orc prompts`](https://orchestor.io/docs/cli/prompt.md). ## Usage ```bash title="terminal" orc topics list --workspace ``` *Inspect saved topics.* ## Subcommands ### `list` List topics under non-deleted brands newest first, including archived topics. Omit `--brand-id` to include all brands. Preserve the brand filter while following pages. ```bash title="terminal" orc topics list [options] ``` #### Unique options ##### `--brand-id` Restrict results to this brand in the selected workspace. Omit to include all brands; an unavailable brand returns 404. Type: `string`. Optional. ```bash title="terminal" orc topics list --brand-id ``` ### `create` `name` is limited to 255 characters and required together with `brand_id`. New topics are unarchived. Requires `workspace:settings` permission. ```bash title="terminal" orc topics 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. ```bash title="terminal" orc topics create --idempotency-key ``` ##### `--name` (required) Human-readable topic name, from 1 to 255 characters.; max 255 chars Type: `string`. Optional. ```bash title="terminal" orc topics create --name ``` ##### `--brand-id` (required) Required parent brand in the selected workspace. A topic cannot currently be created without a brand. Type: `string`. Optional. ```bash title="terminal" orc topics create --brand-id ``` #### Examples ```bash title="terminal" orc topics create --name "CRM selection" --brand-id --workspace ``` *Create a topic for a brand* ### `get` Retrieve details by topic ID, including archived topics. Return 404 if the topic or parent brand is unavailable in the target Workspace. ```bash title="terminal" orc topics get [options] ``` ### `update` Change only supplied `name` and `archived`. `--archived true` archives; false unarchives. The brand association cannot be changed here. An empty body returns the current topic. ```bash title="terminal" orc topics update [options] ``` #### Unique options ##### `--archived` Set true to archive or false to unarchive through the measurement lifecycle. Omit to keep the current state. Type: `string`. Optional. ```bash title="terminal" orc topics update --archived ``` ##### `--name` Replacement topic name. Omit to keep the current name.; max 255 chars Type: `string`. Optional. ```bash title="terminal" orc topics update --name ``` #### Examples ```bash title="terminal" orc topics update --archived true --workspace ``` *Archive a topic* ### `delete` Soft-delete a topic through the measurement lifecycle and hide it from ordinary lists and reads. Requires `workspace:settings` permission. ```bash title="terminal" orc topics delete [options] ``` ### `suggestions list` Filter stored suggestions with `--status` and `--brand-id`. Omitted filters do not restrict results. Preserve filters while following cursors. ```bash title="terminal" orc topics suggestions list [options] ``` #### Unique options ##### `--status` Filter by suggestion status. Omit to include all statuses.; enum: pending|accepted|rejected Type: `string`. Optional. ```bash title="terminal" orc topics suggestions list --status ``` ##### `--brand-id` Filter by brand id in the selected workspace. Omit to include domains or suggestions for all brands. Type: `string`. Optional. ```bash title="terminal" orc topics suggestions list --brand-id ``` ### `suggestions refresh` Start asynchronous suggestion generation from the current Workspace’s brand context. No body is needed. Use `--wait` to wait for completion. Generated candidates do not become topics until explicitly accepted. ```bash title="terminal" orc topics 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. ```bash title="terminal" orc topics suggestions refresh --idempotency-key ``` #### Examples ```bash title="terminal" orc topics suggestions refresh --wait --workspace ``` *Generate topic suggestions and wait* ### `suggestions generations get` Retrieve asynchronous generation status by returned generation ID. Check state rather than treating acceptance as completion. ```bash title="terminal" orc topics suggestions generations get [options] ``` ### `suggestions accept` Accept a pending candidate and create an active topic. `--brand-id` overrides the suggestion’s brand. If neither provides a brand, return 400. Adjust the name with `--edit-name`. Resolved suggestions return 409; missing IDs return 404. ```bash title="terminal" orc topics suggestions accept [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. ```bash title="terminal" orc topics suggestions accept --idempotency-key ``` ##### `--brand-id` Brand in the selected workspace to assign to the new topic. Required when the suggestion has no brand. Type: `string`. Optional. ```bash title="terminal" orc topics suggestions accept --brand-id ``` ##### `--edit-name` Name for the created resource. When omitted, uses the suggestion name.; max 255 chars Type: `string`. Optional. ```bash title="terminal" orc topics suggestions accept --edit-name ``` ### `suggestions reject` Mark a pending candidate rejected. Missing IDs return 404; already accepted or rejected suggestions return 409. ```bash title="terminal" orc topics suggestions reject [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. ```bash title="terminal" orc topics suggestions reject --idempotency-key ``` ## Permissions Access to the target Workspace is required. Changes require the corresponding write permissions. ## Global Options The following [global options](https://orchestor.io/docs/cli/global-flags.md) can be used with `orc topics`: - [`--help`](https://orchestor.io/docs/cli/global-flags.md#help) - [`--workspace`](https://orchestor.io/docs/cli/global-flags.md#workspace) - [`--json`](https://orchestor.io/docs/cli/global-flags.md#json-output) - [`--pretty`](https://orchestor.io/docs/cli/global-flags.md#json-output) - [`--format`](https://orchestor.io/docs/cli/global-flags.md#output-format) - [`--field`](https://orchestor.io/docs/cli/global-flags.md#field-selection) - [`--fields`](https://orchestor.io/docs/cli/global-flags.md#field-selection) - [`--raw`](https://orchestor.io/docs/cli/global-flags.md#raw-output) - [`--output`](https://orchestor.io/docs/cli/global-flags.md#file-output) - [`--no-pager`](https://orchestor.io/docs/cli/global-flags.md#pager) - [`--dry-run`](https://orchestor.io/docs/cli/global-flags.md#dry-run) - [`--yes`](https://orchestor.io/docs/cli/global-flags.md#confirmation) - [`--limit`](https://orchestor.io/docs/cli/global-flags.md) - [`--cursor`](https://orchestor.io/docs/cli/global-flags.md) - [`--stdin`](https://orchestor.io/docs/cli/global-flags.md#standard-input) - [`--from-stdin`](https://orchestor.io/docs/cli/global-flags.md#standard-input) - [`--page-all`](https://orchestor.io/docs/cli/global-flags.md#all-pages) - [`--timing`](https://orchestor.io/docs/cli/global-flags.md#request-timing) - [`--wait`](https://orchestor.io/docs/cli/global-flags.md) - [`--timeout`](https://orchestor.io/docs/cli/global-flags.md) - [`--poll-interval`](https://orchestor.io/docs/cli/global-flags.md) - [`--readonly`](https://orchestor.io/docs/cli/global-flags.md#read-only-mode) - [`--wrap-untrusted`](https://orchestor.io/docs/cli/global-flags.md#untrusted-content-wrapping) For details and examples, see [global options](https://orchestor.io/docs/cli/global-flags.md). --- [Documentation index](https://orchestor.io/docs/llms.txt)