---
title: "Update Agent Insights project guidance"
method: PUT
path: "/v1/private/agent-insights/jobs/{projectId}/guidance"
tags: ["Agent Insights Jobs"]
---

# Update Agent Insights project guidance

`PUT /v1/private/agent-insights/jobs/{projectId}/guidance`

## Request

- Base URL: `http://localhost:5173/api`
- URL: `http://localhost:5173/api/v1/private/agent-insights/jobs/{projectId}/guidance`
- Auth: none declared

Saves the project guidance sent to every Agent Insights run, creating the job (disabled) if the project has none. Empty or whitespace-only clears it. The guidance version is bumped only when the text changes. 404 while guidance is not enabled.

## Path parameters

- `projectId` string, uuid, required

## Request body

- AgentInsightsGuidanceUpdate
  - `guidance` string, required: Project guidance for Agent Insights runs. Empty or whitespace-only clears it

## Response `200`

Job with the saved guidance

- AgentInsightsJob
  - `id` string, uuid
  - `project_id` string, uuid, required
  - `status` 'enabled' | 'disabled'
  - `auto_first_run_enrolled` boolean
  - `auto_first_run_at` string, date-time
  - `last_scan_at` string, date-time
  - `last_failure_reason` string
  - `last_failure_detail` string
  - `last_failed_at` string, date-time
  - `guidance` string: Project guidance sent to every run; null when none
  - `guidance_updated_by` string: Who last saved the guidance
  - `guidance_updated_at` string, date-time: When the guidance was last saved
  - `guidance_version` integer: Bumped each time the guidance text changes; 0 = never saved
  - `results_guidance_version` integer: Guidance version the current results were produced with; null = no run since guidance existed
  - `created_at` string, date-time
  - `created_by` string
  - `last_updated_at` string, date-time
  - `last_updated_by` string

## Other responses

- `403`: Forbidden
- `404`: Project not found, or guidance not enabled
- `422`: Guidance missing or over the length limit

## Changes

- **2026-10-16** `4343d6730050`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/comet-ml/apis/opik-rest-api/changes/v1/private/agent-insights/jobs/:projectId/guidance/put.md)

---

[API](https://skmtc.dev/comet-ml/apis/opik-rest-api.md) - [All operations](https://skmtc.dev/comet-ml/apis/opik-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/comet-ml/apis/opik-rest-api/revisions/0067fada8962?raw)