Knowledge base

The Documents API lets you give Avatars access to domain-specific knowledge. Upload content that your Avatar can reference during conversations to provide accurate, contextual responses.

Token limit

Each Avatar supports up to 50,000 tokens of knowledge. We plan to increase this limit in the future.

Why use a knowledge base

A knowledge base helps your Avatar stay on topic and provide accurate information. Common use cases:

• Customer support: FAQs, product information, company policies
• Quizzes and games: Question banks, correct answers, scoring rules
• Education: Course material, reference content, learning objectives
• Brand experiences: Brand guidelines, messaging, product details

Supported content

Format	Description
Plain text	Unformatted text content
Markdown	Structured content with headings and formatting

More formats are planned for future releases.

Adding knowledge to an Avatar

The flow is: create a Document, then link it to your Avatar.

1. Create a Document

Node

import RunwayML from '@runwayml/sdk';

const client = new RunwayML();

const document = await client.documents.create({
  name: 'Product FAQ',
  content: '# Product FAQ\n\n## What is your return policy?\n\nWe offer a 30-day return policy...',
});

console.log('Document created:', document.id);

Python

from runwayml import RunwayML

client = RunwayML()

document = client.documents.create(
  name='Product FAQ',
  content='# Product FAQ\n\n## What is your return policy?\n\nWe offer a 30-day return policy...',
)

print('Document created:', document.id)

2. Update a Document

You can update a Document’s name, content, or both using the update method.

Node

await client.documents.update(document.id, {
  name: 'Updated Product FAQ',
  content: '# Product FAQ\n\n## What is your return policy?\n\nWe now offer a 60-day return policy...',
});

Python

client.documents.update(
  id=document.id,
  name='Updated Product FAQ',
  content='# Product FAQ\n\n## What is your return policy?\n\nWe now offer a 60-day return policy...',
)

Both fields are optional — provide only the fields you want to change.

3. Link the Document to your Avatar

Update your Avatar to attach the Document. This replaces any existing Document attachments.

Node

await client.avatars.update(avatarId, {
  documentIds: [document.id],
});

Python

client.avatars.update(
  avatar_id,
  document_ids=[document.id],
)

4. Start a Session

The Avatar now has access to the knowledge during conversations. Start a Session as usual:

Node

const session = await client.realtimeSessions.create({
  model: 'gwm1_avatars',
  avatar: {
    type: 'custom',
    avatarId: avatarId,
  },
});

Python

session = client.realtime_sessions.create(
  model='gwm1_avatars',
  avatar={
    'type': 'custom',
    'avatar_id': avatar_id,
  },
)

You can also manage Documents through the Developer Portal. See the API reference for all available endpoints.