Lorebook API

The Lorebook API provides methods for programmatically managing Lorebook entries and categories. Scripts can create, read, update, and delete Lorebook content. Methods that create, modify, or delete Lorebook entries and categories require the script to have the lorebookEdit permission.

Lorebook Structure

Entries

Lorebook entries contain information that can be inserted into generation context when their activation keys are matched. Each entry has various settings that control when and how it activates. Lorebook entries are indentified by a unique ID. This ID can be set freely by scripts, but it’s recommended to use api.v1.uuid() to generate unique IDs. If you attempt to create two entries with the same ID an error will be thrown.

Reading Lorebook Content

Getting All Entries

To retrieve all Lorebook entries, use the api.v1.lorebook.entries function:

let allEntries = await api.v1.lorebook.entries();
for (let entry of allEntries) {
  api.v1.log(`Entry: ${entry.displayName}`);
}

Getting a Specific Entry

To retrieve a single entry by its ID, use the api.v1.lorebook.entry function:

let entry = await api.v1.lorebook.entry('entry-id-here');
if (entry) {
  api.v1.log(`Found entry: ${entry.displayName}`);
}

Getting All Categories

To retrieve all Lorebook categories, use the api.v1.lorebook.categories function:

let allCategories = await api.v1.lorebook.categories();
for (let category of allCategories) {
  api.v1.log(`Category: ${category.name}`);
}

Getting a Specific Category

To retrieve a single category by its ID, use the api.v1.lorebook.category function:

let category = await api.v1.lorebook.category('category-id-here');
if (category) {
  api.v1.log(`Found category: ${category.name}`);
}

Creating Lorebook Content

Creating an Entry

To create a new Lorebook entry, use the api.v1.lorebook.createEntry function. If no ID is provided, one will be generated automatically:

let entryId = await api.v1.lorebook.createEntry({
  text: 'Galena, the Witch of the Tower. Galena\'s eyes are obscured by a translucent ribbon...',
  displayName: 'Galena, the Witch of the Tower',
  keys: ['Galena', 'witch', 'ribbon', 'tower'],
  enabled: true
});
api.v1.log(`Created entry with ID: ${entryId}`);

Creating a Category

To create a new Lorebook category, use the api.v1.lorebook.createCategory function. If no ID is provided, one will be generated automatically:

let newCategory = await api.v1.lorebook.createCategory({
  name: 'Locations',
  enabled: true
});
api.v1.log(`Created category with ID: ${newCategory.id}`);

Updating Lorebook Content

Updating an Entry

To update an existing Lorebook entry, use the api.v1.lorebook.updateEntry function with the entry ID and the fields to update:

await api.v1.lorebook.updateEntry('entry-id-here', {
  text: 'Galena, the Retired Witch of the Tower. Galena now...',
  enabled: false
});

Only the fields you provide will be updated; other fields remain unchanged.

Updating a Category

To update an existing Lorebook category, use the api.v1.lorebook.updateCategory function:

await api.v1.lorebook.updateCategory('category-id-here', {
  name: 'World Locations',
  enabled: false
});

Deleting Lorebook Content

Deleting an Entry

To delete a Lorebook entry, use the api.v1.lorebook.removeEntry function:

await api.v1.lorebook.removeEntry('entry-id-here');

Deleting a Category

To delete a Lorebook category, use the api.v1.lorebook.removeCategory function:

await api.v1.lorebook.removeCategory('category-id-here');

Note that deleting a category does not delete its entries; they become uncategorized.

Working with Entry Selection

Scripts can respond to Lorebook entry selection through the onLorebookEntrySelected hook. This is useful for displaying entry-specific UI or performing actions when users navigate the Lorebook:

api.v1.hooks.register('onLorebookEntrySelected', async ({ entryId, categoryId }) => {
  if (entryId) {
    let entry = await api.v1.lorebook.entry(entryId);
    api.v1.log(`Selected entry: ${entry?.displayName}`);
  } else if (categoryId) {
    let category = await api.v1.lorebook.category(categoryId);
    api.v1.log(`Selected category: ${category?.name}`);
  }
});