Threads and Messages API — Conversation Persistence

Threads and messages in Ragen are pure persistence — they store conversation history in a structured, retrievable format. They do not run the language model or the RAG pipeline. When you need an AI-generated reply, call Chat Completions with your messages inline, then persist the result back to the thread yourself. This separation gives you full control over what gets saved and when.

The OpenAI Runs API (POST /v1/threads/{id}/runs), which automates the generate-and-save loop, is not yet implemented in Ragen. Use the manual loop described below in Generating AI responses.

Threads endpoints

POST   /v1/threads
GET    /v1/threads              (Ragen extension — OpenAI doesn't expose list)
GET    /v1/threads/{id}
POST   /v1/threads/{id}        (OpenAI convention — modify)
PATCH  /v1/threads/{id}        (REST alias)
DELETE /v1/threads/{id}

Authentication:

Authorization: Bearer YOUR_API_KEY

Create a thread

POST /v1/threads

array

Optional array of messages to seed the thread with on creation. Each message has a role (user or assistant) and a content string.

object

Arbitrary key-value metadata. Accepted and returned as-is.

string

Ragen extension. Thread title displayed in the dashboard sidebar.

string

Ragen extension. Bind the thread to a specific assistant using its assistant ID (the bare project UUID; the legacy asst-<projectId> form is still accepted). Optional, and it must agree with the key’s scope: a key bound to one assistant refuses any other with 403, and a knowledge-base key refuses the field entirely and opens the thread against the knowledge base. Omit it and the key decides. See Authentication.

List threads

GET /v1/threads — returns threads across your organization.

integer

default:"20"

Between 1 and 100.

string

default:"desc"

Sort order by created_at. Either asc or desc.

string

Thread ID cursor — returns threads created after the given ID.

Modify a thread

Both POST /v1/threads/{id} and PATCH /v1/threads/{id} accept title (Ragen extension) and metadata.

Delete a thread

DELETE /v1/threads/{id} — deletes the thread and all its messages. Returns:

{ "id": "thread-abc123", "object": "thread.deleted", "deleted": true }

If the organization has Delete threads turned off, the request is refused with 403 Forbidden and nothing is deleted:

{
  "statusCode": 403,
  "message": "This organization cannot delete threads",
  "error": "Forbidden"
}

The same setting refuses DELETE /v1/threads/{id}/messages/{message_id} with the same response, because deleting every message empties a thread just as well. A platform administrator controls the setting in the admin panel — see Organization features.

Messages endpoints

POST   /v1/threads/{id}/messages
GET    /v1/threads/{id}/messages
GET    /v1/threads/{id}/messages/{message_id}
DELETE /v1/threads/{id}/messages/{message_id}

Create a message

POST /v1/threads/{id}/messages — persists one turn on the thread. Does not run the model. Use Chat Completions when you need an AI-generated reply.

string

required

Either user (human turn) or assistant (AI turn, useful for backfilling history or importing transcripts).

string

required

The message text.

List and retrieve messages

GET /v1/threads/{id}/messages returns OpenAI thread.message objects with a typed content array. Each item is currently always a single text block — Ragen doesn’t store multimodal messages on threads today. GET /v1/threads/{id}/messages/{message_id} retrieves a single message.

Encrypted threads

Threads created through the Ragen dashboard with encryption enabled store message content as ciphertext. The API cannot decrypt this content — read endpoints return a placeholder:

{
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": {
        "value": "[encrypted — open this thread in the dashboard to view]",
        "annotations": []
      }
    }
  ]
}

Threads created through the API are never encrypted, so API-first workflows see plaintext throughout.

Generating AI responses

Threads are storage only. To generate a response and persist it, follow this manual loop:

Persist the user's message

POST /v1/threads/{thread_id}/messages
{ "role": "user", "content": "What is our return policy?" }

Call Chat Completions to run RAG

Pass the conversation history inline. Ragen retrieves relevant chunks and generates the reply.

POST /v1/chat/completions
{
  "assistant_id": "11111111-1111-4111-8111-111111111111",
  "messages": [
    { "role": "user", "content": "What is our return policy?" }
  ]
}

Persist the assistant's reply

Save the generated reply back to the thread.

POST /v1/threads/{thread_id}/messages
{ "role": "assistant", "content": "<reply from step 2>" }

Examples

TypeScript SDK
Python (openai SDK)

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

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

// Create a thread
const thread = await ragen.beta.threads.create({
  title: 'Support conversation',
  assistant_id: '11111111-1111-4111-8111-111111111111',
});

// Add a user message
await ragen.beta.threads.messages.create(thread.id, {
  role: 'user',
  content: 'What is our return policy?',
});

// Generate a reply
const completion = await ragen.chat.completions.create({
  assistantId: '11111111-1111-4111-8111-111111111111',
  messages: [{ role: 'user', content: 'What is our return policy?' }],
});
const reply = completion.choices[0].message.content;

// Persist the reply
await ragen.beta.threads.messages.create(thread.id, {
  role: 'assistant',
  content: reply,
});

// Read all messages
const messages = await ragen.beta.threads.messages.list(thread.id);
for (const m of messages.data) {
  console.log(m.role, m.content[0].text.value);
}

import os
from openai import OpenAI

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

# Create a thread with seed messages
t = client.beta.threads.create(
    messages=[
        {"role": "user", "content": "Hi!"},
        {"role": "assistant", "content": "Hello — how can I help?"},
    ],
    metadata={"channel": "support"},
)
print(t.id)

# Add a message
client.beta.threads.messages.create(
    t.id,
    role="user",
    content="What was my last question?",
)

# List messages
for m in client.beta.threads.messages.list(t.id):
    print(m.role, m.content[0].text.value)

# Delete thread
client.beta.threads.delete(t.id)

Rate limits

Scope	Limit
All threads + messages endpoints	20 requests / minute per IP

Getting Started

Endpoints

SDKs & Tools

Threads and Messages API — Conversation Persistence

Threads endpoints

Create a thread

List threads

Modify a thread

Delete a thread

Messages endpoints

Create a message

List and retrieve messages

Encrypted threads

Generating AI responses

Examples

Rate limits

​Threads endpoints

​Create a thread

​List threads

​Modify a thread

​Delete a thread

​Messages endpoints

​Create a message

​List and retrieve messages

​Encrypted threads

​Generating AI responses

​Examples

​Rate limits

Threads endpoints

Create a thread

List threads

Modify a thread

Delete a thread

Messages endpoints

Create a message

List and retrieve messages

Encrypted threads

Generating AI responses

Examples

Rate limits