Operations

Operations are how your plugin reads and changes the writer’s projects. Each one takes a JSON object and returns one, and your plugin calls them through the host functions (every kit has a wrapper for this).

Your plugin can only call the operations its manifest asks for under [permissions], and the writer sees that list before installing it. You can ask for operations by name, or for a whole group at once: for example, content:read covers every operation that reads a project. Destructive operations, the ones that delete things, are never included in a group; you have to name each one.

The Kotlin and Rust kits have a typed function for each operation, shown under its description: see Hammer and hammer::ops. An … stands for the optional inputs, which Kotlin takes as named parameters and Rust in an options struct. In C, call an operation by name with hammer_call.

Your plugin can call ops.list to see which operations it’s allowed to use. It needs permission for that too, which content:read includes.

In the tables below, an input field marked optional can be left out. Outputs always include every field.

account

`account.status`

read account:read

The sync server and account this install uses, and optionally whether the server still accepts it.

Kotlin: Hammer.account.status(…)
Rust: ops::account::status(AccountStatusOptions { … })

Input

Field	Type	Meaning
`check` optional	boolean	Ask the server whether the stored token is still good; needs the network.

Output

Field	Type	Meaning
`server`	string or null
`ssl`	boolean or null
`email`	string or null
`loggedIn`	boolean
`tokenValid`	boolean or null	Null unless checked.

backup

`backup.create`

write content:write

Back up a project's saved files.

Kotlin: Hammer.backup.create(project)
Rust: ops::backup::create(project)

Input

Field	Type	Meaning
`project`	string	The project's name, or its server project id.

Output

Field	Type	Meaning
`date`	string

`backup.list`

read content:read

A project's backups, oldest first.

Kotlin: Hammer.backup.list(project)
Rust: ops::backup::list(project)

Input

Field	Type	Meaning
`project`	string	The project's name, or its server project id.

Output

Field	Type	Meaning
`backups`	list of objects
`backups[].date`	string

draft

`draft.apply`

prose content:prose

Replace a scene's text with one of its drafts, saving the replaced text as a draft first.

Kotlin: Hammer.draft.apply(project, id)
Rust: ops::draft::apply(project, id)

Input

Field	Type	Meaning
`project`	string
`id`	integer

Output

Field	Type	Meaning
`sceneId`	integer
`previousDraftId`	integer or null	The draft holding the text it replaced; null when the text was unchanged.
`wordCount`	integer

`draft.create`

write content:write

Save a scene's current text as a named draft.

Kotlin: Hammer.draft.create(project, sceneId, name)
Rust: ops::draft::create(project, scene_id, name)

Input

Field	Type	Meaning
`project`	string
`sceneId`	integer
`name`	string

Output

Field	Type	Meaning
`id`	integer
`name`	string
`created`	string

`draft.delete`

destructive content:by name

Delete a draft for good.

Kotlin: Hammer.draft.delete(project, id)
Rust: ops::draft::delete(project, id)

Input

Field	Type	Meaning
`project`	string
`id`	integer

Output

Field	Type	Meaning
`id`	integer
`name`	string
`created`	string

`draft.list`

read content:read

A scene's saved drafts, oldest first.

Kotlin: Hammer.draft.list(project, sceneId)
Rust: ops::draft::list(project, scene_id)

Input

Field	Type	Meaning
`project`	string
`sceneId`	integer

Output

Field	Type	Meaning
`drafts`	list of objects
`drafts[].id`	integer
`drafts[].name`	string
`drafts[].created`	string

`draft.read`

read content:read

A draft's markdown.

Kotlin: Hammer.draft.read(project, id)
Rust: ops::draft::read(project, id)

Input

Field	Type	Meaning
`project`	string
`id`	integer

Output

Field	Type	Meaning
`id`	integer
`sceneId`	integer
`name`	string
`created`	string
`markdown`	string

entry

`entry.create`

write content:write

Add an encyclopedia entry to a project.

Kotlin: Hammer.entry.create(project, name, type, text, …)
Rust: ops::entry::create(project, name, r#type, text, EntryCreateOptions { … })

Input

Field	Type	Meaning
`project`	string
`name`	string
`type`	one of "person", "place", "thing", "event", "idea"
`text`	string
`tags` optional	list of strings
`aliases` optional	list of strings	Other names the entry goes by, matched in scenes like its name.

Output

Field	Type	Meaning
`id`	integer
`name`	string
`type`	one of "person", "place", "thing", "event", "idea"
`text`	string
`tags`	list of strings
`aliases`	list of strings
`hasImage`	boolean
`images` optional	list of integers	Image ids in order, primary first. An id can name an image no longer in the project.
`referencedBy`	list of integers	Scene ids whose references to this entry have been confirmed.

`entry.delete`

destructive content:by name

Delete an encyclopedia entry for good. Its images stay in the project.

Kotlin: Hammer.entry.delete(project, id)
Rust: ops::entry::delete(project, id)

Input

Field	Type	Meaning
`project`	string
`id`	integer

Output

Field	Type	Meaning
`id`	integer
`name`	string
`type`	one of "person", "place", "thing", "event", "idea"
`aliases` optional	list of strings	Other names the entry goes by.

`entry.images.add`

write content:write

Add an image already in the project to the end of an encyclopedia entry's images.

Kotlin: Hammer.entry.images.add(project, id, imageId)
Rust: ops::entry::images::add(project, id, image_id)

Input

Field	Type	Meaning
`project`	string
`id`	integer	The entry.
`imageId`	integer

Output

Field	Type	Meaning
`images`	list of objects
`images[].id`	integer
`images[].name`	string
`images[].extension`	string	One of [ImageFormat.ALLOWED_EXTENSIONS].

`entry.images.import`

write content:write

Add a new image to the project, named after an encyclopedia entry, and to the end of the entry's images. The extension is jpg, jpeg, png, webp, or svg, and must match the image.

Kotlin: Hammer.entry.images.`import`(project, id, extension, content)
Rust: ops::entry::images::import(project, id, extension, content)

Input

Field	Type	Meaning
`project`	string
`id`	integer	The entry.
`extension`	string	One of [ImageFormat.ALLOWED_EXTENSIONS].
`content`	base64 string

Output

Field	Type	Meaning
`images`	list of objects
`images[].id`	integer
`images[].name`	string
`images[].extension`	string	One of [ImageFormat.ALLOWED_EXTENSIONS].

`entry.images.list`

read content:read

The images an encyclopedia entry shows, primary first.

Kotlin: Hammer.entry.images.list(project, id)
Rust: ops::entry::images::list(project, id)

Input

Field	Type	Meaning
`project`	string
`id`	integer

Output

Field	Type	Meaning
`images`	list of objects
`images[].id`	integer
`images[].name`	string
`images[].extension`	string	One of [ImageFormat.ALLOWED_EXTENSIONS].

`entry.images.primary`

write content:write

Make one of an encyclopedia entry's images its primary image, moving it first.

Kotlin: Hammer.entry.images.primary(project, id, imageId)
Rust: ops::entry::images::primary(project, id, image_id)

Input

Field	Type	Meaning
`project`	string
`id`	integer	The entry.
`imageId`	integer

Output

Field	Type	Meaning
`images`	list of objects
`images[].id`	integer
`images[].name`	string
`images[].extension`	string	One of [ImageFormat.ALLOWED_EXTENSIONS].

`entry.images.remove`

write content:write

Take an image off an encyclopedia entry. The image stays in the project.

Kotlin: Hammer.entry.images.remove(project, id, imageId)
Rust: ops::entry::images::remove(project, id, image_id)

Input

Field	Type	Meaning
`project`	string
`id`	integer	The entry.
`imageId`	integer

Output

Field	Type	Meaning
`images`	list of objects
`images[].id`	integer
`images[].name`	string
`images[].extension`	string	One of [ImageFormat.ALLOWED_EXTENSIONS].

`entry.list`

read content:read

A project's encyclopedia entries, with their aliases, optionally only one type or those with a tag.

Kotlin: Hammer.entry.list(project, …)
Rust: ops::entry::list(project, EntryListOptions { … })

Input

Field	Type	Meaning
`project`	string
`type` optional	one of "person", "place", "thing", "event", "idea" or null
`tag` optional	string or null

Output

Field	Type	Meaning
`entries`	list of objects
`entries[].id`	integer
`entries[].name`	string
`entries[].type`	one of "person", "place", "thing", "event", "idea"
`entries[].aliases` optional	list of strings	Other names the entry goes by.

`entry.read`

read content:read

An encyclopedia entry, with the scenes confirmed to reference it.

Kotlin: Hammer.entry.read(project, id)
Rust: ops::entry::read(project, id)

Input

Field	Type	Meaning
`project`	string
`id`	integer

Output

Field	Type	Meaning
`id`	integer
`name`	string
`type`	one of "person", "place", "thing", "event", "idea"
`text`	string
`tags`	list of strings
`aliases`	list of strings
`hasImage`	boolean
`images` optional	list of integers	Image ids in order, primary first. An id can name an image no longer in the project.
`referencedBy`	list of integers	Scene ids whose references to this entry have been confirmed.

`entry.update`

write content:write

Replace an encyclopedia entry's text, and its name, tags, or aliases when given.

Kotlin: Hammer.entry.update(project, id, text, …)
Rust: ops::entry::update(project, id, text, EntryUpdateOptions { … })

Input

Field	Type	Meaning
`project`	string
`id`	integer
`text`	string
`name` optional	string or null
`tags` optional	list of strings or null
`aliases` optional	list of strings or null

Output

Field	Type	Meaning
`id`	integer
`name`	string
`type`	one of "person", "place", "thing", "event", "idea"
`text`	string
`tags`	list of strings
`aliases`	list of strings
`hasImage`	boolean
`images` optional	list of integers	Image ids in order, primary first. An id can name an image no longer in the project.
`referencedBy`	list of integers	Scene ids whose references to this entry have been confirmed.

export

`export.formats`

read content:read

The formats project.export can produce.

Kotlin: Hammer.export.formats()
Rust: ops::export::formats()

Input

Takes no input: pass {}.

Output

Field	Type	Meaning
`formats`	list of objects
`formats[].id`	string
`formats[].fileExtension`	string
`formats[].mimeType`	string

idea

`idea.archive`

write content:write

Archive a story idea.

Kotlin: Hammer.idea.archive(id)
Rust: ops::idea::archive(id)

Input

Field	Type	Meaning
`id`	string

Output

Field	Type	Meaning
`id`	string
`title`	string or null
`content`	string
`tags`	list of strings
`created`	string
`updated`	string
`promoted`	string or null
`archived`	string or null

`idea.create`

write content:write

Add a story idea.

Kotlin: Hammer.idea.create(content, …)
Rust: ops::idea::create(content, IdeaCreateOptions { … })

Input

Field	Type	Meaning
`content`	string
`title` optional	string or null
`tags` optional	list of strings

Output

Field	Type	Meaning
`id`	string
`title`	string or null
`content`	string
`tags`	list of strings
`created`	string
`updated`	string
`promoted`	string or null
`archived`	string or null

`idea.delete`

destructive content:by name

Delete a story idea for good.

Kotlin: Hammer.idea.delete(id)
Rust: ops::idea::delete(id)

Input

Field	Type	Meaning
`id`	string

Output

Field	Type	Meaning
`id`	string
`title`	string or null
`content`	string
`tags`	list of strings
`created`	string
`updated`	string
`promoted`	string or null
`archived`	string or null

`idea.list`

read content:read

Story ideas, which belong to the account rather than a project.

Kotlin: Hammer.idea.list(…)
Rust: ops::idea::list(IdeaListOptions { … })

Input

Field	Type	Meaning
`archived` optional	boolean or null	True for only archived ideas, false for only active ones; omitted for both.

Output

Field	Type	Meaning
`ideas`	list of objects
`ideas[].id`	string
`ideas[].title`	string or null
`ideas[].content`	string
`ideas[].tags`	list of strings
`ideas[].created`	string
`ideas[].updated`	string
`ideas[].promoted`	string or null
`ideas[].archived`	string or null

`idea.unarchive`

write content:write

Return an archived story idea to the active ones.

Kotlin: Hammer.idea.unarchive(id)
Rust: ops::idea::unarchive(id)

Input

Field	Type	Meaning
`id`	string

Output

Field	Type	Meaning
`id`	string
`title`	string or null
`content`	string
`tags`	list of strings
`created`	string
`updated`	string
`promoted`	string or null
`archived`	string or null

`idea.update`

write content:write

Replace a story idea's text, and its title or tags when given. An empty title clears it.

Kotlin: Hammer.idea.update(id, content, …)
Rust: ops::idea::update(id, content, IdeaUpdateOptions { … })

Input

Field	Type	Meaning
`id`	string
`content`	string
`title` optional	string or null	Left out, unchanged; empty, cleared.
`tags` optional	list of strings or null

Output

Field	Type	Meaning
`id`	string
`title`	string or null
`content`	string
`tags`	list of strings
`created`	string
`updated`	string
`promoted`	string or null
`archived`	string or null

image

`image.add`

write content:write

Add an image to a project. The extension is jpg, jpeg, png, webp, or svg, and must match the image.

Kotlin: Hammer.image.add(project, name, extension, content)
Rust: ops::image::add(project, name, extension, content)

Input

Field	Type	Meaning
`project`	string
`name`	string
`extension`	string	One of [ImageFormat.ALLOWED_EXTENSIONS].
`content`	base64 string

Output

Field	Type	Meaning
`id`	integer
`name`	string
`extension`	string	One of [ImageFormat.ALLOWED_EXTENSIONS].
`inUse`	boolean	Whether an entry or a text in the project uses the image.

`image.delete`

destructive content:by name

Delete an image for good, first taking it out of every entry and text that uses it, and the project cover.

Kotlin: Hammer.image.delete(project, id)
Rust: ops::image::delete(project, id)

Input

Field	Type	Meaning
`project`	string
`id`	integer

Output

Field	Type	Meaning
`id`	integer
`name`	string
`extension`	string
`removedFrom`	list of objects	Everything the image was taken out of before it was deleted.
`removedFrom[].kind`	one of "scene", "note", "timeline", "entry", "draft", "image", "cover"
`removedFrom[].id` optional	integer or null	Null for [ImageUserKind.Cover], which is not an entity.

`image.get`

read content:read

One image's name, extension, and bytes.

Kotlin: Hammer.image.get(project, id)
Rust: ops::image::get(project, id)

Input

Field	Type	Meaning
`project`	string
`id`	integer

Output

Field	Type	Meaning
`id`	integer
`name`	string
`extension`	string
`content`	base64 string

`image.list`

read content:read

A project's images, with whether anything in the project uses each one.

Kotlin: Hammer.image.list(project)
Rust: ops::image::list(project)

Input

Field	Type	Meaning
`project`	string	The project's name, or its server project id.

Output

Field	Type	Meaning
`images`	list of objects
`images[].id`	integer
`images[].name`	string
`images[].extension`	string	One of [ImageFormat.ALLOWED_EXTENSIONS].
`images[].inUse`	boolean	Whether an entry or a text in the project uses the image.

`image.rename`

write content:write

Rename an image.

Kotlin: Hammer.image.rename(project, id, name)
Rust: ops::image::rename(project, id, name)

Input

Field	Type	Meaning
`project`	string
`id`	integer
`name`	string

Output

Field	Type	Meaning
`id`	integer
`name`	string
`extension`	string	One of [ImageFormat.ALLOWED_EXTENSIONS].
`inUse`	boolean	Whether an entry or a text in the project uses the image.

`image.replace`

write content:write

Replace an image's bytes, keeping its id, so everything that uses it shows the new image. The extension is jpg, jpeg, png, webp, or svg, and must match the image.

Kotlin: Hammer.image.replace(project, id, extension, content)
Rust: ops::image::replace(project, id, extension, content)

Input

Field	Type	Meaning
`project`	string
`id`	integer
`extension`	string	One of [ImageFormat.ALLOWED_EXTENSIONS]; it may differ from the image's current one.
`content`	base64 string

Output

Field	Type	Meaning
`id`	integer
`name`	string
`extension`	string	One of [ImageFormat.ALLOWED_EXTENSIONS].
`inUse`	boolean	Whether an entry or a text in the project uses the image.

note

`note.create`

write content:write

Add a note to a project.

Kotlin: Hammer.note.create(project, content, …)
Rust: ops::note::create(project, content, NoteCreateOptions { … })

Input

Field	Type	Meaning
`project`	string
`content`	string
`tags` optional	list of strings

Output

Field	Type	Meaning
`id`	integer
`created`	string
`tags`	list of strings
`content`	string

`note.delete`

destructive content:by name

Delete a note for good.

Kotlin: Hammer.note.delete(project, id)
Rust: ops::note::delete(project, id)

Input

Field	Type	Meaning
`project`	string
`id`	integer

Output

Field	Type	Meaning
`id`	integer
`created`	string
`tags`	list of strings
`content`	string

`note.list`

read content:read

A project's notes, optionally only those with a tag.

Kotlin: Hammer.note.list(project, …)
Rust: ops::note::list(project, NoteListOptions { … })

Input

Field	Type	Meaning
`project`	string
`tag` optional	string or null

Output

Field	Type	Meaning
`notes`	list of objects
`notes[].id`	integer
`notes[].created`	string
`notes[].tags`	list of strings
`notes[].content`	string

`note.read`

read content:read

One note.

Kotlin: Hammer.note.read(project, id)
Rust: ops::note::read(project, id)

Input

Field	Type	Meaning
`project`	string
`id`	integer

Output

Field	Type	Meaning
`id`	integer
`created`	string
`tags`	list of strings
`content`	string

`note.update`

write content:write

Replace a note's text, and its tags when given.

Kotlin: Hammer.note.update(project, id, content, …)
Rust: ops::note::update(project, id, content, NoteUpdateOptions { … })

Input

Field	Type	Meaning
`project`	string
`id`	integer
`content`	string
`tags` optional	list of strings or null	Left out, the tags stay as they are.

Output

Field	Type	Meaning
`id`	integer
`created`	string
`tags`	list of strings
`content`	string

ops

`ops.list`

read content:read

Every operation you may call, with JSON schemas for its input and output.

Kotlin: Hammer.ops.list()
Rust: ops::ops::list()

Input

Takes no input: pass {}.

Output

Field	Type	Meaning
`operations`	list of objects
`operations[].name`	string
`operations[].description`	string
`operations[].access`	one of "read", "write", "prose", "destructive"
`operations[].scope`	one of "content", "account", "plugins"
`operations[].input`	map of string to any
`operations[].output`	map of string to any

plugin

`plugin.list`

read plugins:read

The installed runtime plugins, and what each may use.

Kotlin: Hammer.plugin.list()
Rust: ops::plugin::list()

Input

Takes no input: pass {}.

Output

Field	Type	Meaning
`plugins`	list of objects
`plugins[].id`	string
`plugins[].name` optional	string or null	Null, as are [version] and [description], when its package can no longer be read.
`plugins[].version` optional	string or null
`plugins[].description` optional	string or null
`plugins[].enabled`	boolean
`plugins[].operations` optional	list of strings	The operations it may use.
`plugins[].http` optional	list of strings	Hosts it may send what the user writes to.
`plugins[].userHostSetting` optional	string or null	The setting holding an address it may also send what the user writes to.

project

`project.create`

write content:write

Create an empty project.

Kotlin: Hammer.project.create(name)
Rust: ops::project::create(name)

Input

Field	Type	Meaning
`name`	string

Output

Field	Type	Meaning
`name`	string

`project.delete`

destructive content:by name

Delete a project, and everything in it, for good. It must not be open in Hammer.

Kotlin: Hammer.project.delete(project)
Rust: ops::project::delete(project)

Input

Field	Type	Meaning
`project`	string	The project's name, or its server project id.

Output

Field	Type	Meaning
`name`	string

`project.export`

read content:read

Export a project, or some of its scenes, in one of the formats from export.formats.

Kotlin: Hammer.project.export(project, format, …)
Rust: ops::project::export(project, format, ProjectExportOptions { … })

Input

Field	Type	Meaning
`project`	string
`format`	string	An id from export.formats.
`sceneIds` optional	list of integers or null	Limits the export to these scenes; omitted exports the whole story.
`treatTopLevelAsChapters` optional	boolean

Output

Field	Type	Meaning
`fileName`	string
`mimeType`	string
`content`	base64 string

`project.import`

prose content:prose

Create a project from a Markdown or RTF manuscript, split into scenes by its headings or a chapter pattern.

Kotlin: Hammer.project.`import`(format, content, …)
Rust: ops::project::import(format, content, ProjectImportOptions { … })

Input

Field	Type	Meaning
`name` optional	string or null	Left out, the title the file gives itself.
`format`	one of "markdown", "rtf"
`content`	base64 string
`markdownSplit` optional	one of "auto", "h1", "h2", "pattern"
`rtfSplit` optional	one of "formatting", "pattern", "single"
`chapterPattern` optional	string or null	A regular expression for the lines that start a chapter; left out, chapter, part, prologue, and epilogue.
`chapterGroups` optional	boolean	Put each chapter's scenes in a group.

Output

Field	Type	Meaning
`name`	string
`scenes`	integer

`project.info`

read content:read

A project's details: author, language, tags, word count goal, cached totals, and sync linkage.

Kotlin: Hammer.project.info(project)
Rust: ops::project::info(project)

Input

Field	Type	Meaning
`project`	string	The project's name, or its server project id.

Output

Field	Type	Meaning
`name`	string
`projectId`	string
`created`	string or null
`lastAccessed`	string or null
`authorName`	string or null
`language`	string or null
`tags`	list of strings
`wordCountGoal`	object or null
`wordCountGoal.cadence`	one of "day", "week"
`wordCountGoal.count`	integer
`wordCount`	integer or null
`sceneCount`	integer or null
`lastEdited`	string or null

`project.list`

read content:read

List every project with its word count and when it was last edited.

Kotlin: Hammer.project.list()
Rust: ops::project::list()

Input

Takes no input: pass {}.

Output

Field	Type	Meaning
`projects`	list of objects
`projects[].name`	string
`projects[].projectId`	string
`projects[].wordCount`	integer or null	From the statistics cache; null until statistics are first calculated.
`projects[].created`	string or null	Null when the project's metadata can't be read.
`projects[].lastAccessed`	string or null
`projects[].lastEdited`	string or null

`project.rename`

write content:write

Rename a project. It must not be open in Hammer.

Kotlin: Hammer.project.rename(project, name)
Rust: ops::project::rename(project, name)

Input

Field	Type	Meaning
`project`	string
`name`	string

Output

Field	Type	Meaning
`name`	string

scene

`scene.append`

prose content:prose

Add markdown to the end of a scene's text, as a new paragraph.

Kotlin: Hammer.scene.append(project, id, markdown)
Rust: ops::scene::append(project, id, markdown)

Input

Field	Type	Meaning
`project`	string
`id`	integer
`markdown`	string

Output

Field	Type	Meaning
`wordCount`	integer

`scene.archive`

write content:write

Archive a scene: take it out of the story, keeping its text, drafts, and notes.

Kotlin: Hammer.scene.archive(project, id)
Rust: ops::scene::archive(project, id)

Input

Field	Type	Meaning
`project`	string
`id`	integer

Output

Field	Type	Meaning
`id`	integer
`name`	string
`kind`	one of "scene", "group"

`scene.archived`

read content:read

A project's archived scenes.

Kotlin: Hammer.scene.archived(project)
Rust: ops::scene::archived(project)

Input

Field	Type	Meaning
`project`	string	The project's name, or its server project id.

Output

Field	Type	Meaning
`scenes`	list of objects
`scenes[].id`	integer
`scenes[].name`	string

`scene.create`

write content:write

Create an empty scene or group, at the end of its parent unless an index is given.

Kotlin: Hammer.scene.create(project, name, …)
Rust: ops::scene::create(project, name, SceneCreateOptions { … })

Input

Field	Type	Meaning
`project`	string
`name`	string
`kind` optional	one of "scene", "group"
`parentId` optional	integer or null	The group to create it in; left out, the top level.
`index` optional	integer or null	Its position among its siblings; left out, the end.

Output

Field	Type	Meaning
`id`	integer
`name`	string
`kind`	one of "scene", "group"

`scene.delete`

destructive content:by name

Delete a scene, archived or not, or an empty group, for good.

Kotlin: Hammer.scene.delete(project, id)
Rust: ops::scene::delete(project, id)

Input

Field	Type	Meaning
`project`	string
`id`	integer

Output

Field	Type	Meaning
`id`	integer
`name`	string
`kind`	one of "scene", "group"

`scene.meta.read`

read content:read

A scene's outline, notes, tags, and references: the entries confirmed as in it, and those dismissed.

Kotlin: Hammer.scene.meta.read(project, id)
Rust: ops::scene::meta::read(project, id)

Input

Field	Type	Meaning
`project`	string
`id`	integer

Output

Field	Type	Meaning
`outline`	string
`notes`	string
`tags`	list of strings
`currentDraft`	string
`created`	string or null
`lastEdited`	string or null
`references`	list of integers	Entry ids confirmed as in the scene.
`dismissedReferences`	list of integers	Entry ids the writer dismissed, which name matching no longer adds.

`scene.meta.write`

write content:write

Change a scene's outline, notes, or tags. Fields left out keep their value.

Kotlin: Hammer.scene.meta.write(project, id, …)
Rust: ops::scene::meta::write(project, id, SceneMetaWriteOptions { … })

Input

Field	Type	Meaning
`project`	string
`id`	integer
`outline` optional	string or null
`notes` optional	string or null
`tags` optional	list of strings or null

Output

Field	Type	Meaning
`outline`	string
`notes`	string
`tags`	list of strings
`currentDraft`	string
`created`	string or null
`lastEdited`	string or null
`references`	list of integers	Entry ids confirmed as in the scene.
`dismissedReferences`	list of integers	Entry ids the writer dismissed, which name matching no longer adds.

`scene.move`

write content:write

Move a scene or group to a position within a group, or the top level when parentId is left out. index is its position there after the move.

Kotlin: Hammer.scene.move(project, id, index, …)
Rust: ops::scene::r#move(project, id, index, SceneMoveOptions { … })

Input

Field	Type	Meaning
`project`	string
`id`	integer
`parentId` optional	integer or null	The group to move into; left out, the top level.
`index`	integer

Output

Field	Type	Meaning
`id`	integer
`name`	string
`kind`	one of "scene", "group"

`scene.read`

read content:read

A scene's markdown, including unsaved edits, with its outline, notes, and tags.

Kotlin: Hammer.scene.read(project, id)
Rust: ops::scene::read(project, id)

Input

Field	Type	Meaning
`project`	string
`id`	integer

Output

Field	Type	Meaning
`id`	integer
`name`	string
`archived`	boolean
`markdown`	string
`wordCount`	integer
`meta`	object
`meta.outline`	string
`meta.notes`	string
`meta.tags`	list of strings
`meta.currentDraft`	string
`meta.created`	string or null
`meta.lastEdited`	string or null
`meta.references`	list of integers	Entry ids confirmed as in the scene.
`meta.dismissedReferences`	list of integers	Entry ids the writer dismissed, which name matching no longer adds.

`scene.read.many`

read content:read

Scenes in story order with their markdown, metadata, and the groups they sit in, a page of about maxWords, counting outlines and notes, at a time: every scene, a group's, or those in ids. Archived scenes are left out. Pass next as after for the following page; it is null on the last.

Kotlin: Hammer.scene.read.many(project, …)
Rust: ops::scene::read::many(project, SceneReadManyOptions { … })

Input

Field	Type	Meaning
`project`	string
`group` optional	integer or null	A group whose scenes, at any depth, to read.
`ids` optional	list of integers or null
`after` optional	integer or null	The previous page's next.
`maxWords` optional	integer

Output

Field	Type	Meaning
`scenes`	list of objects
`scenes[].id`	integer
`scenes[].name`	string
`scenes[].path`	list of strings	Names of the groups containing the scene, outermost first.
`scenes[].markdown`	string
`scenes[].wordCount`	integer
`scenes[].meta`	object
`scenes[].meta.outline`	string
`scenes[].meta.notes`	string
`scenes[].meta.tags`	list of strings
`scenes[].meta.currentDraft`	string
`scenes[].meta.created`	string or null
`scenes[].meta.lastEdited`	string or null
`scenes[].meta.references`	list of integers	Entry ids confirmed as in the scene.
`scenes[].meta.dismissedReferences`	list of integers	Entry ids the writer dismissed, which name matching no longer adds.
`next`	integer or null	The last scene's id when more follow, to pass as after; null on the last page.

`scene.references.set`

write content:write

Change which entries a scene references. confirm marks entries as in the scene, and un-dismisses them; dismiss marks entries as only mentioned, so name matching stops adding them; clear forgets entries either way, so a later match can add them again.

Kotlin: Hammer.scene.references.set(project, id, …)
Rust: ops::scene::references::set(project, id, SceneReferencesSetOptions { … })

Input

Field	Type	Meaning
`project`	string
`id`	integer
`confirm` optional	list of integers
`dismiss` optional	list of integers
`clear` optional	list of integers

Output

Field	Type	Meaning
`outline`	string
`notes`	string
`tags`	list of strings
`currentDraft`	string
`created`	string or null
`lastEdited`	string or null
`references`	list of integers	Entry ids confirmed as in the scene.
`dismissedReferences`	list of integers	Entry ids the writer dismissed, which name matching no longer adds.

`scene.rename`

write content:write

Rename a scene or group.

Kotlin: Hammer.scene.rename(project, id, name)
Rust: ops::scene::rename(project, id, name)

Input

Field	Type	Meaning
`project`	string
`id`	integer
`name`	string

Output

Field	Type	Meaning
`id`	integer
`name`	string
`kind`	one of "scene", "group"

`scene.tree`

read content:read

A project's scenes and groups in story order, with word counts.

Kotlin: Hammer.scene.tree(project)
Rust: ops::scene::tree(project)

Input

Field	Type	Meaning
`project`	string	The project's name, or its server project id.

Output

Field	Type	Meaning
`nodes`	list of SceneNodes

SceneNode

Field	Type	Meaning
`id`	integer
`name`	string
`kind`	one of "scene", "group"
`wordCount`	integer
`children`	list of SceneNodes

`scene.unarchive`

write content:write

Return an archived scene to the story, at the end of the top level.

Kotlin: Hammer.scene.unarchive(project, id)
Rust: ops::scene::unarchive(project, id)

Input

Field	Type	Meaning
`project`	string
`id`	integer

Output

Field	Type	Meaning
`id`	integer
`name`	string
`kind`	one of "scene", "group"

`scene.write`

prose content:prose

Replace a scene's text with markdown. Mode draft saves it as a new draft of the scene and leaves the scene alone. Mode live replaces the scene's text, saving the old text as a draft first.

Kotlin: Hammer.scene.write(project, id, mode, markdown, …)
Rust: ops::scene::write(project, id, mode, markdown, SceneWriteOptions { … })

Input

Field	Type	Meaning
`project`	string
`id`	integer
`mode`	one of "draft", "live"
`markdown`	string
`draftName` optional	string or null	The new draft's name, in draft mode only.

Output

Field	Type	Meaning
`draftId`	integer or null	The new draft, in draft mode.
`previousDraftId`	integer or null	In live mode, the draft holding the text it replaced; null when the text was unchanged.
`wordCount`	integer

search

`search`

read content:read

Search a project's scenes, notes, encyclopedia, and timeline. #tag in the query filters by tag.

Kotlin: Hammer.search(project, query, …)
Rust: ops::search(project, query, SearchOptions { … })

Input

Field	Type	Meaning
`project`	string
`query`	string
`filter` optional	one of "all", "scenes", "notes", "encyclopedia", "timeline"

Output

Field	Type	Meaning
`results`	list of objects
`results[].kind`	one of "scene", "note", "entry", "timeline"
`results[].id`	integer
`results[].title`	string
`results[].snippet`	string
`results[].matchStart`	integer	The match's range within [snippet].
`results[].matchEnd`	integer

stats

`stats.activity`

read content:read

Words written per day over a date range, plus lifetime words per device.

Kotlin: Hammer.stats.activity(project, …)
Rust: ops::stats::activity(project, StatsActivityOptions { … })

Input

Field	Type	Meaning
`project`	string
`from` optional	string or null	First day included, in the device's time zone; omitted for no lower bound.
`to` optional	string or null	Last day included; omitted for no upper bound.

Output

Field	Type	Meaning
`days`	list of objects
`days[].date`	string
`days[].words`	integer
`devices`	list of objects	Lifetime totals, not limited to the range.
`devices[].device`	string
`devices[].words`	integer

`stats.project`

read content:read

A project's statistics, as its Home screen shows them.

Kotlin: Hammer.stats.project(project, …)
Rust: ops::stats::project(project, StatsProjectOptions { … })

Input

Field	Type	Meaning
`project`	string
`recalculate` optional	boolean	Recalculate even when the cached statistics are current.

Output

Field	Type	Meaning
`totalWords`	integer
`sceneCount`	integer
`chapters`	list of objects	Top-level scenes and groups, in story order.
`chapters[].id`	integer
`chapters[].name`	string
`chapters[].words`	integer
`longestScene`	object or null
`longestScene.id`	integer
`longestScene.name`	string
`longestScene.words`	integer
`shortestSceneWords`	integer
`medianSceneWords`	integer
`noteCount`	integer
`timelineEventCount`	integer
`entryCounts`	list of objects
`entryCounts[].type`	one of "person", "place", "thing", "event", "idea"
`entryCounts[].count`	integer
`topAppearances`	list of objects	People appearing in the most scenes.
`topAppearances[].entryId`	integer
`topAppearances[].name`	string
`topAppearances[].type`	one of "person", "place", "thing", "event", "idea"
`topAppearances[].sceneCount`	integer
`wordCountGoal`	object or null
`wordCountGoal.cadence`	one of "day", "week"
`wordCountGoal.count`	integer
`lastEdited`	string or null
`lastEditedScene`	object or null
`lastEditedScene.id`	integer
`lastEditedScene.name`	string

`stats.sessions`

read content:read

Writing sessions over a date range, from every device.

Kotlin: Hammer.stats.sessions(project, …)
Rust: ops::stats::sessions(project, StatsSessionsOptions { … })

Input

Field	Type	Meaning
`project`	string
`from` optional	string or null	First day included, in the device's time zone; omitted for no lower bound.
`to` optional	string or null	Last day included; omitted for no upper bound.

Output

Field	Type	Meaning
`sessions`	list of objects
`sessions[].device`	string
`sessions[].startedAt`	string
`sessions[].endedAt`	string
`sessions[].words`	integer

sync

`sync.status`

read account:read

Each project's link to the sync server, its last sync, and how many of its changes are waiting to sync.

Kotlin: Hammer.sync.status()
Rust: ops::sync::status()

Input

Takes no input: pass {}.

Output

Field	Type	Meaning
`projects`	list of objects
`projects[].name`	string
`projects[].linked`	boolean	True once the project has synced.
`projects[].lastSync`	string or null	Null when never synced.
`projects[].pendingChanges`	integer

tag

`tag.find`

read content:read

Every scene, note, entry, and timeline event carrying a tag.

Kotlin: Hammer.tag.find(project, tag)
Rust: ops::tag::find(project, tag)

Input

Field	Type	Meaning
`project`	string
`tag`	string

Output

Field	Type	Meaning
`entities`	list of objects
`entities[].kind`	one of "scene", "note", "entry", "timeline"
`entities[].id`	integer

`tag.list`

read content:read

The tags used in a project, most used first, optionally counting one kind of entity.

Kotlin: Hammer.tag.list(project, …)
Rust: ops::tag::list(project, TagListOptions { … })

Input

Field	Type	Meaning
`project`	string
`kind` optional	one of "scene", "note", "entry", "timeline" or null
`limit` optional	integer or null

Output

Field	Type	Meaning
`tags`	list of objects
`tags[].tag`	string
`tags[].count`	integer

timeline

`timeline.create`

write content:write

Add a plain event to a project's timeline, main unless timeline names another, at the end unless an index is given. A dated timeline needs a start and takes no index. Entries and scenes are added with timeline.place.

Kotlin: Hammer.timeline.create(project, content, …)
Rust: ops::timeline::create(project, content, TimelineCreateOptions { … })

Input

Field	Type	Meaning
`project`	string
`content`	string
`date` optional	string or null	Deprecated alias of label; label wins when both are given.
`tags` optional	list of strings
`index` optional	integer or null	Its position in the timeline; left out, the end. A dated timeline takes none.
`title` optional	string or null	Its own title; left out, the content's first line is shown.
`label` optional	string or null	Free-text "when" a manual timeline shows, such as "Day 3" or "Spring, 1802".
`lane` optional	string or null	The lane it runs in.
`milestone` optional	boolean	A turning point, marked across every lane.
`start` optional	map of string to integer or null	When it starts on the timeline's calendar, such as {"year": 97, "day": 210}; required on a dated timeline.
`end` optional	map of string to integer or null	When it ends, in the same form as start; needs a start.
`references` optional	list of integers	Scene and entry ids it refers to.
`timeline` optional	string or null	The timeline's id, from timeline.settings.read; left out, or "main", the main timeline.

Output

Field	Type	Meaning
`id`	integer
`order`	integer	Manual position. A dated timeline orders by start date and uses this only to break ties.
`date`	string or null	Deprecated alias of label, always equal to it.
`content`	string	A plain event's markdown; always empty for a placement.
`tags`	list of strings	A plain event's tags; always empty for a placement.
`kind` optional	one of "event", "entry", "scene"	A plain event, or the placement of an encyclopedia entry or a scene.
`subject` optional	integer or null	The placed entry or scene id; null for a plain event.
`title` optional	string or null	A plain event's own title.
`label` optional	string or null	Free-text "when" a manual timeline shows, such as "Day 3" or "Spring, 1802".
`displayTitle` optional	string	The name to show: the subject's name, else the title, the content's first line, or the cached title.
`lane` optional	string or null	The lane it runs in; null for none.
`milestone` optional	boolean	A turning point, marked across every lane.
`start` optional	map of string to integer or null	When it starts on the timeline's calendar, as filled units such as {"year": 97, "day": 210}.
`end` optional	map of string to integer or null	When it ends, in the same form as start; null for a moment.
`references` optional	list of integers	Scene and entry ids a plain event refers to.
`cachedTitle` optional	string or null	A placement's subject name when last seen, kept in case the subject is deleted.
`timeline` optional	string	The id of the timeline it is on, "main" for the main one; a straggler keeps its deleted timeline's.

`timeline.def.create`

write content:write

Add a timeline to a project, manual unless mode says otherwise; a dated one needs a calendar. Its name is trimmed and no other timeline may have it, ignoring case. Returns it with its id, which the timeline option of other operations takes.

Kotlin: Hammer.timeline.def.create(project, name, …)
Rust: ops::timeline::def::create(project, name, TimelineDefCreateOptions { … })

Input

Field	Type	Meaning
`project`	string
`name`	string
`mode` optional	one of "manual", "dated" or null	Left out, manual.
`calendar` optional	object or null	Required for a dated timeline.
`calendar.preset`	one of "story", "gregorian"
`calendar.epochName` optional	string or null	What year 0 of a story calendar is called, such as "The Fall".
`calendar.coarsestUnit` optional	string or null	Story calendar only: the coarsest unit dates use, so a one-day story can run in hours.
`laneOrder` optional	list of strings	Lanes in the order they are drawn.

Output

Field	Type	Meaning
`id`	string	Stable id; the main timeline is "main".
`name`	string
`mode`	one of "manual", "dated"
`calendar`	object or null	The calendar dates are on; null until one is chosen.
`calendar.preset`	one of "story", "gregorian"
`calendar.epochName` optional	string or null	What year 0 of a story calendar is called, such as "The Fall".
`calendar.coarsestUnit` optional	string or null	Story calendar only: the coarsest unit dates use, so a one-day story can run in hours.
`laneOrder`	list of strings	Lanes in the order they are drawn; lanes in use but not listed follow alphabetically.

`timeline.def.delete`

destructive content:by name

Delete a timeline and every event on it for good; entries and scenes placed there are left alone. The main timeline cannot be deleted.

Kotlin: Hammer.timeline.def.delete(project, timeline)
Rust: ops::timeline::def::delete(project, timeline)

Input

Field	Type	Meaning
`project`	string
`timeline`	string	The timeline's id; main cannot be deleted.

Output

Field	Type	Meaning
`timeline`	string	The deleted timeline's id.
`deletedEvents`	integer	How many events were on it, deleted with it.

`timeline.delete`

destructive content:by name

Delete a timeline event for good. Deleting a placement leaves its entry or scene alone.

Kotlin: Hammer.timeline.delete(project, id)
Rust: ops::timeline::delete(project, id)

Input

Field	Type	Meaning
`project`	string
`id`	integer

Output

Field	Type	Meaning
`id`	integer
`order`	integer	Manual position. A dated timeline orders by start date and uses this only to break ties.
`date`	string or null	Deprecated alias of label, always equal to it.
`content`	string	A plain event's markdown; always empty for a placement.
`tags`	list of strings	A plain event's tags; always empty for a placement.
`kind` optional	one of "event", "entry", "scene"	A plain event, or the placement of an encyclopedia entry or a scene.
`subject` optional	integer or null	The placed entry or scene id; null for a plain event.
`title` optional	string or null	A plain event's own title.
`label` optional	string or null	Free-text "when" a manual timeline shows, such as "Day 3" or "Spring, 1802".
`displayTitle` optional	string	The name to show: the subject's name, else the title, the content's first line, or the cached title.
`lane` optional	string or null	The lane it runs in; null for none.
`milestone` optional	boolean	A turning point, marked across every lane.
`start` optional	map of string to integer or null	When it starts on the timeline's calendar, as filled units such as {"year": 97, "day": 210}.
`end` optional	map of string to integer or null	When it ends, in the same form as start; null for a moment.
`references` optional	list of integers	Scene and entry ids a plain event refers to.
`cachedTitle` optional	string or null	A placement's subject name when last seen, kept in case the subject is deleted.
`timeline` optional	string	The id of the timeline it is on, "main" for the main one; a straggler keeps its deleted timeline's.

`timeline.list`

read content:read

A timeline's events in display order: their manual order, or by start date on a dated timeline. The main timeline unless timeline names another; orphaned lists, by order, the events left on timelines deleted since, such as one made offline before a sync.

Kotlin: Hammer.timeline.list(project, …)
Rust: ops::timeline::list(project, TimelineListOptions { … })

Input

Field	Type	Meaning
`project`	string
`timeline` optional	string or null	The timeline's id; left out, or "main", the main timeline.
`orphaned` optional	boolean	Instead, the events whose timeline was deleted.

Output

Field	Type	Meaning
`events`	list of objects
`events[].id`	integer
`events[].order`	integer	Manual position. A dated timeline orders by start date and uses this only to break ties.
`events[].date`	string or null	Deprecated alias of label, always equal to it.
`events[].content`	string	A plain event's markdown; always empty for a placement.
`events[].tags`	list of strings	A plain event's tags; always empty for a placement.
`events[].kind` optional	one of "event", "entry", "scene"	A plain event, or the placement of an encyclopedia entry or a scene.
`events[].subject` optional	integer or null	The placed entry or scene id; null for a plain event.
`events[].title` optional	string or null	A plain event's own title.
`events[].label` optional	string or null	Free-text "when" a manual timeline shows, such as "Day 3" or "Spring, 1802".
`events[].displayTitle` optional	string	The name to show: the subject's name, else the title, the content's first line, or the cached title.
`events[].lane` optional	string or null	The lane it runs in; null for none.
`events[].milestone` optional	boolean	A turning point, marked across every lane.
`events[].start` optional	map of string to integer or null	When it starts on the timeline's calendar, as filled units such as {"year": 97, "day": 210}.
`events[].end` optional	map of string to integer or null	When it ends, in the same form as start; null for a moment.
`events[].references` optional	list of integers	Scene and entry ids a plain event refers to.
`events[].cachedTitle` optional	string or null	A placement's subject name when last seen, kept in case the subject is deleted.
`events[].timeline` optional	string	The id of the timeline it is on, "main" for the main one; a straggler keeps its deleted timeline's.

`timeline.move`

write content:write

Move a timeline event to a position on its own timeline; index is its position after the move. A dated timeline is ordered by its dates, so nothing can be moved on it. timeline.set moves an event to another timeline.

Kotlin: Hammer.timeline.move(project, id, index)
Rust: ops::timeline::r#move(project, id, index)

Input

Field	Type	Meaning
`project`	string
`id`	integer
`index`	integer

Output

Field	Type	Meaning
`id`	integer
`order`	integer	Manual position. A dated timeline orders by start date and uses this only to break ties.
`date`	string or null	Deprecated alias of label, always equal to it.
`content`	string	A plain event's markdown; always empty for a placement.
`tags`	list of strings	A plain event's tags; always empty for a placement.
`kind` optional	one of "event", "entry", "scene"	A plain event, or the placement of an encyclopedia entry or a scene.
`subject` optional	integer or null	The placed entry or scene id; null for a plain event.
`title` optional	string or null	A plain event's own title.
`label` optional	string or null	Free-text "when" a manual timeline shows, such as "Day 3" or "Spring, 1802".
`displayTitle` optional	string	The name to show: the subject's name, else the title, the content's first line, or the cached title.
`lane` optional	string or null	The lane it runs in; null for none.
`milestone` optional	boolean	A turning point, marked across every lane.
`start` optional	map of string to integer or null	When it starts on the timeline's calendar, as filled units such as {"year": 97, "day": 210}.
`end` optional	map of string to integer or null	When it ends, in the same form as start; null for a moment.
`references` optional	list of integers	Scene and entry ids a plain event refers to.
`cachedTitle` optional	string or null	A placement's subject name when last seen, kept in case the subject is deleted.
`timeline` optional	string	The id of the timeline it is on, "main" for the main one; a straggler keeps its deleted timeline's.

`timeline.place`

write content:write

Place an encyclopedia entry of type event, or a scene, on a project's timeline, main unless timeline names another. Each can be placed once on each timeline, and its name and words come from it. A dated timeline needs a start.

Kotlin: Hammer.timeline.place(project, kind, subject, …)
Rust: ops::timeline::place(project, kind, subject, TimelinePlaceOptions { … })

Input

Field	Type	Meaning
`project`	string
`kind`	one of "event", "entry", "scene"	entry or scene.
`subject`	integer	The entry or scene id.
`start` optional	map of string to integer or null	When it starts on the timeline's calendar, such as {"year": 97, "day": 210}; required on a dated timeline.
`end` optional	map of string to integer or null	When it ends, in the same form as start; needs a start.
`lane` optional	string or null	The lane it runs in.
`milestone` optional	boolean	A turning point, marked across every lane.
`timeline` optional	string or null	The timeline's id, from timeline.settings.read; left out, or "main", the main timeline.

Output

Field	Type	Meaning
`id`	integer
`order`	integer	Manual position. A dated timeline orders by start date and uses this only to break ties.
`date`	string or null	Deprecated alias of label, always equal to it.
`content`	string	A plain event's markdown; always empty for a placement.
`tags`	list of strings	A plain event's tags; always empty for a placement.
`kind` optional	one of "event", "entry", "scene"	A plain event, or the placement of an encyclopedia entry or a scene.
`subject` optional	integer or null	The placed entry or scene id; null for a plain event.
`title` optional	string or null	A plain event's own title.
`label` optional	string or null	Free-text "when" a manual timeline shows, such as "Day 3" or "Spring, 1802".
`displayTitle` optional	string	The name to show: the subject's name, else the title, the content's first line, or the cached title.
`lane` optional	string or null	The lane it runs in; null for none.
`milestone` optional	boolean	A turning point, marked across every lane.
`start` optional	map of string to integer or null	When it starts on the timeline's calendar, as filled units such as {"year": 97, "day": 210}.
`end` optional	map of string to integer or null	When it ends, in the same form as start; null for a moment.
`references` optional	list of integers	Scene and entry ids a plain event refers to.
`cachedTitle` optional	string or null	A placement's subject name when last seen, kept in case the subject is deleted.
`timeline` optional	string	The id of the timeline it is on, "main" for the main one; a straggler keeps its deleted timeline's.

`timeline.read`

read content:read

One timeline event.

Kotlin: Hammer.timeline.read(project, id)
Rust: ops::timeline::read(project, id)

Input

Field	Type	Meaning
`project`	string
`id`	integer

Output

Field	Type	Meaning
`id`	integer
`order`	integer	Manual position. A dated timeline orders by start date and uses this only to break ties.
`date`	string or null	Deprecated alias of label, always equal to it.
`content`	string	A plain event's markdown; always empty for a placement.
`tags`	list of strings	A plain event's tags; always empty for a placement.
`kind` optional	one of "event", "entry", "scene"	A plain event, or the placement of an encyclopedia entry or a scene.
`subject` optional	integer or null	The placed entry or scene id; null for a plain event.
`title` optional	string or null	A plain event's own title.
`label` optional	string or null	Free-text "when" a manual timeline shows, such as "Day 3" or "Spring, 1802".
`displayTitle` optional	string	The name to show: the subject's name, else the title, the content's first line, or the cached title.
`lane` optional	string or null	The lane it runs in; null for none.
`milestone` optional	boolean	A turning point, marked across every lane.
`start` optional	map of string to integer or null	When it starts on the timeline's calendar, as filled units such as {"year": 97, "day": 210}.
`end` optional	map of string to integer or null	When it ends, in the same form as start; null for a moment.
`references` optional	list of integers	Scene and entry ids a plain event refers to.
`cachedTitle` optional	string or null	A placement's subject name when last seen, kept in case the subject is deleted.
`timeline` optional	string	The id of the timeline it is on, "main" for the main one; a straggler keeps its deleted timeline's.

`timeline.set`

write content:write

Set single fields of any timeline event, or clear them by name, leaving the rest alone. A placement takes only label, lane, milestone, start, and end. This is how a placement is edited. A timeline other than the event's own moves it there, with start and end, when given, as its dates on that timeline's calendar; a dated timeline refuses the move unless the event's start fits or one is given.

Kotlin: Hammer.timeline.set(project, id, …)
Rust: ops::timeline::set(project, id, TimelineSetOptions { … })

Input

Field	Type	Meaning
`project`	string
`id`	integer	The timeline event.
`title` optional	string or null	A plain event's own title.
`label` optional	string or null	The free-text "when", shown on a manual timeline.
`lane` optional	string or null	The lane it runs in.
`milestone` optional	boolean or null	A turning point, marked across every lane.
`start` optional	map of string to integer or null	When it starts on the timeline's calendar, such as {"year": 97, "day": 210}.
`end` optional	map of string to integer or null	When it ends, in the same form as start.
`clear` optional	list of strings	Fields to clear, from title, label, lane, start, and end.
`timeline` optional	string or null	Moves the event to this timeline, by id, "main" for the main one.

Output

Field	Type	Meaning
`id`	integer
`order`	integer	Manual position. A dated timeline orders by start date and uses this only to break ties.
`date`	string or null	Deprecated alias of label, always equal to it.
`content`	string	A plain event's markdown; always empty for a placement.
`tags`	list of strings	A plain event's tags; always empty for a placement.
`kind` optional	one of "event", "entry", "scene"	A plain event, or the placement of an encyclopedia entry or a scene.
`subject` optional	integer or null	The placed entry or scene id; null for a plain event.
`title` optional	string or null	A plain event's own title.
`label` optional	string or null	Free-text "when" a manual timeline shows, such as "Day 3" or "Spring, 1802".
`displayTitle` optional	string	The name to show: the subject's name, else the title, the content's first line, or the cached title.
`lane` optional	string or null	The lane it runs in; null for none.
`milestone` optional	boolean	A turning point, marked across every lane.
`start` optional	map of string to integer or null	When it starts on the timeline's calendar, as filled units such as {"year": 97, "day": 210}.
`end` optional	map of string to integer or null	When it ends, in the same form as start; null for a moment.
`references` optional	list of integers	Scene and entry ids a plain event refers to.
`cachedTitle` optional	string or null	A placement's subject name when last seen, kept in case the subject is deleted.
`timeline` optional	string	The id of the timeline it is on, "main" for the main one; a straggler keeps its deleted timeline's.

`timeline.settings.read`

read content:read

A project's timelines, main first, each with its id, name, mode, calendar, and lane order, and how many events are left on timelines deleted since (see timeline.list orphaned).

Kotlin: Hammer.timeline.settings.read(project)
Rust: ops::timeline::settings::read(project)

Input

Field	Type	Meaning
`project`	string	The project's name, or its server project id.

Output

Field	Type	Meaning
`timelines`	list of objects	The project's timelines: main first, then the others in the order they were made.
`timelines[].id`	string	Stable id; the main timeline is "main".
`timelines[].name`	string
`timelines[].mode`	one of "manual", "dated"
`timelines[].calendar`	object or null	The calendar dates are on; null until one is chosen.
`timelines[].calendar.preset`	one of "story", "gregorian"
`timelines[].calendar.epochName` optional	string or null	What year 0 of a story calendar is called, such as "The Fall".
`timelines[].calendar.coarsestUnit` optional	string or null	Story calendar only: the coarsest unit dates use, so a one-day story can run in hours.
`timelines[].laneOrder`	list of strings	Lanes in the order they are drawn; lanes in use but not listed follow alphabetically.
`orphaned` optional	integer	Events whose timeline was deleted, such as one made offline before a sync; timeline.list orphaned lists them.

`timeline.settings.write`

write content:write

Change one timeline's settings, main unless timeline names another; fields left out stay as they are, and name renames it. Switching to dated gives every event without a valid start one, spaced evenly in the current order; switching to manual keeps the date order as the manual order. A new calendar drops dates that do not fit it, keeping the start as the label of an event that has none.

Kotlin: Hammer.timeline.settings.write(project, …)
Rust: ops::timeline::settings::write(project, TimelineSettingsWriteOptions { … })

Input

Field	Type	Meaning
`project`	string
`name` optional	string or null	A new name, which renames the timeline.
`mode` optional	one of "manual", "dated" or null	Switching to dated needs a calendar, here or already set.
`calendar` optional	object or null
`calendar.preset`	one of "story", "gregorian"
`calendar.epochName` optional	string or null	What year 0 of a story calendar is called, such as "The Fall".
`calendar.coarsestUnit` optional	string or null	Story calendar only: the coarsest unit dates use, so a one-day story can run in hours.
`laneOrder` optional	list of strings or null	Lanes in the order they are drawn.
`spacing` optional	object or null	Only when switching to dated; left out, events are one of the calendar's coarsest unit apart.
`spacing.unit`	string	The calendar unit to step by, such as "day".
`spacing.step` optional	integer
`spacing.origin`	map of string to integer	The first event's date, such as {"year": 97}.
`timeline` optional	string or null	The timeline's id; left out, or "main", the main timeline.

Output

Field	Type	Meaning
`timelines`	list of objects	The project's timelines: main first, then the others in the order they were made.
`timelines[].id`	string	Stable id; the main timeline is "main".
`timelines[].name`	string
`timelines[].mode`	one of "manual", "dated"
`timelines[].calendar`	object or null	The calendar dates are on; null until one is chosen.
`timelines[].calendar.preset`	one of "story", "gregorian"
`timelines[].calendar.epochName` optional	string or null	What year 0 of a story calendar is called, such as "The Fall".
`timelines[].calendar.coarsestUnit` optional	string or null	Story calendar only: the coarsest unit dates use, so a one-day story can run in hours.
`timelines[].laneOrder`	list of strings	Lanes in the order they are drawn; lanes in use but not listed follow alphabetically.
`orphaned` optional	integer	Events whose timeline was deleted, such as one made offline before a sync; timeline.list orphaned lists them.

`timeline.update`

write content:write

Replace a plain event's text, and any other field given; an empty value clears it. The text is always required, so every call replaces it. Edit a placement with timeline.set.

Kotlin: Hammer.timeline.update(project, id, content, …)
Rust: ops::timeline::update(project, id, content, TimelineUpdateOptions { … })

Input

Field	Type	Meaning
`project`	string
`id`	integer
`content`	string	The plain event's markdown; must be empty for a placement, which is edited with timeline.set.
`date` optional	string or null	Deprecated alias of label; label wins when both are given.
`tags` optional	list of strings or null
`title` optional	string or null
`label` optional	string or null	Free-text "when" a manual timeline shows.
`lane` optional	string or null
`milestone` optional	boolean or null
`start` optional	map of string to integer or null	When it starts on the timeline's calendar, such as {"year": 97, "day": 210}.
`end` optional	map of string to integer or null	When it ends, in the same form as start.
`references` optional	list of integers or null	Scene and entry ids it refers to.

Output

Field	Type	Meaning
`id`	integer
`order`	integer	Manual position. A dated timeline orders by start date and uses this only to break ties.
`date`	string or null	Deprecated alias of label, always equal to it.
`content`	string	A plain event's markdown; always empty for a placement.
`tags`	list of strings	A plain event's tags; always empty for a placement.
`kind` optional	one of "event", "entry", "scene"	A plain event, or the placement of an encyclopedia entry or a scene.
`subject` optional	integer or null	The placed entry or scene id; null for a plain event.
`title` optional	string or null	A plain event's own title.
`label` optional	string or null	Free-text "when" a manual timeline shows, such as "Day 3" or "Spring, 1802".
`displayTitle` optional	string	The name to show: the subject's name, else the title, the content's first line, or the cached title.
`lane` optional	string or null	The lane it runs in; null for none.
`milestone` optional	boolean	A turning point, marked across every lane.
`start` optional	map of string to integer or null	When it starts on the timeline's calendar, as filled units such as {"year": 97, "day": 210}.
`end` optional	map of string to integer or null	When it ends, in the same form as start; null for a moment.
`references` optional	list of integers	Scene and entry ids a plain event refers to.
`cachedTitle` optional	string or null	A placement's subject name when last seen, kept in case the subject is deleted.
`timeline` optional	string	The id of the timeline it is on, "main" for the main one; a straggler keeps its deleted timeline's.

#account

#backup

#draft

#entry

#export

#idea

#image

#note

#ops

#plugin

#project

#scene

#search

#stats

#sync

#tag

#timeline

account

backup

draft

entry

export

idea

image

note

ops

plugin

project

scene

search

stats

sync

tag

timeline