---
title: "Create an expert"
method: POST
path: "/api/v1/experts"
tags: ["Experts"]
---

# Create an expert

`POST /api/v1/experts`

## Request

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

Create an expert for the user: a name and its whole standing instructions as Markdown (second person, present tense, what to do; the shape the user's other experts have). Use it on the user's explicit ask to create one, never because they described how they want one answer written. A name the user already has is refused. The new expert shows in Settings → Experts in Roma, where it answers in the user's chats when mentioned by name.

## Request body

- object
  - `name` string, required: The expert's name, how the user will call it in (two or three words, the way a job title reads).
  - `instructions` string, required: The whole standing instructions, as Markdown.

## Response `201`

Created; the body is the new item.

- 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.

## 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)