Create an assistant over your knowledge
Create an assistant in your own organisation, pointed at the collections it answers from. The server assigns the id, and a new assistant starts out active.
POST
/
assistants
curl --request POST "$MITHUNAI_URL/mithunai/api/v1/assistants" \
--header "Authorization: Bearer $MITHUNAI_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"name": "Developer docs assistant",
"knowledge_base_ids": ["a3c7e1f0-2b9d-4c56-8e14-7f0a9b3d6e21"],
"instruction": "Answer for developers integrating the public API. Prefer code samples.",
"description": "Answers questions on the developer portal"
}'
import os, requests
response = requests.post(
f"{os.environ['MITHUNAI_URL']}/mithunai/api/v1/assistants",
headers={"Authorization": f"Bearer {os.environ['MITHUNAI_API_KEY']}"},
json={
"name": "Developer docs assistant",
"knowledge_base_ids": ["a3c7e1f0-2b9d-4c56-8e14-7f0a9b3d6e21"],
"instruction": "Answer for developers integrating the public API. Prefer code samples.",
"description": "Answers questions on the developer portal",
},
timeout=60,
)
response.raise_for_status()
print(response.json())
const response = await fetch(`${process.env.MITHUNAI_URL}/mithunai/api/v1/assistants`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MITHUNAI_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
name: 'Developer docs assistant',
knowledge_base_ids: ['a3c7e1f0-2b9d-4c56-8e14-7f0a9b3d6e21'],
instruction: 'Answer for developers integrating the public API. Prefer code samples.',
description: 'Answers questions on the developer portal',
}),
})
console.log(await response.json())
{
"id": "5b1e9c2a-7d4f-4e3b-9a61-0c8f2d7e4a13",
"name": "Developer docs assistant",
"description": "Answers questions on the developer portal",
"status": "active",
"model": "anthropic/claude-sonnet-5",
"knowledge_base_ids": ["a3c7e1f0-2b9d-4c56-8e14-7f0a9b3d6e21"],
"instruction": "Answer for developers integrating the public API. Prefer code samples.",
"answerable": true,
"revision": 1,
"created_at": "2026-09-20T14:03:11.482190+00:00",
"updated_at": "2026-09-20T14:03:11.482190+00:00"
}
{
"code": "validation_error",
"message": "A knowledge base named by this assistant does not exist."
}
{ "code": "authorization_error", "message": "You do not have permission to perform this action." }
{ "code": "conflict", "message": "An assistant with that name already exists." }
The assistant is created in the organization your credential belongs to. You cannot name another organization, and you cannot choose the assistant’s
id: the server assigns it. A new assistant always starts with status set to active.
Every knowledge base you list must exist in your organization, or the request fails with 400. Assistant names are unique within an organization; a name that is already taken returns 409.
An assistant can answer questions only when it is active and has at least one knowledge base. The answerable field in the response tells you whether that is true. See Configure an assistant.
Creating an assistant requires the owner, admin or editor role. See Organizations and roles.
string
required
Display name. Leading and trailing whitespace is trimmed; the result must be 1 to 120 characters
on a single line, with no control, invisible formatting or line-separator characters.
string[]
default:"[]"
IDs (UUIDs) of the knowledge bases this assistant answers from. At most 20 after duplicates are
removed; order is kept. An assistant with none is created but is not
answerable.string
Model selector, either
provider/model or a bare model name. The provider must be one the
platform supports, and a bare model name must match exactly one model in the platform’s catalogue,
or the request fails with 400. A model whose provider your deployment has no credential for is
also refused with 400, never substituted, and so is a catalogued model that cannot answer
questions, such as an embedding model. Omitted, the deployment picks a chat model it can reach:
anthropic/claude-sonnet-5 when Anthropic is configured, otherwise the first catalogued chat
model a configured provider serves. GET /models lists what your deployment offers.string
Guidance added to the assistant’s answer policy. Before it is stored, control and invisible
formatting characters are removed, runs of blank lines are collapsed, and surrounding whitespace
is trimmed. Text longer than 8,000 characters is not refused: it is cut and ends with
[…truncated]. An empty or whitespace-only value is stored as null.string
default:"\"\""
Description for administrators, up to 500 characters on a single line. It is never sent to the
model.
Response
Returns201 Created with the full assistant.
string
required
The assistant’s ID (UUID).
string
required
Display name.
string
required
Description. Empty string when none was set.
string
required
Lifecycle status:
active, disabled or archived. Always active on creation.string
required
The model selector.
string[]
required
Knowledge bases the assistant answers from, in the order you gave.
string | null
required
The stored instruction, or
null when there is none.boolean
required
true when the assistant is active and has at least one knowledge base.integer
required
Concurrency revision. Starts at
1. Send it back on PATCH /assistants/{assistant_id}.string | null
required
When the assistant was created, ISO 8601 in UTC.
string | null
required
When the assistant was last changed, ISO 8601 in UTC.
curl --request POST "$MITHUNAI_URL/mithunai/api/v1/assistants" \
--header "Authorization: Bearer $MITHUNAI_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"name": "Developer docs assistant",
"knowledge_base_ids": ["a3c7e1f0-2b9d-4c56-8e14-7f0a9b3d6e21"],
"instruction": "Answer for developers integrating the public API. Prefer code samples.",
"description": "Answers questions on the developer portal"
}'
import os, requests
response = requests.post(
f"{os.environ['MITHUNAI_URL']}/mithunai/api/v1/assistants",
headers={"Authorization": f"Bearer {os.environ['MITHUNAI_API_KEY']}"},
json={
"name": "Developer docs assistant",
"knowledge_base_ids": ["a3c7e1f0-2b9d-4c56-8e14-7f0a9b3d6e21"],
"instruction": "Answer for developers integrating the public API. Prefer code samples.",
"description": "Answers questions on the developer portal",
},
timeout=60,
)
response.raise_for_status()
print(response.json())
const response = await fetch(`${process.env.MITHUNAI_URL}/mithunai/api/v1/assistants`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MITHUNAI_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
name: 'Developer docs assistant',
knowledge_base_ids: ['a3c7e1f0-2b9d-4c56-8e14-7f0a9b3d6e21'],
instruction: 'Answer for developers integrating the public API. Prefer code samples.',
description: 'Answers questions on the developer portal',
}),
})
console.log(await response.json())
{
"id": "5b1e9c2a-7d4f-4e3b-9a61-0c8f2d7e4a13",
"name": "Developer docs assistant",
"description": "Answers questions on the developer portal",
"status": "active",
"model": "anthropic/claude-sonnet-5",
"knowledge_base_ids": ["a3c7e1f0-2b9d-4c56-8e14-7f0a9b3d6e21"],
"instruction": "Answer for developers integrating the public API. Prefer code samples.",
"answerable": true,
"revision": 1,
"created_at": "2026-09-20T14:03:11.482190+00:00",
"updated_at": "2026-09-20T14:03:11.482190+00:00"
}
{
"code": "validation_error",
"message": "A knowledge base named by this assistant does not exist."
}
{ "code": "authorization_error", "message": "You do not have permission to perform this action." }
{ "code": "conflict", "message": "An assistant with that name already exists." }
Last modified on November 2, 2026
curl --request POST "$MITHUNAI_URL/mithunai/api/v1/assistants" \
--header "Authorization: Bearer $MITHUNAI_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"name": "Developer docs assistant",
"knowledge_base_ids": ["a3c7e1f0-2b9d-4c56-8e14-7f0a9b3d6e21"],
"instruction": "Answer for developers integrating the public API. Prefer code samples.",
"description": "Answers questions on the developer portal"
}'
import os, requests
response = requests.post(
f"{os.environ['MITHUNAI_URL']}/mithunai/api/v1/assistants",
headers={"Authorization": f"Bearer {os.environ['MITHUNAI_API_KEY']}"},
json={
"name": "Developer docs assistant",
"knowledge_base_ids": ["a3c7e1f0-2b9d-4c56-8e14-7f0a9b3d6e21"],
"instruction": "Answer for developers integrating the public API. Prefer code samples.",
"description": "Answers questions on the developer portal",
},
timeout=60,
)
response.raise_for_status()
print(response.json())
const response = await fetch(`${process.env.MITHUNAI_URL}/mithunai/api/v1/assistants`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MITHUNAI_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
name: 'Developer docs assistant',
knowledge_base_ids: ['a3c7e1f0-2b9d-4c56-8e14-7f0a9b3d6e21'],
instruction: 'Answer for developers integrating the public API. Prefer code samples.',
description: 'Answers questions on the developer portal',
}),
})
console.log(await response.json())
{
"id": "5b1e9c2a-7d4f-4e3b-9a61-0c8f2d7e4a13",
"name": "Developer docs assistant",
"description": "Answers questions on the developer portal",
"status": "active",
"model": "anthropic/claude-sonnet-5",
"knowledge_base_ids": ["a3c7e1f0-2b9d-4c56-8e14-7f0a9b3d6e21"],
"instruction": "Answer for developers integrating the public API. Prefer code samples.",
"answerable": true,
"revision": 1,
"created_at": "2026-09-20T14:03:11.482190+00:00",
"updated_at": "2026-09-20T14:03:11.482190+00:00"
}
{
"code": "validation_error",
"message": "A knowledge base named by this assistant does not exist."
}
{ "code": "authorization_error", "message": "You do not have permission to perform this action." }
{ "code": "conflict", "message": "An assistant with that name already exists." }