Prompts Client

The Prompts client provides methods for managing prompts in the Opik platform.

class opik.rest_api.prompts.client.PromptsClient(*, client_wrapper: SyncClientWrapper)

Bases: object

get_prompts(*, page: int | None = None, size: int | None = None, name: str | None = None, project_id: str | None = None, sorting: str | None = None, filters: str | None = None, request_options: RequestOptions | None = None) → PromptPagePublic

Get prompts

Parameters:

  • page (Optional[int])

  • size (Optional[int])

  • name (Optional[str])

  • project_id (Optional[str])

  • sorting (Optional[str])

  • filters (Optional[str])

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

OK

Return type:

PromptPagePublic

create_prompt(*, name: str, id: str | None = OMIT, project_id: str | None = OMIT, project_name: str | None = OMIT, description: str | None = OMIT, template: str | None = OMIT, metadata: Dict[str, Any | None] | None = OMIT, change_description: str | None = OMIT, type: Literal['mustache', 'jinja2', 'python'] | Any | None = OMIT, template_structure: Literal['text', 'chat'] | Any | None = OMIT, tags: Sequence[str] | None = OMIT, request_options: RequestOptions | None = None) → None

Create prompt

Parameters:

  • name (str)

  • id (Optional[str])

  • project_id (Optional[str]) – Project ID. Takes precedence over project_name when both are provided.

  • project_name (Optional[str]) – For project scope, specify either project_id or project_name. If project_name is provided and the project does not exist, it will be created. Ignored when project_id is provided. If neither is provided, the prompt is created at workspace level.

  • description (Optional[str])

  • template (Optional[str])

  • metadata (Optional[JsonNodeWrite])

  • change_description (Optional[str])

  • type (Optional[PromptWriteType])

  • template_structure (Optional[PromptWriteTemplateStructure]) – Template structure type: ‘text’ or ‘chat’. Immutable after creation.

  • tags (Optional[Sequence[str]])

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Return type:

None

create_prompt_version(*, name: str, version: PromptVersionDetail, template_structure: Literal['text', 'chat'] | Any | None = OMIT, project_id: str | None = OMIT, project_name: str | None = OMIT, request_options: RequestOptions | None = None) → PromptVersionDetail

Create prompt version

Parameters:

  • name (str)

  • version (PromptVersionDetail)

  • template_structure (Optional[CreatePromptVersionDetailTemplateStructure]) – Template structure for the prompt: ‘text’ or ‘chat’. Note: This field is only used when creating a new prompt. If a prompt with the given name already exists, this field is ignored and the existing prompt’s template structure is used. Template structure is immutable after prompt creation.

  • project_id (Optional[str]) – Project ID. Takes precedence over project_name when both are provided.

  • project_name (Optional[str]) – If provided, scopes the prompt to the specified project. Ignored when project_id is provided.

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

OK

Return type:

PromptVersionDetail

update_prompt_versions(*, ids: Sequence[str], update: PromptVersionUpdate, merge_tags: bool | None = OMIT, request_options: RequestOptions | None = None) → None

Update one or more prompt versions.

Note: Prompt versions are immutable by design. Only organizational properties, such as tags etc., can be updated. Core properties like template and metadata cannot be modified after creation.

PATCH semantics: - non-empty values update the field - null values preserve existing field values (no change) - empty values explicitly clear the field

Parameters:

  • ids (Sequence[str]) – IDs of prompt versions to update

  • update (PromptVersionUpdate)

  • merge_tags (Optional[bool]) – Tag merge behavior: - true: Add new tags to existing tags (union) - false: Replace all existing tags with new tags (default behaviour if not provided)

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Return type:

None

get_prompt_by_id(id: str, *, mask_id: str | None = None, environment: str | None = None, request_options: RequestOptions | None = None) → PromptDetail

Get prompt by id; when mask_id or environment is provided, requestedVersion is populated with the resolved version. mask_id and environment are mutually exclusive.

Parameters:

  • id (str)

  • mask_id (Optional[str]) – Optional mask version id; when set, requestedVersion is the mask row for that id

  • environment (Optional[str]) – Optional environment name; when set, requestedVersion is the version mapped to that environment for the prompt

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

Prompt resource

Return type:

PromptDetail

update_prompt(id: str, *, name: str, description: str | None = OMIT, tags: Sequence[str] | None = OMIT, request_options: RequestOptions | None = None) → None

Update prompt

Parameters:

  • id (str)

  • name (str)

  • description (Optional[str])

  • tags (Optional[Sequence[str]])

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Return type:

None

delete_prompt(id: str, *, request_options: RequestOptions | None = None) → None

Delete prompt

Parameters:

  • id (str)

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Return type:

None

delete_prompts_batch(*, ids: Sequence[str], request_options: RequestOptions | None = None) → None

Delete prompts batch

Parameters:

  • ids (Sequence[str])

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Return type:

None

get_prompt_by_commit(commit: str, *, request_options: RequestOptions | None = None) → PromptDetail

Get prompt by commit

Parameters:

  • commit (str)

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

OK

Return type:

PromptDetail

get_prompt_version_by_id(version_id: str, *, request_options: RequestOptions | None = None) → PromptVersionDetail

Get prompt version by id

Parameters:

  • version_id (str)

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

Prompt version resource

Return type:

PromptVersionDetail

get_prompt_version_by_number(prompt_id: str, version_number: str, *, request_options: RequestOptions | None = None) → PromptVersionDetail

Get a prompt version by its sequential v<N> number for the given prompt.

Parameters:

  • prompt_id (str)

  • version_number (str)

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

Prompt version resource

Return type:

PromptVersionDetail

get_prompt_versions(id: str, *, page: int | None = None, size: int | None = None, search: str | None = None, sorting: str | None = None, filters: str | None = None, request_options: RequestOptions | None = None) → PromptVersionPagePublic

Get prompt versions

Parameters:

  • id (str)

  • page (Optional[int])

  • size (Optional[int])

  • search (Optional[str]) – Search text to find in template or change description fields

  • sorting (Optional[str])

  • filters (Optional[str])

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

OK

Return type:

PromptVersionPagePublic

get_prompts_by_commits(*, commits: Sequence[str], request_options: RequestOptions | None = None) → List[PromptVersionLinkPublic]

Get prompts by prompt version commits

Parameters:

  • commits (Sequence[str])

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

OK

Return type:

List[PromptVersionLinkPublic]

restore_prompt_version(prompt_id: str, version_id: str, *, request_options: RequestOptions | None = None) → PromptVersionDetail

Restore a prompt version by creating a new version with the content from the specified version

Parameters:

  • prompt_id (str)

  • version_id (str)

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

OK

Return type:

PromptVersionDetail

retrieve_prompt_version(*, name: str, commit: str | None = OMIT, environment: str | None = OMIT, version_number: str | None = OMIT, project_name: str | None = OMIT, request_options: RequestOptions | None = None) → PromptVersionDetail

Retrieve prompt version

Parameters:

  • name (str)

  • commit (Optional[str])

  • environment (Optional[str]) – If provided, resolves to the version mapped to this environment for the prompt; mutually exclusive with commit and version_number

  • version_number (Optional[str]) – If provided, resolves to the version with this sequential number (e.g. v3); mutually exclusive with commit and environment

  • project_name (Optional[str]) – If provided, scopes the search to the specified project

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

OK

Return type:

PromptVersionDetail

retrieve_prompt_versions_by_ids(*, ids: Sequence[str], request_options: RequestOptions | None = None) → List[PromptVersionDetail]

Retrieve a batch of prompt versions by their ids. Typically used by the UI to resolve mask overlays.

Parameters:

  • ids (Sequence[str])

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

OK

Return type:

List[PromptVersionDetail]

set_prompt_version_environment(version_id: str, *, environments: Sequence[str], request_options: RequestOptions | None = None) → None

Set or clear the environment owned by a prompt version. Setting a non-null environment moves ownership atomically: any previous owner of that environment for the same prompt has its environment cleared in the same transaction. Setting null clears the environment from the version. The environment must already exist in the workspace registry; unknown names return 404.

Parameters:

  • version_id (str)

  • environments (Sequence[str])

  • request_options (Optional[RequestOptions]) – Request-specific configuration.

Return type:

None

Usage Example

import opik

client = opik.Opik()

# Create a prompt
client.rest_client.prompts.create_prompt(
    name="my-prompt",
    prompt="Tell me about {{topic}}",
    type="mustache"
)

# Get a prompt by name
prompt = client.rest_client.prompts.get_prompt_by_name("my-prompt")

# List all prompts
prompts = client.rest_client.prompts.find_prompts(
    page=0,
    size=10
)

# Get prompt versions
versions = client.rest_client.prompts.get_prompt_versions(
    prompt_name="my-prompt"
)