​

personas

orc personas manages audience personas in a Workspace. Create, retrieve, update, and delete profiles containing names, descriptions, behavior, demographics, and employment information. You can also asynchronously generate candidates from a brand and save reviewed profiles.

Configure authentication and specify the target Workspace. Creating a persona does not attach it to prompts or start measurement. Use its saved ID in persona_ids through orc prompts. Profiles are user-described hypotheses, not verified customer attributes.

Inspect saved personas and their IDs.

Generate buyer persona hypotheses asynchronously from a brand in the current Workspace. Acceptance may already report dispatch failure, so inspect status using the returned generation ID. Generation does not save personas, attach them, or start measurement.

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) Brand in the selected workspace whose profile supplies generation context.

Type: string. Optional.

Requested number of persona candidates, from 1 to 5. Defaults to 3.

Type: number. Optional.

Language for the generated candidates. Defaults to ja-JP.

Type: string. Optional.

Optional guidance for generation, up to 2000 characters. Omit for no additional instructions.; max 2000 chars

Type: string. Optional.

Retrieve candidate generation status and results by generation ID. Review and edit candidates, then save selected profiles with personas create.

List non-deleted personas newest first by creation time. This does not filter by brand. Pass the returned cursor unchanged for the next page.

Only name is required. Omitted description becomes null; omitted persona becomes an empty profile. Creation requires workspace:settings permission.

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) Display name for this audience persona.

Type: string. Optional.

Optional audience summary. Omit or send null to store no description.; (use "null" or "reset" to clear)

Type: string. Optional.

Optional audience attributes grouped into behavior, demographics and employment, plus visual identity. Omit unknown groups or fields. Nullable leaf values can be null. Text and string arrays describe the audience; they are not validated against demographic taxonomies. Use employment.roleSeniority; the removed employment.seniority field is rejected.; (JSON object, e.g. '{"custom_id":"x"}')

Type: string. Optional.

Save a structured profile

Retrieve details using a persona ID from listing. Missing, deleted, or other-Workspace IDs return 404.

Change only supplied fields. description: null clears the description. Supplying persona replaces the entire profile rather than merging nested fields. Use an empty JSON object to clear the profile.

Replacement display name. Omit to keep the current name.

Type: string. Optional.

Replacement summary. Send null to clear it; omit to retain it.; (use "null" or "reset" to clear)

Type: string. Optional.

Optional audience attributes grouped into behavior, demographics and employment, plus visual identity. Omit unknown groups or fields. Nullable leaf values can be null. Text and string arrays describe the audience; they are not validated against demographic taxonomies. Use employment.roleSeniority; the removed employment.seniority field is rejected.; (JSON object, e.g. '{"custom_id":"x"}')

Type: string. Optional.

Soft-delete a persona. If it is attached to a non-deleted prompt, return 409. Remove it from each prompt’s persona_ids before retrying.

Persona input

The main persona groups are behavior, demographics, and employment. Field names use camelCase. Omit unknown groups or fields; nullable leaf values can be null.

behavior contains motivations and painPoints. demographics contains ageRange, gender, location, income, and education. employment contains companySize, industry, jobTitle, roleSeniority, and department. Demographic and employment values are arrays of strings. Use roleSeniority, not the removed employment.seniority.

Optional avatar contains colorToken, identityKind, iconToken, emoji, and imageFileId. Null restores the default avatar. Sending only part of a profile on update also replaces the rest, so send the complete profile containing fields you want to preserve.

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

The following global options can be used with orc personas:

For details and examples, see global options.