​

prompts

orc prompts manages questions monitored in a Workspace. Create or update question text, topics, personas, measurement channels, regions, and languages, and enable or disable execution. It also handles suggestion generation and acceptance, and reading or replacing tags. New questions default to draft and do not run or consume active prompt quota.

Authentication and Workspace access are required. Use prompt IDs returned by creation or listing. Discover channel IDs with orc channels list and region codes with orc regions list. Activation needs remaining prompt quota. Creating a question is separate from working with results through orc runs.

Inspect question IDs, lifecycle state, and persisted result aggregates.

platforms contains consumer AI observation channel IDs. The default is chatgpt-ui; recognized observation aliases are normalized. Direct provider API channels are rejected. Specify up to 20 existing persona IDs in the same Workspace.

Supported country_code forms such as JP, jp, JPN, and ja-JP are normalized to alpha-2 and can fill omitted region and language defaults. Explicit values are preserved. These are measurement conditions, not organization data residency. language_code uses BCP 47.

schedule is a stored cron expression of at most 100 characters. Omitting it on creation stores null. Execution also depends on question lifecycle and Workspace measurement configuration; saving cron does not guarantee execution.

branding is non_branded or branded; intent_type is informational, commercial, or transactional. Omitting branding classifies against brand names, aliases, and domains; intent defaults to informational. These classify the question, not answer sentiment. Omitted classifications are preserved on update.

Filter with --topic-id and --status. Omitting status includes all lifecycle states; soft-deleted prompts and prompts under deleted parents are excluded. Persisted answer aggregates are included, but measurement does not start.

Existing accessible Topic ID. Omit to include prompts across topics and prompts without a topic. A missing or inaccessible Topic returns 404.

Type: string. Optional.

Return only this lifecycle state. Omit to include draft, active, disabled and archived prompts; deleted prompts remain excluded.; enum: draft|active|disabled|archived

Type: string. Optional.

Comma-separated platform or channel IDs restricting answer metrics and mentioned brands. Prompt membership is unchanged. Omit for all platforms.; max 2000 chars

Type: string. Optional.

text is required and limited to 2,000 characters. Supply a supported country_code, or both region_id and language_code. Active questions without a topic are assigned the Workspace default topic and need an active owned brand. Duplicate text and country return 409.

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.

Existing Topic ID in this workspace. Omit or set null to leave a draft or disabled prompt unassigned. Persisted active creation resolves the workspace default topic; preview does not.; (use "null" or "reset" to clear)

Type: string. Optional.

(required) The prompt text to send to LLM platforms.; max 2000 chars

Type: string. Optional.

Existing Persona IDs in this workspace. Omit or use an empty array for no persona associations. Missing or inaccessible IDs return 404.; csv

Type: string. Optional.

Consumer AI observation channel IDs. Defaults to chatgpt-ui. Recognized observation aliases are normalized; direct provider API channels are rejected.; csv of: chatgpt-ui|gemini-ui|perplexity-ui|copilot-ui|google-ai-overview|google-ai-mode

Type: string. Optional.

Execution region. Required unless the supplied country or another recognized locale field resolves a supported default. Explicit values are preserved. This does not control data residency.

Type: string. Optional.

Execution language. Required unless the supplied country or another recognized locale field resolves a supported default. Explicit values are preserved.

Type: string. Optional.

ISO 3166 observation country used when executing this prompt. Common forms such as JP, jp, JPN, and locale-style ja-JP are normalized to the canonical alpha-2 country code when supported. This does not control Organization residency.; (use "null" or "reset" to clear)

Type: string. Optional.

Lifecycle status. draft is editable and excluded from measurement and active prompt quota until explicitly activated. Defaults to draft; disabled preserves history and stops future execution.; enum: draft|active|disabled

Type: string. Optional.

Stored cron expression for periodic collection. Omit to store null. Actual execution also depends on prompt lifecycle and workspace measurement configuration.; max 100 chars

Type: string. Optional.

Whether the prompt text names a brand (branded) or is generic (non_branded). On creation, omission classifies against registered workspace brand names, aliases and domains. An explicit value takes precedence; measurement does not overwrite manual classifications.; enum: non_branded|branded

Type: string. Optional.

Search-intent classification of the prompt question. Defaults to informational on creation; omission in a partial update preserves the stored value.; enum: informational|commercial|transactional

Type: string. Optional.

When true, validate and resolve the Prompt without persistence. Requires Idempotency-Key; read-scope API keys may use only this mode.

Type: string. Optional.

Create a draft question

Retrieve a question and its persona associations. Use config_revision from this response for updates. Single-item reads do not calculate answer aggregates; inspect them through list.

Change only supplied fields, except that supplied locale values may populate omitted locale fields. Disable an active question before changing its text. Supply the latest config_revision; on a 409 conflict, retrieve again and review the change. persona_ids and platforms replace complete selections.

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.

Replacement question text. Omit to retain it. An active prompt must be disabled before its text changes.; max 2000 chars

Type: string. Optional.

Replacement accessible Topic ID. Omit to retain the association. Null clears a non-active association; an active prompt resolves a default topic and requires an active owned brand.; (use "null" or "reset" to clear)

Type: string. Optional.

Complete replacement of persona associations. Omit to retain them; use [] to clear them. Every ID must belong to this workspace.; csv

Type: string. Optional.

Complete replacement of observation channels. Omit to retain the selection. Recognized observation aliases are normalized; direct provider API channels are rejected.; csv of: chatgpt-ui|gemini-ui|perplexity-ui|copilot-ui|google-ai-overview|google-ai-mode

Type: string. Optional.

Replacement execution region. Omit to retain it unless another supplied locale field derives a supported default.

Type: string. Optional.

Replacement execution language. Omit to retain it unless another supplied locale field derives a supported default.

Type: string. Optional.

Replacement observation country. Supported country and locale forms are normalized and can populate omitted region_id and language_code. Omit all locale fields to retain the current locale.; (use "null" or "reset" to clear)

Type: string. Optional.

Lifecycle transition. disabled preserves history and stops future execution; archived removes the prompt from active work while preserving its history.; enum: draft|active|disabled|archived

Type: string. Optional.

Replacement stored cron expression. Omit to retain it. This request schema does not accept null.; max 100 chars

Type: string. Optional.

Whether the prompt text names a brand (branded) or is generic (non_branded). On creation, omission classifies against registered workspace brand names, aliases and domains. An explicit value takes precedence; measurement does not overwrite manual classifications.; enum: non_branded|branded

Type: string. Optional.

Search-intent classification of the prompt question. Defaults to informational on creation; omission in a partial update preserves the stored value.; enum: informational|commercial|transactional

Type: string. Optional.

Latest revision from a prompt response. A mismatch returns 409 when applying a change. Omission remains accepted during the migration window; do not use a preview revision as a saved revision.

Type: number. Optional.

When true, validate and resolve the update without persistence. Requires Idempotency-Key; read-scope API keys may use only this mode.

Type: string. Optional.

Change a disabled question’s text

Soft-delete a question and hide it from ordinary lists and reads. The question and observation history are permanently removed by daily purge after the 30-day retention window. Use disable to stop only future observation. Repeating deletion returns 404.

Move a draft, active, or archived question to disabled, preserving configuration and history while stopping future observation. An already disabled question returns 409. The response includes the updated config_revision.

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.

Activate a draft, disabled, or archived question. Insufficient active quota returns 402; already active returns 409. Default-topic assignment for an unassigned question needs an active owned brand. Inactive periods are not backfilled, and this does not return completed measurement results.

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.

Read stored suggestions filtered by status and topic_id. Omitted status includes pending, accepted, and rejected suggestions. This read does not generate suggestions.

Review state to include. Omit for all states.; enum: pending|accepted|rejected

Type: string. Optional.

Limit results to this parent topic. Omit to include all topics in the workspace.

Type: string. Optional.

Start asynchronous generation for existing Workspace topic IDs. --topic-ids is required. Omit or empty persona_ids to generate without persona context. instructions allows up to 2,000 characters and applies to all selected topics. Acceptance can already report dispatch failure. Generation does not activate questions.

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) Existing topic IDs in this workspace. Select 1–20 entries; repeated IDs are deduplicated before generation. Missing or deleted topics are rejected.; csv

Type: string. Optional.

Existing workspace Persona IDs to distribute across generated suggestions. Omit or send an empty array to generate without Persona context.; csv

Type: string. Optional.

Requested new candidates per distinct topic, from 1 to 20. Defaults to 5. Deduplication or generation results can produce fewer stored candidates.

Type: number. Optional.

Language context for generated prompt text. Defaults to ja-JP.

Type: string. Optional.

Country context for generation. Defaults to JP.

Type: string. Optional.

Optional generation guidance applied to every selected topic.; max 2000 chars

Type: string. Optional.

Generate suggestions for a topic and wait

Retrieve generation state and results by returned generation ID. Use this and the suggestion list to inspect generation started without --wait.

Promote a pending suggestion to a new disabled question and mark it accepted in the same transaction. Measurement does not start automatically. Supply --edit-text and --topic-id as needed; a suggestion without a topic requires one. Resolved suggestions return 409.

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.

Destination topic in the same workspace. Omit to use the suggestion topic. Required when the suggestion has no topic.

Type: string. Optional.

Replacement prompt text, up to 2000 characters. Omit to preserve the suggestion text. Providing an edit also causes branding to be resolved for the edited text.; max 2000 chars

Type: string. Optional.

Mark a pending suggestion rejected and record resolution time. No question is created; the suggestion remains in rejected lists. Resolved suggestions return 409 and missing IDs 404.

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.

Retrieve active tags attached to a question, oldest first by creation time. This is not paginated. The current API resolves prompts through non-deleted topics and brands, so an unassigned question returns 404.

Replace all associations with the complete tag_ids list. Supply the latest config_revision. Even when adding one tag, include every ID you want to preserve.

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) Complete replacement tag set. Supply distinct active IDs from this workspace; [] removes all tags. Unknown or repeated IDs are rejected.; csv

Type: string. Optional.

Current prompt revision for optimistic concurrency. A mismatch returns 409 without changing tags. Omission currently skips the revision check.

Type: number. Optional.

preview returns a non-persisted projection. Unlike --dry-run, it sends to the API. It does not reserve quota, reject stored duplicates, or create a default topic.

Validate configuration on the server before saving

Creation and update with preview true require Idempotency-Key and support read-scope API keys. Persisted creation requires write scope; updates and other configuration changes require workspace:settings. Do not use a preview revision as a saved revision.

Omitting config_revision is accepted only during the migration window. Edit with the latest saved value; on conflict, retrieve again and review rather than overwriting. Prefer enable and disable for lifecycle changes. They do not restore soft-deleted questions.

Access to the target Workspace is required. Changes require the corresponding write permissions.

The following global options can be used with orc prompts:

For details and examples, see global options.