Create your assistant

An assistant brings together instructions, a model and a conversation memory. You create it through the API, then talk to it in threads.

On this page

Access
Create an assistant
Fields
Read, update, delete

Access

Assistant routes act on behalf of a user. They require that user’s Learnya access token, obtained through OAuth for the https://api.learnya.ai audience. API keys only give access to the models.

Create an assistant

POST /v1/assistant Creates the assistant and returns its ID.

curl https://api.learnya.ai/v1/assistant \
  -H "Authorization: Bearer $LEARNYA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Billing desk",
    "model": "learnya-flash",
    "instructions": "Answer billing questions plainly.",
    "visibility": "private",
    "contextWindow": { "mode": "last_n", "historyLimit": 20 }
  }'

import os
import requests

API = "https://api.learnya.ai/v1"
TOKEN = os.environ["LEARNYA_TOKEN"]
HEADERS = {"Authorization": f"Bearer {TOKEN}"}

assistant = requests.post(
    f"{API}/assistant",
    headers=HEADERS,
    json={
        "name": "Billing desk",
        "model": "learnya-flash",
        "instructions": "Answer billing questions plainly.",
        "visibility": "private",
        "contextWindow": {"mode": "last_n", "historyLimit": 20},
    },
).json()
print(assistant["id"])

const API = "https://api.learnya.ai/v1"
const headers = {
  Authorization: `Bearer ${process.env.LEARNYA_TOKEN}`,
  "Content-Type": "application/json",
}

const response = await fetch(`${API}/assistant`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    name: "Billing desk",
    model: "learnya-flash",
    instructions: "Answer billing questions plainly.",
    visibility: "private",
    contextWindow: { mode: "last_n", historyLimit: 20 },
  }),
})
const assistant = await response.json()
console.log(assistant.id)

interface Assistant {
  id: string
  name: string
  model: string
  instructions?: string | null
  visibility: "private" | "org" | "instance"
  createdAt: string
}

const API = "https://api.learnya.ai/v1"
const headers = {
  Authorization: `Bearer ${process.env.LEARNYA_TOKEN}`,
  "Content-Type": "application/json",
}

const response = await fetch(`${API}/assistant`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    name: "Billing desk",
    model: "learnya-flash",
    instructions: "Answer billing questions plainly.",
    visibility: "private",
    contextWindow: { mode: "last_n", historyLimit: 20 },
  }),
})
const assistant = (await response.json()) as Assistant
console.log(assistant.id)

Response

{
  "id": "6f1c2b0e-3a4d-4c8e-9b7a-2d5e8f1a0c34",
  "name": "Billing desk",
  "instructions": "Answer billing questions plainly.",
  "model": "learnya-flash",
  "tools": [],
  "responseFormat": { "type": "text" },
  "contextWindow": { "mode": "last_n", "historyLimit": 20 },
  "visibility": "private",
  "ownerUserId": "0b9d4e2a-7c1f-4a6b-8e3d-5f2a9c7b1e08",
  "createdAt": "2026-10-09T09:41:12.000Z"
}

Fields

nametextrequired: Its name, as people see it in Learnya.
modeltextrequired: The model that powers it: learnya-flash or learnya-max.
instructionstext: Its instructions, up to 500,000 characters.
visibilitytext: private restricts it to the person who creates it. org and instance share it with the organisation or the whole workspace, and require admin rights.
contextWindowobject: What it rereads from a thread: full, none, or the latest messages with last_n and historyLimit, from 1 to 500.
responseFormatobject: text, or json with a schema to read the response in your code.

Read, update, delete

GET /v1/assistants The assistants the user can use.

GET /v1/assistant/{id} A single assistant.

PUT /v1/assistant/{id} Updates the fields you send, and only those.

DELETE /v1/assistant/{id} Deletes the assistant.

Only the person who created an assistant and the workspace administrators can update or delete it.