Assistants API — Create and Manage Ragen AI Projects

In Ragen, an assistant is a project — a named container with its own knowledge base, system instructions, and settings. The Assistants API is an OpenAI-compatible CRUD surface over your projects, which means you can use the openai Python or Node SDK with base_url pointed at your Ragen instance to create, list, update, and delete assistants without writing custom HTTP code.

Endpoints

POST   /v1/assistants
GET    /v1/assistants
GET    /v1/assistants/{id}
POST   /v1/assistants/{id}   (OpenAI convention — modify)
PATCH  /v1/assistants/{id}   (REST alias — same as POST /:id)
DELETE /v1/assistants/{id}

Authentication:

Authorization: Bearer YOUR_API_KEY

Assistants are scoped to the API key. A key scoped to the knowledge base — the default — sees every assistant its organization owns, which is what an OpenAI client expects from client.assistants.list(). A key created for one assistant sees, and can change, that one only: any other is refused with 403, and such a key cannot create or delete an assistant at all. See Authentication.

OpenAI field mapping

Ragen maps OpenAI assistant fields to Ragen project concepts:

OpenAI field	Ragen meaning	Notes
`id`	`<projectId>`	The bare project UUID. The legacy `asst-<projectId>` form is still accepted wherever an assistant ID is sent
`name`	Project title
`instructions`	Per-project system prompt	Merged on top of the org default
`model`	—	Read-through from org default; per-project override not yet persisted
`temperature`	—	Accepted and stored for SDK compatibility; same note as `model`
`tools`	`[{"type": "file_search"}]`	RAG is always on — returned as a constant
`description`, `metadata`, `tool_resources`, `top_p`, `response_format`	—	Accepted for SDK compatibility; returned as constants

Create an assistant

POST /v1/assistants

string

required

The project title displayed in the dashboard.

string

Per-project system prompt. Merged on top of the organization’s default instructions. Pass an empty string to clear any existing instructions.

string

Accepted for OpenAI SDK compatibility; not yet persisted as a per-project override.

number

Accepted for OpenAI SDK compatibility; not yet persisted as a per-project override.

string

Accepted for OpenAI SDK compatibility; returned as-is.

object

Accepted for OpenAI SDK compatibility; returned as-is.

List, retrieve, and modify

GET /v1/assistants returns every assistant the key can reach — the whole organization for a knowledge-base key, or the single bound one. GET /v1/assistants/{id} retrieves a single assistant. Both POST /v1/assistants/{id} and PATCH /v1/assistants/{id} update an existing assistant — every field is optional, and they accept the same fields as create.

Delete an assistant

DELETE /v1/assistants/{id} — deletes the project and returns:

{ "id": "11111111-1111-4111-8111-111111111111", "object": "assistant.deleted", "deleted": true }

Self-delete protection: You cannot delete the assistant your API key is bound to — that would revoke the key’s own context. Attempting it returns a 400 error. A key scoped to one assistant therefore deletes nothing at all: its own is refused here, and every other one is refused as out of scope with 403.

{
  "error": {
    "message": "Cannot delete the assistant this API key is bound to. Rotate the key first, then retry.",
    "type": "invalid_request_error"
  }
}

This prevents accidentally breaking your own chat and files context. Issue or rotate to a different key first if you need to delete the bound project.

Examples

TypeScript SDK
Python (openai SDK)
curl

import { Ragen } from '@webamigos/ragen-sdk-ts';

const ragen = new Ragen({ apiKey: process.env.RAGEN_API_KEY });

// Create
const assistant = await ragen.beta.assistants.create({
  name: 'Support Bot',
  instructions: 'Respond concisely. If unsure, say so.',
});
console.log(assistant.id); // 11111111-1111-4111-8111-111111111111...

// List
const assistants = await ragen.beta.assistants.list();
for (const a of assistants.data) {
  console.log(a.id, a.name);
}

// Retrieve
const a = await ragen.beta.assistants.retrieve('11111111-1111-4111-8111-111111111111');
console.log(a.instructions);

// Update
await ragen.beta.assistants.update('11111111-1111-4111-8111-111111111111', {
  name: 'Support Bot v2',
});

import os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ["RAGEN_BASE_URL"],
    api_key=os.environ["RAGEN_API_KEY"],
)

# Create
a = client.beta.assistants.create(
    name="Support Bot",
    instructions="Respond concisely. If unsure, say so.",
)
print(a.id)

# List
for a in client.beta.assistants.list():
    print(a.id, a.name)

# Retrieve
a = client.beta.assistants.retrieve("11111111-1111-4111-8111-111111111111")

# Update
a = client.beta.assistants.update("11111111-1111-4111-8111-111111111111", name="Support Bot v2")

# Create
curl -X POST $RAGEN_BASE_URL/assistants \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Bot",
    "instructions": "Respond concisely. If unsure, say so."
  }'

# List
curl $RAGEN_BASE_URL/assistants \
  -H "Authorization: Bearer YOUR_API_KEY"

# Retrieve
curl $RAGEN_BASE_URL/assistants/11111111-1111-4111-8111-111111111111 \
  -H "Authorization: Bearer YOUR_API_KEY"

# Update
curl -X PATCH $RAGEN_BASE_URL/assistants/11111111-1111-4111-8111-111111111111 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Support Bot v2"}'

# Delete
curl -X DELETE $RAGEN_BASE_URL/assistants/11111111-1111-4111-8111-111111111111 \
  -H "Authorization: Bearer YOUR_API_KEY"

Rate limits

Scope	Limit
All assistant endpoints	20 requests / minute per IP

Getting Started

Endpoints

SDKs & Tools

Assistants API — Create and Manage Ragen AI Projects

Endpoints

OpenAI field mapping

Create an assistant

List, retrieve, and modify

Delete an assistant

Examples

Rate limits

​Endpoints

​OpenAI field mapping

​Create an assistant

​List, retrieve, and modify

​Delete an assistant

​Examples

​Rate limits

Endpoints

OpenAI field mapping

Create an assistant

List, retrieve, and modify

Delete an assistant

Examples

Rate limits