Skip to main content
Version: 2025.4

Studio integration

Studio API Endpoints​

The Copilot Bundle provides a RESTful API for the Pimcore Studio interface, enabling management of copilot actions, interaction workflows, and job run monitoring. All endpoints are prefixed with /pimcore-studio/api/bundle/copilot and require appropriate permissions.

Actions​

List Actions​

Endpoint: GET /actions
Operation ID: bundle_copilot_actions
Permission: PCP_GENERAL_PERMISSION

Lists all available Copilot actions with localized descriptions. This endpoint returns a paginated collection of actions that can be executed.

Response: Collection of Action objects

Run Automation Action​

Endpoint: POST /actions/automation/{name}/run
Operation ID: bundle_copilot_actions_automation_run
Permission: PCP_GENERAL_PERMISSION

Executes a specific automation action configuration by name. This triggers an asynchronous job run and returns the job run ID for tracking progress.

Path Parameter:

  • name (string): The name of the automation action configuration to run (e.g., "CarVariantGenerator")

Request Body: AutomationActionRunParameters

Response: CopilotJobRunId object (HTTP 201 Created)

Example:

POST /actions/automation/CarVariantGenerator/run

Interaction Actions​

Chat Workflow​

The chat workflow is a multi-turn conversation with an AI model. It consists of three steps: initializing the chat, sending follow-up prompts, and applying the final result.

Get Initial Chat Interaction​

Endpoint: POST /actions/interaction/{name}/{interactionId}/initial
Operation ID: bundle_copilot_actions_interaction_chat_initial
Permission: PCP_GENERAL_PERMISSION

Initializes a new chat interaction session. Sends the initial context/prompt to the AI model and returns the initial chat history.

Path Parameters:

  • name (string): The name of the interaction action configuration (e.g., "OpenAITextGeneration")
  • interactionId (integer): The ID of the chat interaction (e.g., 9875567)

Request Body: InteractionActionChatInitialParameters

Response: Array of InteractionActionChatHistory objects

Example:

POST /actions/interaction/OpenAITextGeneration/9875567/initial
Send Prompt to Chat Interaction​

Endpoint: POST /actions/interaction/{name}/{interactionId}/prompt
Operation ID: bundle_copilot_actions_interaction_chat_prompt
Permission: PCP_GENERAL_PERMISSION

Sends a follow-up user prompt to an ongoing chat interaction and receives the AI response. This endpoint is used for continuing a chat conversation after the initial call.

Path Parameters:

  • name (string): The name of the interaction action configuration (e.g., "OpenAITextGeneration")
  • interactionId (integer): The ID of the chat interaction (e.g., 9875567)

Request Body: InteractionActionChatPromptParameters

Response: Array of InteractionActionChatHistory objects

Example:

POST /actions/interaction/OpenAITextGeneration/9875567/prompt
Apply Chat Interaction Results​

Endpoint: POST /actions/interaction/{name}/{interactionId}/apply
Operation ID: bundle_copilot_actions_interaction_chat_apply
Permission: PCP_GENERAL_PERMISSION

Applies the results from a chat interaction to the target element (e.g., writes AI-generated text to a data object field). This finalizes the interaction by persisting the changes.

Path Parameters:

  • name (string): The name of the interaction action configuration (e.g., "OpenAITextGeneration")
  • interactionId (integer): The ID of the chat interaction (e.g., 9875567)

Request Body: InteractionActionChatApplyParameters

Response: Empty JSON response (HTTP 200 OK)

Example:

POST /actions/interaction/OpenAITextGeneration/9875567/apply

One-Step Workflow​

Execute One-Step Interaction​

Endpoint: POST /actions/interaction/{name}/execute
Operation ID: bundle_copilot_actions_interaction_one_step
Permission: PCP_GENERAL_PERMISSION

Executes a one-step interaction action that processes input and returns a result in a single request. Unlike chat interactions, this does not maintain conversation history and completes immediately.

Path Parameter:

  • name (string): The name of the interaction action configuration (e.g., "HFTranslationPrompt")

Request Body: InteractionActionOneStepParameters

Response: InteractionActionOneStep object

Example:

POST /actions/interaction/HFTranslationPrompt/execute

Job Runs​

List All Job Runs​

Endpoint: GET /job-runs
Operation ID: bundle_copilot_job_runs
Permission: PCP_JOB_RUN

Retrieves a paginated list of all job runs with optional sorting capabilities.

Query Parameters:

  • page (integer, optional): Page number for pagination
  • pageSize (integer, optional, default: 50): Number of results per page
  • sortOrder (string, optional): Sort direction
  • sortBy (string, optional): Sort field. Supported values: id, ownerId, state, currentStep, currentMessage, context, creationDate, modificationDate

Response: Collection of CopilotJobRun objects

Example:

GET /job-runs?page=1&pageSize=25&sortBy=creationDate&sortOrder=desc

List Running Job Runs​

Endpoint: GET /job-runs/running
Operation ID: bundle_copilot_job_runs_running
Permission: PCP_JOB_RUN

Returns only the currently running job runs. Useful for monitoring active automation tasks.

Query Parameters:

  • pageSize (integer, optional, default: 50): Number of results per page
  • sortOrder (string, optional): Sort direction
  • sortBy (string, optional): Sort field. Supported values: id, ownerId, state, currentStep, currentMessage, context, creationDate, modificationDate

Response: Collection of CopilotJobRun objects

Example:

GET /job-runs/running?pageSize=10&sortBy=creationDate&sortOrder=desc

Get Job Run Progress​

Endpoint: GET /job-run/{id}/progress
Operation ID: bundle_copilot_job_run_progress
Permission: PCP_GENERAL_PERMISSION

Retrieves the current progress status of a specific job run, including completion percentage and status information.

Path Parameter:

  • id (integer): The job run ID

Response: CopilotJobRunProgress object

Example:

GET /job-run/123/progress

Cancel Job Run​

Endpoint: POST /job-run/{id}/cancel
Operation ID: bundle_copilot_job_run_cancel
Permission: PCP_JOB_RUN

Cancels a running job run. Only running jobs can be cancelled; attempting to cancel a completed or already cancelled job will result in a conflict error.

Path Parameter:

  • id (integer): The job run ID to cancel

Response: { "jobRunId": <id> }

Possible Errors:

  • 409 Conflict: Job run is not in a cancellable state
  • 403 Forbidden: User lacks permission to cancel this job

Rerun Job Run​

Endpoint: POST /job-run/{id}/rerun
Operation ID: bundle_copilot_job_run_rerun
Permission: PCP_JOB_RUN

Creates a new job run with the same configuration as a previous job run. Useful for retrying failed jobs or re-executing successful automations.

Path Parameter:

  • id (integer): The job run ID to rerun

Response: CopilotJobRun object with the new job run details (HTTP 201 Created)

Example:

POST /job-run/456/rerun

Permissions​

The Studio API uses the following permission constants:

  • PCP_GENERAL_PERMISSION (pcp_general_permission): Required for viewing actions, executing interaction actions, and checking job run progress
  • PCP_JOB_RUN (pcp_job_run_permission): Required for managing job runs (list, cancel, rerun)
  • PCP_SEE_ALL_JOB_RUNS (pcp_job_runs_see_all_permission): Required for viewing job runs from all users
  • PCP_CONFIGURATION (pcp_configuration_permission): Required for managing copilot configuration

Common Response Codes​

  • 200 OK: Successful request
  • 201 Created: Resource created successfully (automation run, job rerun)
  • 400 Bad Request: Invalid request data
  • 401 Unauthorized: Missing or invalid authentication
  • 403 Forbidden: User lacks required permissions
  • 404 Not Found: Resource not found
  • 409 Conflict: Operation cannot be performed in current state

API Tags​

All endpoints are tagged with Bundle Copilot for OpenAPI documentation grouping.

Interaction Workflows​

The Copilot Bundle provides two distinct interaction workflows:

Chat (Multi-Turn)​

A conversational workflow where the user interacts with an AI model over multiple turns:

  1. Initialize the chat interaction (/actions/interaction/{name}/{interactionId}/initial)
  2. Send prompts to continue the conversation (/actions/interaction/{name}/{interactionId}/prompt) -- can be repeated
  3. Apply the final result to the target element (/actions/interaction/{name}/{interactionId}/apply)

One-Step (Single-Turn)​

A simple workflow where the interaction completes in a single request:

  1. Execute the interaction action (/actions/interaction/{name}/execute)

Available Events​

The following pre-response events are available for extending response data:

  • pre_response.actions -- Dispatched for each Action object before sending the actions list response
  • pre_response.job_runs -- Dispatched for each CopilotJobRun object before sending the job runs response
  • pre_response.job_runs.progress -- Dispatched for the CopilotJobRunProgress object before sending the progress response

Usage Examples​

Running an Automation Action​

  1. List available actions:

    GET /actions

  2. Run an automation action:

    POST /actions/automation/CarVariantGenerator/run

  3. Monitor progress:

    GET /job-run/123/progress

Using Chat Interactions​

  1. Start a chat interaction:

    POST /actions/interaction/OpenAITextGeneration/9875567/initial

  2. Send follow-up prompts:

    POST /actions/interaction/OpenAITextGeneration/9875567/prompt

  3. Apply the result:

    POST /actions/interaction/OpenAITextGeneration/9875567/apply

Using One-Step Interactions​

  1. Execute a one-step interaction: 
    POST /actions/interaction/HFTranslationPrompt/execute

Managing Job Runs​

  1. List all job runs:

    GET /job-runs?page=1&pageSize=25

  2. List running jobs only:

    GET /job-runs/running

  3. Cancel a running job:

    POST /job-run/123/cancel

  4. Rerun a previous job:

    POST /job-run/123/rerun