---
title: "Rename an expert or replace its instructions"
method: PATCH
path: "/api/v1/experts/{id}"
tags: ["Experts"]
---

# Rename an expert or replace its instructions

`PATCH /api/v1/experts/{id}`

## Request

- Base URL: `https://api.roma.app`
- URL: `https://api.roma.app/api/v1/experts/{id}`
- Auth: HTTP bearer

Update one of the user's experts: its name, its instructions, or both. `instructions` replaces the WHOLE body: read it with get_expert first and send the whole text with the change in it, a line that contradicts an existing one replacing that line rather than sitting beside it. A rename to a name the user already has is refused. The previous body stays in the expert's version history (list_versions, restore_version). Use it when the user says an expert missed something, should work differently, or should be called something else.

## Path parameters

- `id` string, required

## Request body

- object
  - `name` string, nullable: A new name. Omit, or pass null, to keep it.
  - `instructions` string, nullable: The whole standing instructions, as Markdown, replacing the body. Omit, or pass null, to keep it.
  - `baseUpdatedAt` string, nullable: The `updatedAt` get_expert returned; when the expert changed since, the write is refused and the body is read again.

## Response `200`

The tool's result.

- object
  - `id` string, required
  - `name` string, required
  - `firstLine` string, required: The opening line of its instructions.
  - `updatedAt` string, required
  - `webUrl` string, required: The expert's page in Roma on the web.
  - `changed` string[], required: Which of `name` and `instructions` changed.

## Other responses

- `400`: The request was understood and refused; the error says what to change.
- `401`: No usable bearer token.
- `404`: No such item for this account.
- `405`: The path exists but not with this method; Allow lists the ones that work.
- `429`: Over the rate limit; wait for Retry-After.

---

[API](https://skmtc.dev/roma/apis/roma-api.md) - [All operations](https://skmtc.dev/roma/apis/roma-api/llms.txt) - [OpenAPI document](https://skmtc.dev/roma/apis/roma-api/revisions/3dd91459b0fb?raw)