---
title: "Set an agent's prompt"
method: PUT
path: "/v1/agent/{agentId}/prompts"
tags: ["Agent"]
---

# Set an agent's prompt

`PUT /v1/agent/{agentId}/prompts`

## Request

- Base URL: `https://api.roark.ai`
- URL: `https://api.roark.ai/v1/agent/{agentId}/prompts`
- Auth: HTTP bearer

Sets the agent's API-managed prompt. This is its own version history (`source: API_MANAGED`), separate from prompts observed on calls, edited in the app, or managed by config-as-code. Setting the same content twice is a no-op (no new version). Roark does not run your agent and no metric reads this prompt: it is stored and versioned for your reference.

## Path parameters

- `agentId` string, uuid, required

## Request body

- SetAgentPromptInput
  - `prompt` string, required: The prompt content to set.

## Response `200`

The prompt was set (or already matched the current version).

- object
  - `data` SetAgentPromptResponse, required
    - `promptId` string, uuid, required: The ID of the API-managed prompt lineage.
    - `versionNumber` integer, required: The current version number after the set.
    - `changed` boolean, required: True if a new version was appended; false if the content matched the current version (no-op).

## Other responses

- `401`: Unauthorized
- `404`: Not Found
- `500`: Internal Server Error

## Changes

> 188 revisions in range; 1 not diffed.

- **2026-09-09** `7ea77678cced`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/roarkhq/apis/roark-analytics-api/changes/v1/agent/:agentId/prompts/put.md)

---

[API](https://skmtc.dev/roarkhq/apis/roark-analytics-api.md) - [All operations](https://skmtc.dev/roarkhq/apis/roark-analytics-api/llms.txt) - [OpenAPI document](https://skmtc.dev/roarkhq/apis/roark-analytics-api/revisions/efc3377249d1?raw)