Campaign Chapters Service

Manage chapters within a campaign book, including their notes and assets.

Campaign chapters organize content within books. Each chapter can contain notes and assets. Chapters are numbered sequentially within their book and can be reordered using the renumber() method.

Usage

from vclient import chapters_service

chapters = chapters_service(
    campaign_id="CAMPAIGN_ID",
    book_id="BOOK_ID",
    on_behalf_of="USER_ID",
    company_id="COMPANY_ID"
)

Methods

CRUD Operations

Method	Returns	Description
`get(chapter_id, *, include=None)`	`CampaignChapterDetail`	Get a chapter by ID, optionally embedding `notes` or `assets`
`create(ChapterCreate, **kwargs)`	`CampaignChapter`	Create a new chapter
`update(chapter_id, ChapterUpdate, **kwargs)`	`CampaignChapter`	Update a chapter
`delete(chapter_id)`	`None`	Delete a chapter
`renumber(chapter_id, number)`	`CampaignChapter`	Change a chapter's position

Character Associations

Both create() and update() accept an optional character_ids: list[str] | None field on the request model.

Each ID must reference an active character in the same campaign, or the API returns a 400 ValidationError.
On update(): omit character_ids (or set it to None) to leave existing associations unchanged. Pass [] to clear all associations.

from vclient.models import ChapterCreate, ChapterUpdate

# Create a chapter with character associations
chapter = await chapters.create(ChapterCreate(
    name="The First Night",
    character_ids=["char-123", "char-456"],
))

# Clear all character associations
updated = await chapters.update(chapter.id, ChapterUpdate(character_ids=[]))

# Leave associations unchanged (omit the field)
updated = await chapters.update(chapter.id, ChapterUpdate(name="Renamed"))

Embedding Child Resources

The get() method accepts an optional include parameter that embeds child resources directly in the response, eliminating the need for follow-up requests.

Valid values (ChapterInclude type alias): "notes", "assets"

When a value is not included in the request, the corresponding field on CampaignChapterDetail is None. When requested, the field contains a list of fully populated objects — the same DTOs returned by the dedicated child endpoints.

from vclient import chapters_service

chapters = chapters_service(
    campaign_id="...", book_id="...", on_behalf_of="...", company_id="..."
)

# Embed notes and assets in a single request
chapter = await chapters.get("chapter_id", include=["notes", "assets"])
assert chapter.notes is not None   # list[Note]
assert chapter.assets is not None  # list[Asset]

Pagination

Method	Returns	Description
`get_page(limit?, offset?)`	`PaginatedResponse[CampaignChapter]`	Get a page of chapters
`list_all()`	`list[CampaignChapter]`	Get all chapters
`iter_all(limit?)`	`AsyncIterator[CampaignChapter]`	Iterate through all chapters

Assets

Method	Returns	Description
`get_assets_page(chapter_id, limit?, offset?)`	`PaginatedResponse[Asset]`	Get a page of assets
`list_all_assets(chapter_id)`	`list[Asset]`	Get all assets
`iter_all_assets(chapter_id, limit?)`	`AsyncIterator[Asset]`	Iterate through assets
`get_asset(chapter_id, asset_id)`	`Asset`	Get an asset
`upload_asset(chapter_id, filename, content)`	`Asset`	Upload an asset
`delete_asset(chapter_id, asset_id)`	`None`	Delete an asset

Notes

Method	Returns	Description
`get_notes_page(chapter_id, limit?, offset?)`	`PaginatedResponse[Note]`	Get a page of notes
`list_all_notes(chapter_id)`	`list[Note]`	Get all notes
`iter_all_notes(chapter_id, limit?)`	`AsyncIterator[Note]`	Iterate through notes
`get_note(chapter_id, note_id)`	`Note`	Get a note
`create_note(chapter_id, NoteCreate, **kwargs)`	`Note`	Create a note
`update_note(chapter_id, note_id, NoteUpdate, **kwargs)`	`Note`	Update a note
`delete_note(chapter_id, note_id)`	`None`	Delete a note

Examples

Create and Manage Chapters

from vclient.models import ChapterCreate, ChapterUpdate

# Create a chapter (preferred: use model object)
request = ChapterCreate(
    name="The First Night",
    description="Characters meet for the first time"
)
chapter = await chapters.create(request)
print(f"Created chapter #{chapter.number}: {chapter.name}")

# Alternative: pass fields as kwargs
chapter = await chapters.create(
    name="The First Night",
    description="Characters meet for the first time"
)

# Update a chapter
update = ChapterUpdate(name="The First Night: Introductions")
updated = await chapters.update(chapter.id, update)

# Reorder the chapter
await chapters.renumber(chapter.id, number=3)

# Delete a chapter
await chapters.delete(chapter.id)

Manage Chapter Notes

from vclient.models import NoteCreate, NoteUpdate

# Create a note
note_request = NoteCreate(title="Scene Notes", content="Important plot points...")
note = await chapters.create_note(chapter.id, note_request)

# Get a specific note
retrieved = await chapters.get_note(chapter.id, note.id)

# Update the note
update = NoteUpdate(content="Updated plot points...")
await chapters.update_note(chapter.id, note.id, update)

# List all chapter notes
all_notes = await chapters.list_all_notes(chapter.id)

Manage Chapter Assets

# Upload an asset for a chapter
with open("scene_diagram.png", "rb") as f:
    asset = await chapters.upload_asset(
        chapter.id,
        filename="scene_map.png",
        content=f.read(),
    )

# Get all chapter assets
all_assets = await chapters.list_all_assets(chapter.id)
for asset in all_assets:
    print(f"{asset.original_filename}: {asset.public_url}")

# Delete an asset
await chapters.delete_asset(chapter.id, asset.id)

See Response Models for CampaignChapter, Asset, Note, and related types.