Tools
The tools, prompts and resources the novem MCP server lists to a client that has every scope, grouped by area.
AI-assisted, human-approvednovem uses AI to review and keep our documentation up to date.
This page is generated from the server's own tool definitions, so it matches
what tools/list returns. The server offers 126 tools. A client
sees the subset its scopes open; the
MCP guide covers connecting a client.
Each tool carries two labels:
- Behaviour:
read-onlytools only read;writetools only add, such as creating a resource or appending to one;destructivetools overwrite, delete, share, send or run something. Clients use this to decide what to ask you about. - Scope: the area on the consent screen that opens the tool. A tool marked
any scopeis available once you grant any area, and one markedalways availableneeds none.
The description under each tool is the text the server gives the assistant.
General
general_add_resource_tagsAdd resource tags
Add one or more tags to a resource (plot, grid, mail, or doc) without replacing existing ones.
Description and parameters (3)
Add one or more tags to a resource (plot, grid, mail, or doc) without replacing existing ones.
Use the forms returned by general_list_resource_tags: bare system names
such as "fav", user tags such as "+sales", and categories such as "=finance".
A bare ordinary name such as "sales" adds "+sales". Use "+fav" to add a
user tag whose name matches a system tag. Names start with a letter and
contain only letters, numbers, hyphens, and underscores.
Returns:
CallToolResult with status| Parameter | Type | Description |
|---|---|---|
namerequired | string | Resource name |
tagsrequired | array of string | List of tags to add |
typerequired | string | Resource type ("plot", "grid", "mail", or "doc") |
general_api_GETRaw API GET
Make a raw GET request to a Novem API endpoint.
Description and parameters (1)
Make a raw GET request to a Novem API endpoint. The /v1 prefix is added automatically — do NOT include it in path. Read novem://api-schema for valid path patterns before calling this tool. The public reference for the API this tool calls is https://novem.io/docs/reference/api. Call general_check_access() first to see which path prefixes you are allowed to access. Omit path to list your visualisations at /v1/vis.
| Parameter | Type | Description |
|---|---|---|
path | stringdefault "" | API path WITHOUT /v1 prefix, must start with / Correct: path="/vis/plots/my_plot/data" Incorrect: path="/v1/vis/plots/my_plot/data" (do not include /v1) Incorrect: path="vis/plots" (must start with /) |
general_api_POSTRaw API POST
Update a Novem resource with new content via POST.
Description and parameters (2)
Update a Novem resource with new content via POST.
Read novem://api-schema for valid path patterns before calling this tool.
The public reference for the API this tool calls is https://novem.io/docs/reference/api.
Use this for updating resource data/configuration. For plot data updates,
the correct endpoint is /vis/plots/{name}/data (not /files/data.csv).
Common use cases:
- Update plot data: POST /vis/plots/{name}/data (CSV as text/plain)
- Update plot config: POST /vis/plots/{name}/config/title
- Update mail content: POST /mails/{name}/content
To comment in a discussion thread, use general_post_comment instead.
Tips:
- Read novem://api-schema before calling to discover valid paths
- For plot data, use Content-Type: text/plain with CSV
- Paths are case-sensitive
Examples:
# Update plot with CSV data
general_api_POST(
path="/vis/plots/sales_dashboard/data",
content="Date,Sales\n2024-01-01,100\n2024-01-02,150"
)
# Update plot title
general_api_POST(
path="/vis/plots/sales_dashboard/config/title",
content="Q4 Sales Performance"
)| Parameter | Type | Description |
|---|---|---|
pathrequired | string | API path starting with / (e.g., "/vis/plots/my_plot/data") The /v1 prefix is added automatically. |
contentrequired | string | Content to POST (string format) |
general_api_PUTRaw API PUT
Create a new Novem resource via PUT.
Description and parameters (1)
Create a new Novem resource via PUT. The /v1 prefix is added automatically — do NOT include it in path. Read novem://api-schema for valid path patterns before calling this tool. The public reference for the API this tool calls is https://novem.io/docs/reference/api. Call general_check_access() to see which path prefixes you are allowed to write to. To comment in a discussion thread, use general_post_comment instead. A path that changes sharing requires user confirmation before the PUT.
| Parameter | Type | Description |
|---|---|---|
pathrequired | string | API path WITHOUT /v1 prefix, must start with / Correct: path="/vis/plots/my_new_plot" Incorrect: path="/v1/vis/plots/my_new_plot" (do not include /v1) Incorrect: path="vis/plots/my_new_plot" (must start with /) |
general_check_accessCheck granted access
Show the tools and API access granted to the authenticated user.
Description and parameters (0)
Show the tools and API access granted to the authenticated user.
No parameters.
general_delete_resourceDelete resource
Permanently delete a resource (plot, grid, mail, job, or repo) and all of its data/configuration.
Description and parameters (2)
Permanently delete a resource (plot, grid, mail, job, or repo) and all of its data/configuration.
Returns:
CallToolResult with deletion status| Parameter | Type | Description |
|---|---|---|
namerequired | string | Resource name |
typerequired | string | Resource type ("plot", "grid", "mail", "job", or "repo") |
general_delete_resource_varDelete resource variable
Delete a single variable from a resource (destructive — elicits confirmation).
Description and parameters (3)
Delete a single variable from a resource (destructive — elicits confirmation).
Doc references like `{/u/<user>/<t>/<name>/v/<var_name>}` will render as
plain text after the var is gone. Removing one var doesn't affect others
on the same resource.| Parameter | Type | Description |
|---|---|---|
namerequired | string | Resource name. |
typerequired | string | 'plot', 'grid', 'mail', 'doc', 'job', or 'repo'. |
var_namerequired | string | Variable to delete. |
general_describe_resourceDescribe resource
One-shot synthesis of a resource — the *"tell me about this"* tool.
Description and parameters (3)
One-shot synthesis of a resource — the *"tell me about this"* tool.
Returns a compact summary suitable for starting a conversation about
any plot / doc / grid / mail you have access to (your own, public, or
shared-with-you). For deeper inspection of a specific piece (the JS,
the data, the full description, a thread) use `general_read_resource`
or `general_read_thread`.
Returns:
- `identity`: id, type, title, summary, author, tags, shared_with, updated
- `data_preview`: row/column counts, header, formats and a bounded sample
(up to 5 rows × 20 columns, 256 characters per text cell)
- `description_preview`: ~400-char plain-text preview of the description
- `urls`: web / image / pdf URLs
- `topics`: up to 5 most recent thread topics (creator + slug + size + timestamp)| Parameter | Type | Description |
|---|---|---|
namerequired | string | Resource id (the URL slug, e.g. 'ree_supply_gap' — NOT the shortname). |
typerequired | string | plot | doc | grid | mail. |
author | string | null | Owner. Defaults to current user. |
general_diff_historyDiff revisions
Show what changed in one leaf between two revisions, as a unified diff — the `git diff`.
Description and parameters (6)
Show what changed in one leaf between two revisions, as a unified diff — the `git diff`. The defaults compare the previous revision (1) with the current one (0): "what did the last write change". Read the diff before choosing between fixing forward and general_restore_history; it costs a fraction of reading both revisions in full.
| Parameter | Type | Description |
|---|---|---|
namerequired | string | The resource id. |
typerequired | string | One of 'plot', 'doc', 'grid', 'mail', 'job', 'repo'. |
partrequired | string | Which leaf — same vocabulary as general_list_history. |
revision | integer | stringdefault 1 | The older side. An index from general_list_history (0 = current, 1 = previous), a sha1 prefix, or an ISO 8601 timestamp (resolves to the newest revision at or before that instant). |
against | integer | stringdefault 0 | The newer side, same forms. Default 0, the current content. |
author | string | null | Owner username for a resource shared with you. Omit for your own. |
general_helpGet help topic
Get documentation for Novem API topics and operations.
Description and parameters (1)
Get documentation for Novem API topics and operations.
Usage:
general_help() - List all available topics
general_help(topic='custom-plots') - Get documentation for that topic
Only returns documentation for modules accessible with your OAuth scopes.| Parameter | Type | Description |
|---|---|---|
topic | stringdefault "" |
general_list_historyList revisions
List the retained revisions of one leaf of a resource — the `git log` of a plot's data, a doc's content or a job's schedule.
Description and parameters (4)
List the retained revisions of one leaf of a resource — the `git log` of a plot's data, a doc's content or a job's schedule. Call it before general_diff_history or general_restore_history, and whenever you need to know what a leaf looked like before an edit. Revisions come newest first: index 0 is the current content, 1 the one before it. Only the last 10 revisions per leaf are kept, and a tool that rewrites the whole leaf (docs_update_section, custom_plots_update_js_section) consumes one revision per call, so check early rather than late.
| Parameter | Type | Description |
|---|---|---|
namerequired | string | The resource id (the plot / doc / grid / mail / job / repo name). |
typerequired | string | One of 'plot', 'doc', 'grid', 'mail', 'job', 'repo'. |
partrequired | string | Which leaf. plot: data, js, css, deps. doc: content, css, theme. grid: layout, mapping, theme. mail: content, subject, theme. job: schedule, chains, type, filter. repo: type. Every type also takes name, description, summary, and any config leaf as 'config/<path>' (e.g. 'config/title'). Not covered: space file content, theme CSS, and repository code (that is git — use repos_list_commits and repos_diff). |
author | string | null | Owner username when the resource is shared with you rather than your own. Omit for your own resources. |
general_list_inboxList notifications
Notifications inbox — events you should know about, time-ordered.
Description and parameters (3)
Notifications inbox — events you should know about, time-ordered.
Distinct from `general_list_threads` (which is discussion-grouped per
resource). This is the event feed: new comments, mentions, job runs,
sharing actions, social, group invites — every notification the
platform has raised for your user.
Returns:
Time-ordered list of notifications, each with actor, target, payload,
and read/unread state.| Parameter | Type | Description |
|---|---|---|
unread_only | booleandefault false | True to filter to unread notifications only. |
limit | integerdefault 20 | Max items to return after filtering (1-100, default 20). |
event_class | string | null | Optional filter — 'comment', 'job', 'social', 'shared', 'invite', 'mention', 'reaction', etc. |
general_list_resource_tagsList resource tags
List all tags for a resource (plot, grid, mail, or doc).
Description and parameters (2)
List all tags for a resource (plot, grid, mail, or doc).
Returns:
CallToolResult with list of tags| Parameter | Type | Description |
|---|---|---|
namerequired | string | Resource name |
typerequired | string | Resource type ("plot", "grid", "mail", or "doc") |
general_list_resource_varsList resource variables
List all live variables defined on a resource (via GraphQL — single round trip).
Description and parameters (2)
List all live variables defined on a resource (via GraphQL — single round trip). Returns each var's id, value, about, format, type, threshold, and the rendered text the doc parser would substitute.
| Parameter | Type | Description |
|---|---|---|
namerequired | string | Resource name. |
typerequired | string | 'plot', 'grid', 'mail', 'doc', 'job', or 'repo'. |
general_list_sharesList resource shares
List every active share on a resource.
Description and parameters (2)
List every active share on a resource.
Returns the public flag and any group shares (org-group, user-group) along
with their permissions. Use this before adjusting shares so you can see
what's already in place.
Returns:
Structured list of shares with target and permissions.| Parameter | Type | Description |
|---|---|---|
namerequired | string | Resource name. |
typerequired | string | One of plot | grid | mail | doc | job | repo | space. |
general_list_threadsList discussion threads
List discussion threads — your inbox view across all resources you have access to.
Description and parameters (2)
List discussion threads — your inbox view across all resources you have access to.
Use this as the catch-up / triage tool: *"any new activity on my plots,
docs, mails, etc.?"*. One call, sorted by `last_activity` desc.
To read the actual contents of a specific thread, use general_read_thread.
Returns:
Aggregated discussion items, each summarising activity on one resource:
- `vde_type`, `vde_shortname`, `vde_name`, `vde_url` — which resource
- `author { username, name }` — resource owner
- `total_topics`, `total_comments`, `total_likes`, `last_activity`| Parameter | Type | Description |
|---|---|---|
mode | stringdefault "mine" | 'mine' (your resources + things shared with you, default) or 'top' (trending public discussions across the platform). |
limit | integerdefault 20 | Max items (1-50, default 20). |
general_post_commentPost comment
Post a comment in a discussion thread on a plot, doc, grid or mail.
Description and parameters (6)
Post a comment in a discussion thread on a plot, doc, grid or mail.
The comment is created with its text in one step. Find the thread first
with general_read_thread (call it without thread_path to list topics), and
read the thread before replying so the comment fits the conversation.
Mention a user with `@username`.
Returns:
`comment_path` (pass it as reply_to to answer this comment), `comment`
(the new comment's '@<you>~<slug>' name) and the topic `url`.| Parameter | Type | Description |
|---|---|---|
namerequired | string | Resource name (e.g. 'ree_supply_gap'). |
typerequired | string | One of plot | doc | grid | mail. |
thread_pathrequired | string | The topic to comment in, as general_read_thread returns it (e.g. '@afa~flgsa01n'). |
messagerequired | string | The comment text. Plain text or markdown, up to 10,000 characters. |
author | string | null | Owner of the resource. Defaults to the current user. |
reply_to | string | null | Optional. The comment to reply to, as a path under the topic: '@bob~k2j9x0aa' for a top-level comment, or '@bob~k2j9x0aa/comments/@cy~p0q1r2s3' for a reply to a reply. Leave empty to comment on the topic itself. |
general_read_resourceRead resource
Read specific parts of a resource — the drill-down tool.
Description and parameters (4)
Read specific parts of a resource — the drill-down tool.
Fetches the REST aggregate at `/v1/u/<author>/<short>/<name>` then
returns only the requested parts. Use this after `general_describe_resource`
when you want to see the actual contents.
Returns:
Object with requested parts as keys. Unrequested parts are omitted.| Parameter | Type | Description |
|---|---|---|
namerequired | string | Resource id (URL slug, e.g. 'ree_supply_gap'). |
typerequired | string | plot | doc | grid | mail. |
author | string | null | Owner. Defaults to current user. |
parts | array of string | null | List of parts to return. Valid values: - 'identity' — full identity (id, title, author, tags, sharing, etc.) - 'description' — full HTML description - 'data' — data + metadata (columns, types, formats) - 'js' — custom plot JS source (plots only) - 'css' — custom plot CSS (plots only) - 'deps' — custom plot dependencies (plots only) - 'config' — full config tree (theme, layout, render, custom) - 'urls' — web/image/pdf URLs - 'all' — everything from the aggregate (heavy; use sparingly) Default is ['identity'] (lightest). |
general_read_threadRead discussion thread
Read discussion thread(s) on a resource — cross-namespace, recursive.
Description and parameters (4)
Read discussion thread(s) on a resource — cross-namespace, recursive.
Two modes:
- `thread_path=None`: list topic summaries on the resource (no message bodies).
- `thread_path='@<creator>~<slug>'`: read the full thread, walking nested
replies into a flat tree. One return shape contains the topic message +
all comments at all depths.
Works on any resource you can see — your own, public, or shared-with-you.
Returns:
- List mode: `topics` array with creator/slug/name/size/last_modified.
- Read mode: nested `topic` with `msg` + recursive `comments` tree.
To reply in a thread, use general_post_comment.| Parameter | Type | Description |
|---|---|---|
namerequired | string | Resource name (e.g. 'ree_supply_gap'). |
typerequired | string | One of plot | doc | grid | mail. |
author | string | null | Owner of the resource. Defaults to the current user. |
thread_path | string | null | Optional. The thread path as it appears in the URL after `/c/` (e.g. '@afa~flgsa01n'). Leading `c/` or `threads/` is normalised away. Leave empty to just list topics. |
general_remove_resource_tagsRemove resource tags
Remove one or more tags from a resource (plot, grid, mail, or doc).
Description and parameters (3)
Remove one or more tags from a resource (plot, grid, mail, or doc).
Accepts the tags exactly as general_list_resource_tags returns them:
user tags as "+sales", category tags as "=finance", and system tags
bare, such as "fav" or "like". A bare name removes the system tag of
that name if the resource has one, and the user tag "+<name>"
otherwise, so "sales" removes "+sales".
Returns:
CallToolResult with status| Parameter | Type | Description |
|---|---|---|
namerequired | string | Resource name |
tagsrequired | array of string | List of tags to remove |
typerequired | string | Resource type ("plot", "grid", "mail", or "doc") |
general_restore_historyRestore revision
Put one leaf back to an earlier revision — `git restore --source=<rev> -- <file>`.
Description and parameters (5)
Put one leaf back to an earlier revision — `git restore --source=<rev> -- <file>`. The old bytes are written as a NEW revision: history stays append-only, the restore shows up in general_list_history, and it can be undone the same way. The write is conditional on the leaf still holding the content you listed (If-Match); if someone wrote in between you get a precondition error instead of overwriting their change — list again and retry. Restore one leaf at a time: a tool call that wrote js, css and data produced three separate leaf revisions. Use general_diff_history first when you are not sure which revision you want. Cannot undo: deleting a resource or a leaf (its history goes with it), space file writes, theme CSS, mail sends, job runs.
| Parameter | Type | Description |
|---|---|---|
namerequired | string | The resource id. |
typerequired | string | One of 'plot', 'doc', 'grid', 'mail', 'job', 'repo'. |
partrequired | string | Which leaf — same vocabulary as general_list_history. |
revisionrequired | integer | string | Which revision to bring back: an index from general_list_history (1 = the one before the current), a sha1 prefix, or an ISO 8601 timestamp. 0 is the current content and a no-op. |
author | string | null | Owner username for a resource shared with you. Omit for your own. |
general_searchSearch resources
List and search your Novem resources.
Description and parameters (17)
List and search your Novem resources.
Default sort order: most-recently-updated first (the API returns items
ordered by `updated` descending; explicit ordering isn't configurable).
Returns:
Structured response with:
- `items` (single resource) or `buckets` (resource='all'): matched resources
- `pagination`: limit / offset / total / mode info
- `dropped_fields` (optional): fields you asked for but the server
didn't recognise — present only when fields were dropped
- `notes` (optional): runtime adjustments (limit capping, auto-pagination
overriding limit, etc.) — present only when something was adjusted
- `error_messages` (optional): API error messages, wrapped for inspection
Examples:
# List your plots (minimal fields)
general_search(resource="plots")
# Get plots with social stats and tags
general_search(resource="plots", fields=["id", "name", "social { likes favs }", "tags { id name }"])
# Get job status info
general_search(resource="jobs", fields=["id", "name", "schedule", "last_run_status", "run_count"])
# Get mail recipients
general_search(resource="mails", fields=["id", "name", "summary", "recipients { to { type recipient { id name } } }"])
# List ALL users' plots
general_search(resource="plots", author="*")
# List plots updated in November 2025
general_search(resource="plots", start_date="2025-11-01", end_date="2025-11-30")
# List plots with specific tag
general_search(resource="plots", tag="project-alpha")
# Combine filters: your plots with tag, updated after date
general_search(
resource="plots",
tag="sales",
start_date="2025-11-01",
filter_text="revenue"
)
# Search with text filter
general_search(resource="plots", filter_text="sales")
# Introspect available arguments for a resource
general_search(resource="plots", introspect=True)
# Search for a user by username (server-side filter)
general_search(resource="users", query_args={"username": "steve"})
# Get custom plots created in December 2025
general_search(resource="plots", type_filter="custom", start_date="2025-12-01", end_date="2025-12-31", date_field="created")
# Fetch specific plot by ID
general_search(resource="plots", id="my-plot-id")
# Filter groups by type
general_search(resource="groups", query_args={"type": "org"})| Parameter | Type | Description |
|---|---|---|
resourcerequired | string | Resource type, or 'all' for cross-resource search. Singular or plural accepted — plot/plots, mail/mails, grid/grids, job/jobs, repo/repos, doc/docs, user/users, group/groups, tag/tags. (For your own user info use general_whoami.) |
fields | array of string | null | Fields to return. Validated against an allowlist; unrecognised fields are dropped and reported in `dropped_fields` of the response. Common: id, name, shortname, url, summary, type, public, created, updated Nested: social { likes favs }, tags { id name }, author { username } Jobs: schedule, last_run_status, last_run_time, run_count, job_steps, current_step Mails: recipients { to { type recipient { id name } } } Users: username, name Groups: parent_group Blocked (context efficiency): description Call with `introspect=True` to see the full list per resource. |
limit | integerdefault 20 | Max items to return (1-50, default 20). Server caps at 50; capping is reported in `notes`. When client-side filters (filter_text, tag, date) trigger auto-pagination, `limit` does NOT cap the result set — a note explains. |
offset | integerdefault 0 | Skip first N items for pagination (default 0) |
author | string | null | Filter by author username. Use `scope` instead for the common cases; `author` is the low-level override. |
scope | string | null | Discovery scope. Higher-level than `author`: - 'mine' (default): your own resources - 'all': resources from all users - 'shared-with-me': resources shared with any group you're in (REST fan-out across your group memberships; supports a single resource type — `resource='all'` not allowed with this scope) |
id | string | null | Server-side filter — fetch specific resource by id (the URL slug like 'example-map', NOT the shortname). |
shortname | string | null | Server-side filter — fetch specific resource by shortname (the system-generated short code in the URL, e.g. 'w9bON' for `/p/w9bON`). Useful for URL-to-resource lookups. |
type_filter | string | null | Client-side filter by resource type. For plots, only "custom" is meaningful (MCP manages custom plots only). |
filter_text | string | null | Client-side text filter (case-insensitive search across all fields) |
since | string | null | Relative-date shortcut for `start_date`. Accepts 'today', 'yesterday', or `<N><unit>` where unit is h/d/w/m. Examples: '7d' (last 7 days), '2w' (last 2 weeks), '1m' (last month). Ignored if `start_date` is also set. |
start_date | string | null | Filter by date >= this (ISO format: "2025-11-01" or "2025-11-01T10:00:00") |
end_date | string | null | Filter by date <= this (ISO format: "2025-12-31") |
tag | string | null | Filter by tag id, as general_list_resource_tags returns it (e.g., "project-x" or "+project-x", "fav", "=finance"). A bare name matches the system tag or the "+" user tag. Single-resource scope. For a CROSS-resource tag search (plots + grids + mails + ...) use `general_search_by_tag`, or set `resource='all'`. |
date_field | stringdefault "updated" | Which date field to filter on ("updated" or "created", default "updated") |
introspect | booleandefault false | If True, return available GraphQL arguments for this resource instead of data. Useful for discovering valid `query_args` keys. |
query_args | object | null | Server-side filters as dict (passed verbatim to GraphQL). Unknown keys produce a clear error in `error_messages`. Known keys (use introspect=True to discover more): - plots/grids/docs/mails/jobs/repos: shortname, id, author - users: {"username": "..."} - groups: {"name": "...", "type": "org|org_group|user_group", "parent_group": "..."} - tags: {"type": "..."} |
general_search_by_tagSearch resources by tag
Search for all resources (plots, grids, mails, jobs, repos, docs) by tag name.
Description and parameters (1)
Search for all resources (plots, grids, mails, jobs, repos, docs) by tag name.
The API automatically filters results based on your access permissions - you'll only
see resources you have access to.
Perfect for discovering project dependencies or finding all resources in a workflow.
Returns:
CallToolResult with all resources matching the tag, organized by type
(plots, grids, mails, jobs, repos, docs, etc.)
Examples:
# Find all resources tagged with "q4-2024"
general_search_by_tag(tag="q4-2024")
# Find all resources in a project
general_search_by_tag(tag="+project-alpha")| Parameter | Type | Description |
|---|---|---|
tagrequired | string | Tag name to search for (with or without '+' prefix, e.g., "project-x" or "+project-x"). Category tags keep their '=' prefix, e.g. "=finance". |
general_search_docsSearch Novem documentation
Search the Novem documentation and get back the pages to read.
Description and parameters (2)
Search the Novem documentation and get back the pages to read. Search, then read: every hit carries `md_url`, the Markdown render of that page. Fetch it to read the page in full — `snippet` is only the section that matched, and `url` is the human-facing page with the section anchor. Use this for questions about how Novem works: what a config key does, how to share a plot, which chart types exist. Use `general_help` for guides to the MCP tools in this server — those are a separate corpus.
| Parameter | Type | Description |
|---|---|---|
queryrequired | string | Natural-language question or keywords. |
limit | integerdefault 10 | Max pages to return (1-50, default 10). |
general_set_resource_sharingSet resource sharing
Share or unshare a resource with a group, an org-group, or the public.
Description and parameters (6)
Share or unshare a resource with a group, an org-group, or the public.
Four target shapes — pick the right one (full guide: general_help(topic='sharing')):
'public' — view/use access to anyone with the link
'@<user>' — share directly with a user (they must be visible to you)
'+<org>~<group>' — share with an org-group (you must be a member)
'@<user>~<group>' — share with a user-owned group (only the owner can share TO it)
Direct vs. user-group: '@bob' and '@bob~rw' share directly with the user bob;
'@bob~analysts' shares with bob's user-group 'analysts'. A second segment made
only of permission letters (r/w/d/x) always reads as a direct share, so a
personal group can't be named 'rw', 'rwd', etc.
Top-level orgs are NOT valid targets — `+novem` alone is rejected; use `+novem~<group>`.
A direct user share needs the target to be visible to you (public, connected, or a
co-member); an invisible or nonexistent user both return 404. Use `general_whoami()`
to discover which org-groups you have a role in. Membership in a user-group is not
enough to share to it; ownership is required.
Targets are pre-validated against your `general_whoami` output, so a group
you don't have a role in fails fast with a clear "not in your roles" error
rather than the misleading `404 path does not exist` the API returns
natively.
Optional permission suffix appended after the target: `~x` (default) | `~r` | `~rw` | `~rx` | `~rwx`.
Letters: x=view/use, r=use plus source read, w=write. `d` (delete) is refused: only the owner deletes. Either passed inline (`+acme~eng~rw`) or via the
`permissions` argument; inline wins if both are set. Public accepts x and r only.
**`include_embeds=True` (docs only):** also share/unshare every embedded
`{{ vis }}` / `{{ page ref: }}` plot/grid/mail inside the doc. One
confirmation prompt covers the doc plus every owned embed. Cross-user
embeds (e.g. `/u/other-user/p/foo`) are skipped — you can only share
resources you own. External-URL refs and broken refs are skipped too,
surfaced in the result.
**Embedding is NOT auto-sharing.** A viewer who can see your doc but not
its embedded plots sees "This visualisation is not available" for each
embed. Use `include_embeds=True` when publishing a doc with embeds
you've authored — the typical case.
After sharing, call `general_list_shares(name, type)` to verify the share landed.
Examples:
general_set_resource_sharing(name='q4-revenue', type='plot', target='public')
general_set_resource_sharing(name='q4-revenue', type='plot', target='@bob', permissions='rw')
general_set_resource_sharing(name='roadmap', type='doc', target='+acme~engineering')
general_set_resource_sharing(name='q1-report', type='doc',
target='+acme~engineering', include_embeds=True)
general_set_resource_sharing(name='nightly-etl', type='job',
target='@alice~data-team', permissions='rw')
general_set_resource_sharing(name='q4-revenue', type='plot',
target='+acme~engineering', revoke=True)| Parameter | Type | Description |
|---|---|---|
namerequired | string | Resource name (lowercase alphanumeric, '-', '_'). |
typerequired | string | One of plot | grid | mail | doc | job | repo | space. |
targetrequired | string | 'public' | '@<user>' | '+<org>~<group>' | '@<user>~<group>' (each optionally suffixed with `~<perms>`; slash is accepted as an ergonomic alias for `~`). |
permissions | stringdefault "x" | 'x' (default) | 'r' | 'rw' | 'rx' | 'rwx'. Public accepts only x/r (or rx). An inline permission suffix takes precedence over this argument. |
revoke | booleandefault false | True to remove an existing share. For public, an inline suffix removes only those bits; bare 'public' removes the whole grant. The permissions argument is ignored on revoke. |
include_embeds | booleandefault false | When True and type='doc', also share/unshare every embedded plot/grid/mail in the doc with the same target+permissions. One confirmation covers the lot. |
general_set_resource_varSet resource variable
Create or update a live variable on a Novem resource.
Description and parameters (8)
Create or update a live variable on a Novem resource. Variables are small formatted data points (KPIs, returns, dates, labels) attached to a plot/grid/mail/doc/job/repo. They are stored, formatted by the server, and exposed at `/v1/u/<user>/<t>/<name>/v/<var>/txt`. All fields are optional after the first set; subsequent calls only POST the fields you supply. The PUT to create the var is idempotent (409 → treated as already-exists, then field updates proceed).
| Parameter | Type | Description |
|---|---|---|
namerequired | string | Resource name (e.g. 'q4-revenue-trend'). |
typerequired | string | 'plot', 'grid', 'mail', 'doc', 'job', or 'repo'. |
var_namerequired | string | Variable identifier (lowercase, alphanumeric + `-`/`_`, max 50 chars). |
value | string | null | Raw value (max 50 chars). For numbers pass the unscaled value, e.g. '0.041' for 4.1% (paired with format `+,.1%`). For text pass the verbatim string. Optional when updating to leave the value untouched. |
about | string | null | Description (max 250 chars). |
format | string | null | Format string. Server-side default `+,.2%`. Recognised forms: - **Text**: `st` — display the raw value verbatim, no formatting. - **Numbers** (Python format mini-language): `.1f` → 22.5 (1 decimal float) `,.0f` → 21,725 (integer with thousands) `+,.1%` → +5.9% (signed percent, 1dp) `.1%` → 27.4% - **SI / scientific** (suffix `s`): `1s` → 1.2M; `2s` → 1.00m - **Money** (suffix `m`, optional currency before/after precision): `m` → 1,234.5; `.2m` → 1,234.50; `$2m` → $446.74; `.2m$` → 446.74$ - **Dates** (strftime): `%Y-%m-%d`, `%b %d, %Y`, etc. |
var_type | string | null | One of 'relative' | 'triangle' | 'plus_minus' | 'number' | 'text' | 'date'. - **`relative`**: prepends ↑/↓/→ based on sign vs threshold. - **`triangle`**: prepends ▲/▼/◆. - **`plus_minus`**: prepends +/−/=. - **`number`** / **`text`** / **`date`**: no indicator. |
threshold | string | null | Reference point for `relative` (and similar) types' indicator and colour scaling. Default '0'. |
general_whoamiWho am I
Get current authenticated user information plus group / org memberships.
Description and parameters (0)
Get current authenticated user information plus group / org memberships. Returns the authenticated username and the groups the user is a member of — useful as a one-shot before sharing operations (groups become valid share targets like `+<parent_group>~<slug>` or `@<owner>~<slug>`).
No parameters.
Custom plots
custom_plots_append_code_to_descriptionAppend code to plot description
Append the custom JavaScript code to the plot description as a markdown code block.
Description and parameters (3)
Append the custom JavaScript code to the plot description as a markdown code block.
This tool fetches the current custom.js code and description, then appends the code
to the description. If a code section already exists (marked by "### Implementation Code"),
it can either replace it or append a duplicate section.
Useful for creating showcase plots where the implementation code is displayed alongside
the visualization.
Returns:
CallToolResult with update status
Examples:
# First time - append code to description
custom_plots_append_code_to_description(plot_name="my-showcase-plot")
# Update the code section after modifying JavaScript
custom_plots_append_code_to_description(plot_name="my-showcase-plot")
# Remove the code section
custom_plots_append_code_to_description(plot_name="my-showcase-plot", remove=True)
# Force append duplicate (rarely needed)
custom_plots_append_code_to_description(
plot_name="my-showcase-plot",
replace_existing=False
)| Parameter | Type | Description |
|---|---|---|
plot_namerequired | string | Name of the custom plot |
replace_existing | booleandefault true | If True, replaces any existing code section; if False, always appends a new code section even if one exists (default: True) |
remove | booleandefault false | If True, removes the code section from the description, restoring just the original description text (default: False) |
custom_plots_append_rowsAppend plot data rows
Append rows to a custom plot without replacing existing data.
Description and parameters (2)
Append rows to a custom plot without replacing existing data. Provide one or more rows as CSV with a header row matching the existing column names. Extra columns are dropped; missing columns are filled with empty values. Use custom_plots_inspect_data first to confirm column names. **CLI handoff:** there's no dedicated CLI "append" subcommand — for bulk additions from a file on disk, compose the full CSV locally and re-push the whole thing with **`novem -p <plot_name> -w data @data.csv`** instead of looping calls to this tool. This tool is right for small in-conversation additions (a few rows the agent constructed). See `general_help(topic='cli-handoff')`.
| Parameter | Type | Description |
|---|---|---|
plot_namerequired | string | Name of the custom plot |
rowsrequired | string | CSV string — header row followed by one or more data rows to append |
custom_plots_check_overlapCheck plot label overlap
Diagnose whether a custom plot's SVG text labels visually overlap with other chart content (bars, points, axis lines, other labels, ...) at every share-target dimension — LinkedIn (4:5, 1:1), Instagram (4:5, 1:1, 9:16), X (16:9), OG, and iOS widgets (sm/md/lg).
Description and parameters (1)
Diagnose whether a custom plot's SVG text labels visually overlap with other chart content (bars, points, axis lines, other labels, ...) at every share-target dimension — LinkedIn (4:5, 1:1), Instagram (4:5, 1:1, 9:16), X (16:9), OG, and iOS widgets (sm/md/lg). Use this AFTER finishing a custom plot edit when you want to confirm the chart still composes well across all output surfaces — author-time layouts that look fine in the editor often collide on the smaller widget canvases. Each entry includes the colliding text's CSS selector, the fraction of the label covered, the compass direction of the overlap, and a `collisions[]` array naming every individual element that contributed (drill down to find which mark sits where). EXPENSIVE: ~5-10s wall-clock. The create service renders the plot in parallel at every share-target dimension and runs an in-page detector in each — this is not free. Don't call after every small edit; call once when you believe the design is settled, then again if you make layout/typography changes.
| Parameter | Type | Description |
|---|---|---|
plot_namerequired | string | Name of the custom plot to check. |
custom_plots_createCreate custom plot
Create a custom plot with user-provided JavaScript/CSS for visualization.
Description and parameters (13)
Create a custom plot with user-provided JavaScript/CSS for visualization.
Can also clone from an existing custom plot by providing source_plot parameter.
Write your JavaScript code directly — do NOT wrap it in a function.
The runtime automatically injects your code inside a draw function, so
the following parameters are already in scope:
Key parameters available in your code:
- info.data: 2D array of data rows (refer to columns by index)
- info.metadata.format[i].type: per-column type (datetime, us_number, int, text)
- render.theme.colors[0..9]: theme palette — prefer over hardcoded hex
- render.theme.text / .bg / .accent / .axisColor / etc.: chrome tokens
- render.dark: boolean for dark mode
- render.frac: DPI scale factor for text sizing
- render.width / render.height: Container dimensions (use these, not window.innerWidth)
- render.static: true when rendering PDF/PNG — gate animations on !render.static
- node: DOM element to render into (use d3.select(node), not document.querySelector)
Lifecycle hooks — set these inside your draw code for smooth animated updates
instead of a full redraw on every data change:
render.update = ({ info, render, node, prevInfo, prevRender, done }) => {
// Called on data/config/dark-mode change. Animate freely. Call done() when complete.
};
render.resize = ({ info, render, node, prevInfo, prevRender, done }) => {
// Called on dimension-only change. Snap to new size — no animation.
};
Available libraries: D3.js v7, Observable Plot v0.6, Ramda
Before authoring from scratch, read the closest flagship example —
adapting one is faster and more reliable than re-inventing the
patterns (theme cascade, render.dark chrome, derived layout, lifecycle
hooks, etc.):
- help(topic='custom-plots-examples') ← index, pick by chart shape
- help(topic='custom-plots-example-line') ← multi-series time-series
- help(topic='custom-plots-example-bar') ← categorical bar w/ HTML tooltip
- help(topic='custom-plots-example-map') ← inlined Natural Earth basemap
For runtime API reference (what's in scope inside the draw function,
lint rules, lifecycle hook signatures):
help(topic='custom-plots')
Writing the same chart for several plots? Publish it once as a module
plot instead — a repo builds an ES module and each plot names it as its
`config/type` (`@user/repo`), so one push updates every consumer:
help(topic='module-plots')
The Novem API accepts up to 5 MB for `custom_js` and 5 MB for `data`
— effectively unbounded for any plot you'll actually author. Push
full bodies through this tool when an agent is producing the bytes.
Use the CLI only when the bytes are already on local disk and you'd
rather skip the model-context round-trip:
`novem -p <name> -w config/custom/custom.js @plot.js`
`novem -p <name> -w data @data.csv`
See `general_help(topic='cli-handoff')`.
Scaffolding: `data` and `custom_js` are both optional. If omitted, the
plot is created with renderable placeholders and the response carries a
warning naming the follow-up tool (`custom_plots_update_js` /
`custom_plots_update_data`). Use this when you want to scaffold the plot
first and fill it incrementally — common when you're still designing the
rendering code and don't want to block plot creation.
Returns:
CallToolResult with plot URL and configuration status
Examples:
# Create from scratch
custom_plots_create(
name="my-plot",
data="x,y\n1,2\n3,4",
custom_js="// visualization code"
)
# Clone from existing plot
custom_plots_create(
name="ethereum-chart",
source_plot="bitcoin-chart",
data="Date,Price\n2024-01-01,2500",
title="Ethereum Price"
)| Parameter | Type | Description |
|---|---|---|
namerequired | string | Plot name (lowercase alphanumeric, '-', '_' only) |
data | string | null | CSV data (newline-separated); first row treated as headers. Optional — if omitted, a placeholder ('placeholder\n0\n') is used. Always optional if source_plot provided (copied from source). |
custom_js | string | null | JavaScript rendering code. Optional — if omitted, a placeholder stub is used that renders '(placeholder)' text so the plot boots without errors. Always optional if source_plot provided (copied from source). |
custom_css | string | null | Optional CSS styling |
custom_deps | string | null | Optional dependencies — newline-separated Novem registry specifiers, e.g. "d3@7\n@observablehq/plot@0.6". Not comma-separated; arbitrary URLs are not supported. See general_help(topic='custom-plots') for the available libraries. |
source_plot | string | null | Optional plot to clone from. Use this to create a safe baseline before iterating — clone first, then experiment on the copy. Copies all code/config from source, then applies any explicit overrides |
title | string | null | Optional plot title |
caption | string | null | Optional plot caption |
description | string | null | Optional detailed description displayed below the plot. Supports full Markdown including headers, lists, inline `code blocks`, links, bold/italic, etc. |
summary | string | null | Optional one-sentence summary (max ~100 chars) |
theme | stringdefault "custom" | Theme name (default: 'custom') |
copy_tags | booleandefault false | If True and source_plot provided, copy tags from source (default: False) |
tags | array of string | null | Optional tags (e.g., ["q4-2024", "sales"]) |
custom_plots_get_previewPreview plot
Get a rendered output file for a custom plot.
Description and parameters (3)
Get a rendered output file for a custom plot. Returns an embedded resource URI — call resources/read with that URI to get the binary. Mirrors `mails_get_preview` and `docs_get_preview` so the LLM has a uniform preview verb across all visualization types. Pairs with `custom_plots_test_render`, which returns fresh logs and the fetched static PNG by default. Inspect its attached PNG instead of fetching that same unchanged image again. Use this tool for a requested alternate format or sharing size; default plot verification does not require those variants. Pass `share_target` to render at a share-surface size (LinkedIn, Instagram, X, og:image, iOS widget) instead of the default. Forces PNG output; PDF doesn't have share flavors. Valid slugs: linkedin-45, linkedin-11, instagram-45, instagram-11, instagram-916, x-169, some-og, ios-widget-sm, ios-widget-md, ios-widget-lg. Note: ASCII (`txt`) preview is not supported for custom plots — the server-side renderer can't represent custom JS visualisations as text.
| Parameter | Type | Description |
|---|---|---|
plot_namerequired | string | Name of the custom plot. |
format | stringdefault "png" | Output format — 'png' (default) or 'pdf'. |
share_target | string | null | Optional share-surface slug; forces PNG and overrides default dimensions. Omit for the standard preview. |
custom_plots_inspect_cssInspect plot CSS
Fetch the full CSS styling for a custom plot.
Description and parameters (1)
Fetch the full CSS styling for a custom plot. CSS files are typically small so the full content is returned. Use this before calling custom_plots_update_css to review current styles before making changes.
| Parameter | Type | Description |
|---|---|---|
plot_namerequired | string | Name of the custom plot to inspect |
custom_plots_inspect_dataInspect plot data
Inspect a custom plot's CSV data with filtering and pagination. Prefer filtered reads over fetching all data.
Description and parameters (5)
Inspect a custom plot's CSV data with filtering and pagination. Prefer filtered reads over fetching all data. - Use grep to find rows matching a pattern (e.g. grep="Norway") - Use columns to restrict which columns are returned (e.g. columns=["date", "value"]) - Use offset + limit to page through data (default: first 50 rows) The response always includes total_rows and has_more so you can plan follow-up reads. Call custom_plots_update_data to replace all data, or custom_plots_append_rows to add rows.
| Parameter | Type | Description |
|---|---|---|
plot_namerequired | string | Name of the custom plot |
offset | integerdefault 0 | Row offset for pagination (default: 0) |
limit | integerdefault 50 | Max rows to return (default: 50) |
columns | array of string | null | Column names to include (all if omitted) |
grep | string | null | Regex to filter rows — only rows with a matching cell value are returned |
custom_plots_inspect_interactionInspect real plot interactions
Inspect a plot in a real browser and exercise its visible controls.
Description and parameters (2)
Inspect a plot in a real browser and exercise its visible controls. Use this to verify requested click/hover behavior after an interactive edit. Batch up to six named actions, for example click Day, Week, Month and Year. Click/select targets can be visible control labels; click/hover can target a datum's SVG title (omit the hover target for a representative mark). A select action also requires the option value. Omit actions to discover labels first. Returns observed visible text, controls, SVG titles/positions before and after each input, browser errors, and the final screenshot. Compare observed values with the requested data semantics: a dispatched click or changed screenshot alone does not prove correctness. An unchanged active control is valid. Truncated observations cannot verify unreturned values. Uses a fresh context for this authorized plot, 1200x675, with a 30-second deadline. Local interactions do not save edits or publish the asset. Use test_render for a static PNG; use this when actual interaction matters.
| Parameter | Type | Description |
|---|---|---|
plot_namerequired | string | |
actions | array of object | null |
custom_plots_inspect_jsInspect plot JavaScript
Fetch custom JavaScript code from a plot. Prefer filtered reads to avoid flooding context.
Description and parameters (4)
Fetch custom JavaScript code from a plot. Prefer filtered reads to avoid flooding context. - Use grep to locate a function, variable, or pattern (e.g. grep="drawBars") - Use line_range to read a known section (e.g. line_range=(40, 80)) - Only omit both if you need to review the entire file (e.g. for an initial audit) The response always includes total line count so you can plan follow-up line_range reads.
| Parameter | Type | Description |
|---|---|---|
plot_namerequired | string | Name of the custom plot to inspect |
grep | string | null | Regex pattern — returns matching lines plus context_lines around each match |
line_range | array of any | null | (start, end) line numbers to fetch (1-indexed, inclusive) |
context_lines | integerdefault 3 | Lines of context around grep matches (default: 3) |
custom_plots_test_renderTest-render plot
Test rendering and SEE the static PNG together with fresh paginated log entries.
Description and parameters (4)
Test rendering and SEE the static PNG together with fresh paginated log entries.
This tool is useful for debugging custom plot rendering issues. It:
1. Snapshots the render log to find the newest existing entry (the high-water mark)
2. Triggers a server-side render by requesting the plot PNG
3. Returns ONLY log entries newer than the high-water mark (or a success message)
4. Allows scrolling through older entries if needed
5. Attaches the PNG fetched in step 2 (default). Inspect that image directly;
a second read_resource for the same unchanged render is unnecessary.
The log format from the API (multi-line messages such as browser console
output continue on lines without a timestamp; those belong to the entry
above them):
time path severity message
----------------------------- ---- -------- -----------------------------------------
2026-01-05 17:59:56.469415+00 ./ info Created new plot "example_plot".
Success Detection:
If the render produced no new log entries, the tool reports that. This is a
server-side STATIC render: code gated on `!render.static` (animations,
transitions) never runs here, and a clean log does not prove the chart looks
right. Confirm visually using the attached image. Static PNGs do not test
live click/hover handlers. Images larger than 4 MiB are not attached.
Efficient debugging workflow:
1. custom_plots_test_render(plot_name) - Check the rendered image and logs
2. custom_plots_inspect_js(plot_name, grep="pattern") - Find the relevant code
3. custom_plots_update_js_section(plot_name, ...) - Edit that section
4. Inspect the attached PNG and diagnostic_entries. New informational
logs alone are not a render failure; repeat only for a concrete defect.
Returns:
CallToolResult with paginated log entries (newest first), pagination info,
and statistics
Examples:
# Get latest 10 log entries
test_custom_plot_render(plot_name="bitcoin-bloomberg-pro")
# Get next 10 older entries
test_custom_plot_render(plot_name="bitcoin-bloomberg-pro", cursor="10")
# Get latest 20 entries
test_custom_plot_render(plot_name="bitcoin-bloomberg-pro", limit=20)
# Efficient debugging cycle
test_custom_plot_render("my-plot") # Error: "lineColor is not defined"
inspect_custom_plot_code("my-plot", grep="lineColor") # Find the issue
update_custom_plot_section("my-plot", "lineColor", "colors.line") # Fix it
test_custom_plot_render("my-plot") # The render produced no new log entries| Parameter | Type | Description |
|---|---|---|
plot_namerequired | string | Name of the custom plot to test |
cursor | string | null | Optional pagination cursor (offset). Use the nextCursor from previous response to fetch older log entries |
limit | integerdefault 10 | Number of log entries to return (default: 10) |
include_preview | booleandefault true | Include the already-fetched PNG with the logs (default True). Set False for a logs-only debugging/pagination request. |
custom_plots_updateUpdate custom plot
Convenience tool to update any fields of a custom plot without recreating it.
Description and parameters (12)
Convenience tool to update any fields of a custom plot without recreating it.
Can update data, code (JS/CSS/deps), and metadata (title, caption, description, summary, theme, tags).
Use this for quick updates of multiple fields at once. For efficient single-field updates,
use the focused tools (custom_plots_update_data, custom_plots_update_js, etc.).
Returns:
CallToolResult with update status
Examples:
# Update multiple fields at once
custom_plots_update(
plot_name="my-plot",
data="x,y\n1,2\n3,4",
title="Updated Title",
tags=["updated", "2024"]
)
# Copy from another plot
custom_plots_update(
plot_name="ethereum-chart",
match_plot="bitcoin-chart",
title="Ethereum Price"
)
# Update only JavaScript
custom_plots_update(
plot_name="my-plot",
custom_js="// new code"
)| Parameter | Type | Description |
|---|---|---|
plot_namerequired | string | Name of custom plot to update |
data | string | null | Optional CSV data to update |
custom_js | string | null | Optional JavaScript rendering code |
custom_css | string | null | Optional CSS styling |
custom_deps | string | null | Optional dependencies — newline-separated Novem registry specifiers, e.g. "d3@7\n@observablehq/plot@0.6". Not comma-separated; arbitrary URLs are not supported. See general_help(topic='custom-plots') for the available libraries. |
match_plot | string | null | Optional plot name to copy from. If provided, copies all code/config from source, then applies any explicit overrides |
title | string | null | Optional plot title |
caption | string | null | Optional plot caption |
description | string | null | Optional detailed description (supports full Markdown) |
summary | string | null | Optional one-sentence summary |
theme | string | null | Optional theme name |
tags | array of string | null | Optional tags (e.g., ["q4-2024", "sales"]) |
custom_plots_update_cssReplace plot CSS
Update the CSS styling for a custom plot (full replacement).
Description and parameters (2)
Update the CSS styling for a custom plot (full replacement).
**CLI handoff:** if the CSS is already on disk (or you've read it with the
`Read` tool), prefer **`novem -p <plot_name> -w config/custom/custom.css @plot.css`**.
The CLI streams the file directly — no context burn. Use this MCP tool only
when you're producing the CSS in-conversation, or when no shell is available.
See `general_help(topic='cli-handoff')`.
Returns:
CallToolResult with update status| Parameter | Type | Description |
|---|---|---|
plot_namerequired | string | Name of the custom plot |
custom_cssrequired | string | CSS styling code |
custom_plots_update_dataReplace plot data
Replace the CSV data for a custom plot (full replacement — not a patch).
Description and parameters (2)
Replace the CSV data for a custom plot (full replacement — not a patch). Use custom_plots_inspect_data first to understand the current column structure before submitting new data. The first row is treated as headers. **CLI handoff:** if the CSV is already on disk (or you've read it with the `Read` tool), prefer **`novem -p <plot_name> -w data @data.csv`** — the CLI streams the file directly with no context burn. Use this MCP tool only when you're producing the CSV in-conversation, or when no shell is available (claude.ai web / iOS). See `general_help(topic='cli-handoff')`.
| Parameter | Type | Description |
|---|---|---|
plot_namerequired | string | Name of the custom plot |
datarequired | string | Full CSV content (newline-separated rows, first row = headers) |
custom_plots_update_depsSet plot dependencies
Update external dependencies for a custom plot.
Description and parameters (2)
Update external dependencies for a custom plot.
Returns:
CallToolResult with update status| Parameter | Type | Description |
|---|---|---|
plot_namerequired | string | Name of the custom plot |
custom_depsrequired | string | Newline-separated Novem registry specifiers, e.g. "d3@7\n@observablehq/plot@0.6". Not comma-separated; arbitrary URLs are not supported. See general_help(topic='custom-plots') for the available libraries. |
custom_plots_update_descriptionSet plot description
Update the description for a custom plot.
Description and parameters (2)
Update the description for a custom plot.
The description is displayed below the plot and supports full Markdown including
headers, lists, inline code blocks, links, bold/italic, etc.
Returns:
CallToolResult with update status| Parameter | Type | Description |
|---|---|---|
plot_namerequired | string | Name of the custom plot |
descriptionrequired | string | Detailed description (full Markdown supported) |
custom_plots_update_jsReplace plot JavaScript
Update the JavaScript code for a custom plot (full replacement).
Description and parameters (2)
Update the JavaScript code for a custom plot (full replacement).
For targeted edits, use custom_plots_update_js_section.
Before rewriting from scratch, check whether one of the flagship
examples already covers your chart shape — adapting one is faster
than re-deriving the patterns:
- help(topic='custom-plots-examples') ← index, pick by chart shape
- help(topic='custom-plots-example-line') ← multi-series time-series
- help(topic='custom-plots-example-bar') ← categorical bar w/ HTML tooltip
- help(topic='custom-plots-example-map') ← inlined Natural Earth basemap
**CLI handoff:** if the JS is already on disk (or you've read it with the
`Read` tool), prefer **`novem -p <plot_name> -w config/custom/custom.js @plot.js`**.
The CLI streams the file directly — no context burn. Use this MCP tool only
when you're producing the JS in-conversation, or when no shell is available.
See `general_help(topic='cli-handoff')`.
Returns:
CallToolResult with update status| Parameter | Type | Description |
|---|---|---|
plot_namerequired | string | Name of the custom plot |
custom_jsrequired | string | JavaScript rendering code |
custom_plots_update_js_sectionEdit plot JavaScript sections
Update one or more sections of custom plot JavaScript via string replacement.
Description and parameters (5)
Update one or more sections of custom plot JavaScript via string replacement.
Performs surgical edits without sending the full file. Fetches the file once,
applies all replacements, then writes back in a single request.
For a single edit provide old_code + new_code.
For multiple edits in one call provide sections — a list of {old_code, new_code} dicts.
All replacements are validated before any write — if one fails the file is not modified.
Each replacement fails if old_code is not found, or if it matches more than once
and replace_all is False.| Parameter | Type | Description |
|---|---|---|
plot_namerequired | string | Name of the custom plot to update |
old_code | string | null | Exact string to find (single-edit mode) |
new_code | string | null | Replacement string (single-edit mode) |
replace_all | booleandefault false | Replace all occurrences instead of requiring uniqueness (default: False) |
sections | array of object | null | List of {old_code, new_code, replace_all?} dicts for multi-edit mode |
custom_plots_update_metadataSet plot metadata
Update metadata fields for a custom plot (title, caption, description, summary, theme, tags).
Description and parameters (7)
Update metadata fields for a custom plot (title, caption, description, summary, theme, tags).
This tool allows you to update plot metadata without modifying the visualization code.
Only the fields you specify will be updated; others remain unchanged.
Field descriptions:
- title: Short plot title displayed at the top
- caption: Brief caption or subtitle (typically 1-2 lines)
- description: Detailed description displayed below the plot. Supports full Markdown
including headers, lists, inline `code blocks`, links, bold/italic, etc.
- summary: One-sentence summary (max ~100 chars) for search/previews
- theme: Theme name (e.g., 'custom', 'dark', 'light')
- tags: List of tags for categorization/search
Args:
plot_name: Name of the custom plot to update
title: Optional new title
caption: Optional new caption
description: Optional new description (full Markdown supported)
summary: Optional new summary
theme: Optional new theme name
tags: Optional tags (e.g., ["q4-2024", "sales"])
Returns:
CallToolResult with update status
Examples:
# Update just the title
update_custom_plot_metadata(
plot_name="bitcoin-chart",
title="Bitcoin Price History - 2024"
)
# Update description with Markdown
update_custom_plot_metadata(
plot_name="bitcoin-chart",
description="""# Overview
This chart shows Bitcoin price trends over time.
## Key Metrics
- **High**: $68,000
- **Low**: $42,000
- **Average**: $55,000
Data source: CoinMarketCap"""
)
# Update multiple fields
update_custom_plot_metadata(
plot_name="sales-dashboard",
title="Q4 2024 Sales Performance",
summary="Quarterly sales analysis by region and product",
caption="Updated January 2025"
)| Parameter | Type | Description |
|---|---|---|
plot_namerequired | string | |
title | string | null | |
caption | string | null | |
description | string | null | |
summary | string | null | |
theme | string | null | |
tags | array of string | null |
Documents
docs_append_contentAppend doc content
Append raw markdown at the very end of a doc — escape hatch.
Description and parameters (3)
Append raw markdown at the very end of a doc — escape hatch. For adding a new section at the end, **prefer** `docs_insert_section(position='end', new_content=...)` — it adds proper section structure (with the right page-break boundaries), respects the canonical blank-line spacing, and shows up cleanly in `docs_get_outline`. Use `docs_append_content` only for free-form additions that don't fit a section structure (e.g. extending the methodology callout at the end of an existing trailing section). **CLI handoff:** there's no dedicated CLI "append" subcommand for docs — if you have the new content on disk and want to extend the doc, compose the full body locally and re-push it with **`novem -d <doc_name> -w content @body.md`**. This tool is right for small in-conversation additions. See `general_help(topic='cli-handoff')`.
| Parameter | Type | Description |
|---|---|---|
doc_namerequired | string | Doc to append to. |
contentrequired | string | Markdown to append. |
separator | stringdefault "\n\n" | Inserted between existing content and new content. Defaults to a blank line. |
docs_check_embedsCheck doc embeds
Pre-publish lint for a Novem doc. Two passes:
Description and parameters (2)
Pre-publish lint for a Novem doc. Two passes:
1. **Ref validity** — every `{{ vis ref: ... }}` and `{{ page ref: ... }}`
is resolved against the API. Output groups refs by status:
- `ok` — resource resolved.
- `broken` — API returned an error (404 most likely).
- `unverifiable` — external URL or shortcode form we don't resolve.
- `bad_format` — could not parse the ref path at all.
2. **Block attribute lint** — walks every `{{ <block> ... }}` opener
(`vis`, `page`, `para`, `callout`, `author`, …) and flags keys that
aren't in the block's known set, unknown block names, and attributes on
blocks that don't accept any. The Novem doc parser is lenient — unknown
keys are silently dropped at render time — so this catch is critical
before publish.
Theme: optionally also verifies the doc's `theme` exists. Set
`include_theme=False` to skip.
Saves the LLM from doing N round-trips to verify embeds before publish.| Parameter | Type | Description |
|---|---|---|
doc_namerequired | string | |
include_theme | booleandefault true |
docs_cloneClone doc
Clone an existing doc into a new doc, with optional overrides.
Description and parameters (8)
Clone an existing doc into a new doc, with optional overrides. Useful for spinning up a sibling document that shares the source's theme/ structure but with new content — e.g. a Q1→Q2 quarterly report. Custom CSS is preserved by default; pass an explicit empty string to drop it on the clone, or a new CSS body to override.
| Parameter | Type | Description |
|---|---|---|
source_docrequired | string | |
new_doc_namerequired | string | |
content | string | null | |
display_name | string | null | |
description | string | null | |
theme | string | null | |
doc_type | string | null | |
custom_css | string | null |
docs_createCreate doc
Create a new doc with markdown content and optional theme/metadata.
Description and parameters (7)
Create a new doc with markdown content and optional theme/metadata.
| Parameter | Type | Description |
|---|---|---|
doc_namerequired | string | Unique doc identifier (lowercase, no spaces; `-` and `_` allowed). |
contentrequired | string | Novem markdown body. Supports YAML frontmatter (`--- title: ... theme: ... ---`), page breaks (`{{ page orient: portrait }}`), paragraph styling (`{{ para sz: l, st: b, al: center }} ... {{ /para }}`), callouts (`{{ callout type: info }} ... {{ /callout }}`), and embedded visualizations (`{{ vis ref: /u/user/p/plot, width: 100% }}`). Refer to `general_help(topic='docs')` for the full syntax. Begin published content with `{{ page }}`, `{{ frontpage }}` or `{{ tocpage }}`; preceding content is ignored except cascading headers/footers. Frontmatter creates no page. |
display_name | string | null | Human-readable doc name shown in the dashboard (POST /name). |
description | string | null | Free-text description (POST /description). |
theme | string | null | Theme reference. Use the built-in `novem`, `+org/yourorg` for an org theme, or any theme name available to the user. The theme cascades into every embedded plot/grid via CSS variables (`--novem-*`) and the `render.theme` JS object that custom plots receive. |
doc_type | string | null | Doc layout type. Default is `doc`; consult `general_help(topic='docs')` for other supported values. |
custom_css | string | null | Per-doc CSS override applied on top of the theme. Use the `.novem--doc--*` hooks (page, header, footer, cover, content nodes) or re-route theme primitives like `--novem-accent`, `--novem-color-1`, etc. See `general_help(topic='docs')` "Per-doc Custom CSS" for the full hook list. Note: custom_css is ignored when theme='novem'; set theme='custom' or '+org/<name>' for it to take effect. |
docs_delete_sectionDelete doc section
Delete a section by heading.
Description and parameters (4)
Delete a section by heading. Returns the number of lines removed. Blank-line gap is collapsed to exactly one blank line so the surrounding doc stays clean.
| Parameter | Type | Description |
|---|---|---|
doc_namerequired | string | Doc to edit. |
headingrequired | string | Heading text of the section to remove (em-dash/hyphen and whitespace are normalized for matching). |
level | integerdefault 2 | Heading level (default 2 = `## `). |
include_preceding_page_break | booleandefault true | Also remove the section's preceding `{{ page }}` block (default True). Set False to keep the page break so the section that follows takes its place on that page. |
docs_get_configGet doc config
Retrieve the configuration and metadata for a doc.
Description and parameters (1)
Retrieve the configuration and metadata for a doc.
| Parameter | Type | Description |
|---|---|---|
doc_namerequired | string |
docs_get_outlineGet doc outline
Return the doc's outline: headings (level + text + line + page) and page breaks.
Description and parameters (3)
Return the doc's outline: headings (level + text + line + page) and page breaks. The outline is a navigation map — much cheaper than reading the full body. Use it to orient before edits: "what sections exist, on what pages, in what order?". Also runs `_lint_doc_content` on the same fetched body and surfaces any warnings in the result — so the LLM sees outstanding markdown issues every time it navigates the doc, without an extra API call. Pairs with `docs_get_section(heading=...)` to fetch a single section by name.
| Parameter | Type | Description |
|---|---|---|
doc_namerequired | string | Doc to outline. |
include_pages | booleandefault true | Include page-break entries (default True). |
max_level | integerdefault 6 | Filter to headings at this level or shallower (default 6 = all). |
docs_get_previewPreview doc
Get a rendered output file for a doc.
Description and parameters (2)
Get a rendered output file for a doc. Currently wired server-side: `pptx` and `pdf`. PNG, TXT, and ANSI exports are planned but still stubbed in the API; calling them returns a clear error. For both supported formats the tool returns an embedded resource URI — call resources/read with that URI to get the binary.
| Parameter | Type | Description |
|---|---|---|
doc_namerequired | string | Name of the doc. |
format | stringdefault "pptx" | Output format. One of 'pptx' (default) or 'pdf'. |
docs_get_sectionRead doc section
Fetch one section (by heading text) or one page (by index) from a doc.
Description and parameters (6)
Fetch one section (by heading text) or one page (by index) from a doc.
Provide exactly one of `heading=` or `page=`:
- `heading='3 — Sector Attribution'` returns a section delimited by `## `
headings (or set `level=` for `### ` etc.). When a `{{ page }}` block
immediately precedes the heading, it is included by default
(`include_preceding_page_break=True`).
- `page=4` returns everything between the 4th `{{ page }}` boundary and the next.
Returns the raw markdown slice. Use this to read a focused chunk before
calling `docs_update_section` or `docs_replace`.| Parameter | Type | Description |
|---|---|---|
doc_namerequired | string | |
heading | string | null | |
page | integer | null | |
level | integerdefault 2 | |
include_preceding_page_break | booleandefault true | |
body_only | booleandefault false | If True (and `heading=` was provided), return only the body text — no heading line, no preceding `{{ page }}` block, no leading or trailing blank lines. Round-trips with `docs_update_section(keep_heading=True, ...)`. Default False. |
docs_grepSearch doc content
Search a doc's markdown content for a regex (or literal string) pattern.
Description and parameters (6)
Search a doc's markdown content for a regex (or literal string) pattern. Use this to find where a topic / phrase / variable / vis embed lives before editing — much cheaper than fetching the full content. Returns each match with line number, page number, and ±N lines of surrounding context. Pairs naturally with `docs_get_section` (read the section the match is in) and `docs_replace` (do a search-and-replace of the same pattern).
| Parameter | Type | Description |
|---|---|---|
doc_namerequired | string | Doc to search. |
patternrequired | string | Regex by default; pass `regex=False` for a literal string match. |
context_lines | integerdefault 2 | Number of context lines on each side (default 2). |
max_matches | integerdefault 50 | Cap the result list (default 50). Refine the pattern if hit. |
regex | booleandefault true | Treat `pattern` as a regex (default). False = literal substring. |
case_sensitive | booleandefault false | Default False (case-insensitive match). |
docs_insert_sectionInsert doc section
Insert a brand-new section into the doc.
Description and parameters (5)
Insert a brand-new section into the doc. Insertion uses canonical blank-line splicing — exactly one blank line is ensured on each side of the inserted block, so the doc stays clean.
| Parameter | Type | Description |
|---|---|---|
doc_namerequired | string | Doc to edit. |
new_contentrequired | string | Full markdown for the new section. Should include the heading line and any leading `{{ page }}` block you want. |
position | stringdefault "after" | - `'before'` / `'after'`: place relative to `target_heading`. - `'start'`: place before the first `## ` section. - `'end'`: append after the last section. |
target_heading | string | null | Anchor heading (required for before/after, ignored otherwise). |
level | integerdefault 2 | Heading level used to identify the target (default 2 = `## `). |
docs_inspect_contentInspect doc content
Inspect a doc's content without flooding the LLM with the full markdown.
Description and parameters (3)
Inspect a doc's content without flooding the LLM with the full markdown.
| Parameter | Type | Description |
|---|---|---|
doc_namerequired | string | Doc to inspect. |
mode | stringdefault "summary" | 'summary' (default) returns frontmatter, headings, embeds, and counts — ideal for orienting before an edit. 'full' returns the raw markdown, capped at `max_chars`. 'head' returns only the first `max_chars` chars. |
max_chars | integerdefault 4000 | Cap for full/head modes (default 4000). |
docs_inspect_custom_cssInspect doc CSS
Read the doc's per-doc custom CSS (the file at `/config/custom/custom.css`).
Description and parameters (2)
Read the doc's per-doc custom CSS (the file at `/config/custom/custom.css`).
Use this to inspect existing branding/style overrides before editing. The
response is capped at `max_chars` (default 8000) to keep the LLM context tidy.
For larger CSS bodies, fetch via the `docs://{doc_name}/css` resource instead.| Parameter | Type | Description |
|---|---|---|
doc_namerequired | string | |
max_chars | integerdefault 8000 |
docs_move_sectionMove doc section
Reorder a section to a new position in the doc.
Description and parameters (6)
Reorder a section to a new position in the doc. Heading match is normalized: em-dashes vs hyphens, varying whitespace, and case differences all match. Round-trips are byte-stable thanks to canonical blank-line splicing.
| Parameter | Type | Description |
|---|---|---|
doc_namerequired | string | Doc to edit. |
headingrequired | string | Source section heading (the one to move). |
target_heading | string | null | Anchor heading (required for 'before'/'after'). Omitted for 'start' and 'end'. |
position | stringdefault "after" | - `'before' <target>`: place source immediately before target. - `'after' <target>`: place source immediately after target. - `'start'`: move source to be the first `## ` section (after frontmatter and any cover content). - `'end'`: move source to be the last section. |
level | integerdefault 2 | Heading level for both source and target (default 2 = `## `). |
include_preceding_page_break | booleandefault true | Include the source's preceding page break in the moved slice. Default True — sections that open their own page keep their own page after the move. |
docs_replaceFind and replace in doc
Search-and-replace across a doc's markdown content.
Description and parameters (6)
Search-and-replace across a doc's markdown content. Returns the count of replacements made. If zero matches, the doc is not modified. Pairs naturally with `docs_grep` (preview matches first).
| Parameter | Type | Description |
|---|---|---|
doc_namerequired | string | Doc to edit. |
findrequired | string | Pattern to find. Literal by default; pass `regex=True` to use a Python regex. |
replacerequired | string | Replacement string. With `regex=True`, supports `\1`, `\2`, etc. |
regex | booleandefault false | Treat `find` as a regex (default False). |
count | integer | null | Cap the number of replacements (default: replace all). |
case_sensitive | booleandefault true | Default True. |
docs_set_themeSet doc theme
Set the theme on a doc. The theme cascades through every embedded plot/grid: custom plots receive theme tokens via CSS variables (`var(--novem-*)`) and a `render.theme` JS object.
Description and parameters (2)
Set the theme on a doc. The theme cascades through every embedded plot/grid: custom plots receive theme tokens via CSS variables (`var(--novem-*)`) and a `render.theme` JS object. Common theme values: - `novem` — built-in default - `+org/<orgname>` — your organisation's theme - any custom theme published to your account Use `general_help(topic='docs')` for the full theme cascade explanation.
| Parameter | Type | Description |
|---|---|---|
doc_namerequired | string | |
themerequired | string |
docs_spellcheckSpellcheck doc
Spellcheck the prose of a doc and return a list of suspicious words.
Description and parameters (4)
Spellcheck the prose of a doc and return a list of suspicious words.
The checker walks the doc body and styled blocks (`{{ para }}` / callout /
preview) and skips: frontmatter, `{{ page }}` and `{{ vis }}` blocks, code
fences, inline code, link URLs, theme tokens, and the wrappers around
`[[text]]{fg: token}` / `[[ref: text]]` / `[[ftn: text]]` (the inline
text inside those is checked). Numeric tokens, single letters, and short
all-caps acronyms are dropped automatically.
Saves the LLM from reading the entire doc to look for typos.| Parameter | Type | Description |
|---|---|---|
doc_namerequired | string | Doc to check. |
language | stringdefault "en" | Spellchecker language code (default 'en'; pyspellchecker also supports 'es', 'fr', 'pt', 'de', 'it', 'ru', 'ar', etc.). |
custom_dict | array of string | null | Optional list of project-specific words to mark as known. Combined with the built-in NOVEM_CUSTOM_DICT (novem, vislib, MCP, PPTX, financial acronyms like AUM/CAGR/EBITDA, …). |
max_words | integerdefault 200 | Cap on number of misspellings returned (default 200). Refine the custom dict if hit. |
docs_swap_sectionsSwap doc sections
Atomically swap two sections.
Description and parameters (5)
Atomically swap two sections. `heading_a` ends up where `heading_b` was, and vice versa. Page-break blocks travel with each section, so each one keeps its own page after the swap. Heading match is forgiving (em-dash/hyphen/whitespace/case-insensitive). A single atomic operation — saves you from two `docs_move_section` calls and the position-math gymnastics that go with them.
| Parameter | Type | Description |
|---|---|---|
doc_namerequired | string | Doc to edit. |
heading_arequired | string | First section to swap. |
heading_brequired | string | Second section to swap. |
level | integerdefault 2 | Heading level for both (default 2 = `## `). |
include_preceding_page_break | booleandefault true | Include each section's preceding page break in the swap. Default True. |
docs_updateUpdate doc fields
Update one or more fields of an existing doc without recreating it. Only supplied fields are updated.
Description and parameters (7)
Update one or more fields of an existing doc without recreating it. Only supplied fields are updated. For surgical content edits, prefer `docs_update_content` (replace) or `docs_append_content` (append). For just changing the theme, `docs_set_theme` is the focused tool. For just changing the per-doc CSS, use `docs_update_custom_css`.
| Parameter | Type | Description |
|---|---|---|
doc_namerequired | string | |
content | string | null | |
display_name | string | null | |
description | string | null | |
theme | string | null | |
doc_type | string | null | |
custom_css | string | null |
docs_update_contentReplace doc content
Replace the entire markdown body of a doc — escape hatch, not the primary edit tool.
Description and parameters (2)
Replace the entire markdown body of a doc — escape hatch, not the primary edit tool. For partial edits, **prefer the section tools**: - `docs_update_section(keep_heading=True, ...)` to rewrite one section's body - `docs_replace(find=..., replace=...)` for search-and-replace - `docs_insert_section(...)` / `docs_delete_section(...)` / `docs_move_section(...)` for structure - `docs_swap_sections(...)` to swap two sections Use `docs_update_content` only when you're rewriting the doc from scratch or making changes that span the whole document and don't fit any section pattern. It's the riskiest write path because a single typo replaces the entire body. **CLI handoff:** if the markdown body is already on disk (or you've read it with the `Read` tool), prefer **`novem -d <doc_name> -w content @body.md`**. The CLI streams the file directly — no context burn. Use this MCP tool only when you're producing the markdown in-conversation, or when no shell is available. See `general_help(topic='cli-handoff')`.
| Parameter | Type | Description |
|---|---|---|
doc_namerequired | string | |
contentrequired | string |
docs_update_custom_cssReplace doc CSS
Replace the per-doc custom CSS — POSTs to `/config/custom/custom.css`.
Description and parameters (2)
Replace the per-doc custom CSS — POSTs to `/config/custom/custom.css`.
Use this for branded styling on top of the theme cascade: re-routing theme
primitives (e.g. `--novem-accent`, `--novem-color-1`), styling the page
chrome (`.novem--doc--page-header`, `.novem--doc--footer`), or adding
cover-page typography (`.novem--doc--cover-title`, `--cover-subtitle`).
Theme requirement: this CSS is only injected at render when the doc's
theme is `custom` or `+org/<name>`. The built-in `novem` theme intentionally
ignores it — set the theme accordingly with `docs_set_theme` if needed.
See `general_help(topic='docs')` "Per-doc Custom CSS" for the full hook
list (page structure, cover, content nodes, layout vars, data attrs).
The API accepts large bodies. Push CSS through this tool when an
agent is producing it; reach for the CLI only when the CSS is
already on local disk:
`novem -d <doc_name> -w config/custom/custom.css @doc.css`
See `general_help(topic='cli-handoff')`.| Parameter | Type | Description |
|---|---|---|
doc_namerequired | string | |
custom_cssrequired | string |
docs_update_sectionUpdate doc section
Replace one section's body in place, identified by its heading.
Description and parameters (6)
Replace one section's body in place, identified by its heading.
The new body should include the heading line itself (e.g. `## 3 — New Heading`)
if you want to keep or change the heading. The section is delimited by the
next heading at the same or higher level (or end of doc). Any preceding
`{{ page }}` block is included by default and replaced as part of the slice.
Pairs with `docs_get_section` (read the current body first).| Parameter | Type | Description |
|---|---|---|
doc_namerequired | string | Doc to edit. |
headingrequired | string | Heading text (whitespace and em-dashes are normalized for matching). |
new_contentrequired | string | Full markdown for the new section. If `keep_heading=False` (default), include the heading line and any preceding `{{ page }}` block you want to retain. If `keep_heading=True`, provide ONLY the body (no heading line, no page block) — the existing heading and page block are preserved. |
level | integerdefault 2 | Heading level to match (default 2 = `## `). |
include_preceding_page_break | booleandefault true | If True (default), an immediately preceding `{{ page }}` block is part of the slice. Ignored when keep_heading=True. |
keep_heading | booleandefault false | If True, keep the existing heading line + preceding page block, replace only the body that follows. Saves you from retyping the heading and prevents accidental heading-level mistakes. |
Grids
grids_cloneClone grid
Clone an existing grid into a new one, with optional overrides for layout, mapping, and config.
Description and parameters (16)
Clone an existing grid into a new one, with optional overrides for layout, mapping, and config.
| Parameter | Type | Description |
|---|---|---|
source_gridrequired | string | |
new_grid_namerequired | string | |
layout | string | null | |
mapping | string | null | |
header_title | string | null | |
footer_footnote | string | null | |
footer_pagenum | boolean | null | |
border_style | string | null | |
border_color | string | null | |
border_corner | string | null | |
border_label | string | null | |
theme | string | null | |
color_theme | string | null | |
display_name | string | null | |
description | string | null | |
summary | string | null |
grids_createCreate grid
Create a Novem grid dashboard with layout, mapping, and optional configuration.
Description and parameters (19)
Create a Novem grid dashboard with layout, mapping, and optional configuration.
CRITICAL - Layout and Mapping Syntax:
Layout must be ASCII box art with {ID:-} placeholders:
Example (RECOMMENDED FORMAT with vertical spacing):
layout = "+---------------------------+---------------------------+
| | |
| {A:-} | {B:-} |
| | |
+---------------------------+---------------------------+
| | |
| {C:-} | {D:-} |
| | |
+---------------------------+---------------------------+"
IMPORTANT Layout Rules:
- Use +, -, | for box drawing
- Placeholders: {ID:-} where ID is a single letter/number
- Cell width (dashes) determines horizontal space - use at least 25-30 dashes per cell
- CRITICAL: Include empty lines above/below placeholders for vertical spacing
- Custom plots and complex visualizations REQUIRE adequate spacing to render
- Without vertical spacing, plots may fail to render completely
Mapping binds each placeholder to a plot with format: "ID => REFERENCE,options"
Example:
mapping = "A => /p/sales-summary,c=t
B => u/acme/p/revenue-trend,c=t,m=d,s=2
C => https://novem.io/u/acme/p/regional-comparison,c=t,tbg=f"
- References accept a shortname; /p/name or p/name; /u/user/p/name or
u/user/p/name; and official https://novem.io/u/user/p/name URLs
- Comma options (preferred): c=t/f (caption), h=t/f (header),
m=l/d (mode), s=1/2/3 (scale), tbg=t/f (transparent background)
- Standard query options also work, e.g. /p/plot-name?c=t&m=d&scale=2
Args:
grid_name: Grid identifier
layout: ASCII box art layout with {ID:-} placeholders
mapping: Panel-to-plot mapping (format: "ID => /p/plot-name,c=t")
header_title: Header title text (optional)
footer_footnote: Footer footnote text (optional)
footer_pagenum: Show page numbers (optional)
border_style: Border style - "single", "double", "none" (optional)
border_color: Border color hex code, e.g., "#2c3e50" (optional)
border_corner: Border corners - "round", "square" (optional)
border_label: Border label text (optional)
theme: Theme name (optional)
color_theme: Color theme (optional)
display_name: Display name in web app (optional)
description: Grid description (optional)
summary: Grid summary (optional)
grid_type: Grid type setting (default: "fs" for fullscreen layout, better for most cases)
Other options: "default" for standard layout
include_preview: If True, embed preview reference (optional)
include_layout: If True, embed layout in response (optional)
include_mapping: If True, embed mapping in response (optional)
Returns:
CallToolResult with grid URL and configuration status| Parameter | Type | Description |
|---|---|---|
grid_namerequired | string | |
layoutrequired | string | |
mappingrequired | string | |
header_title | string | null | |
footer_footnote | string | null | |
footer_pagenum | boolean | null | |
border_style | string | null | |
border_color | string | null | |
border_corner | string | null | |
border_label | string | null | |
theme | string | null | |
color_theme | string | null | |
display_name | string | null | |
description | string | null | |
summary | string | null | |
grid_type | stringdefault "fs" | |
include_preview | booleandefault false | |
include_layout | booleandefault false | |
include_mapping | booleandefault false |
grids_get_configGet grid config
Retrieve the JSON config/metadata for a grid.
Description and parameters (1)
Retrieve the JSON config/metadata for a grid.
| Parameter | Type | Description |
|---|---|---|
grid_namerequired | string |
grids_get_previewPreview grid
Get a rendered output file for a grid.
Description and parameters (2)
Get a rendered output file for a grid. Returns an embedded resource URI — call resources/read with that URI to get the binary. Note: ASCII (`txt`) preview is not supported for grids. Grids are typically composed of custom plots, and the server-side renderer can't represent custom JS visualisations as text.
| Parameter | Type | Description |
|---|---|---|
grid_namerequired | string | Name of the grid. |
format | stringdefault "png" | Output format — 'png' (default) or 'pdf'. |
grids_updateUpdate grid
Update grid layout/mapping/config without recreating. Only supplied fields are updated.
Description and parameters (17)
Update grid layout/mapping/config without recreating.
Only supplied fields are updated.
IMPORTANT - Layout Format (if updating layout):
- Include empty lines above/below placeholders for vertical spacing
- Use at least 25-30 dashes per cell for horizontal space
- Example working format:
"+---------------------------+---------------------------+
| | |
| {A:-} | {B:-} |
| | |
+---------------------------+---------------------------+"
- Without proper spacing, custom plots may fail to render
Parameters:
layout: ASCII box art layout with {ID:-} placeholders (see format above)
mapping: Panel-to-plot mapping (format: "ID => /p/plot-name,c=t")
grid_type: Grid type setting (e.g., "fs" for fullscreen, "default" for standard)
header_title, footer_footnote, border_style, theme, etc.: Optional configuration
match_grid: Optional grid name to copy layout/mapping/styling from. If provided,
copies layout, mapping, and all configuration from the source grid.
Explicit parameters override the copied values.
Examples:
# Copy layout and styling from another grid
update_grid(
grid_name="new-dashboard",
match_grid="crypto-spaced-2x2"
)
# Match a grid but override specific settings
update_grid(
grid_name="new-dashboard",
match_grid="crypto-spaced-2x2",
header_title="Custom Title"
)| Parameter | Type | Description |
|---|---|---|
grid_namerequired | string | |
layout | string | null | |
mapping | string | null | |
header_title | string | null | |
footer_footnote | string | null | |
footer_pagenum | boolean | null | |
border_style | string | null | |
border_color | string | null | |
border_corner | string | null | |
border_label | string | null | |
theme | string | null | |
color_theme | string | null | |
display_name | string | null | |
description | string | null | |
summary | string | null | |
grid_type | string | null | |
match_grid | string | null |
Mails
mails_cloneClone mail
Clone an existing mail into a new mail, with optional overrides (subject, content, recipients, theme, etc.).
Description and parameters (12)
Clone an existing mail into a new mail, with optional overrides (subject, content, recipients, theme, etc.).
| Parameter | Type | Description |
|---|---|---|
source_mailrequired | string | |
new_mail_namerequired | string | |
subject | string | null | |
content | string | null | |
to_recipients | string | null | |
cc_recipients | string | null | |
bcc_recipients | string | null | |
reply_to | string | null | |
size | string | null | |
theme | string | null | |
description | string | null | |
summary | string | null |
mails_createCreate mail
Create a new mail resource with content and optional recipients/config.
Description and parameters (12)
Create a new mail resource with content and optional recipients/config.
| Parameter | Type | Description |
|---|---|---|
mail_namerequired | string | Unique mail identifier (no spaces) |
subjectrequired | string | Mail subject line |
contentrequired | string | Markdown body (supports Novem template syntax). For example: # Example weekly summary |
display_name | string | null | Webapp display name for the mail (POST /name). |
to_recipients | string | null | Optional newline-separated primary recipients |
cc_recipients | string | null | Optional newline-separated CC recipients |
bcc_recipients | string | null | Optional newline-separated BCC recipients |
reply_to | string | null | Reply-to email or "yes"/"noreply" value |
size | string | null | Optional size (e.g., "small") |
theme | string | null | Optional theme |
description | string | null | Optional description |
summary | string | null | Optional summary |
mails_get_configGet mail config
Retrieve the configuration and metadata for a mail.
Description and parameters (1)
Retrieve the configuration and metadata for a mail.
| Parameter | Type | Description |
|---|---|---|
mail_namerequired | string |
mails_get_previewPreview mail
Get a rendered output file for a mail.
Description and parameters (2)
Get a rendered output file for a mail. Use this to retrieve a mail as PNG, PDF, or plain text. For png and pdf, returns a resource URI — call resources/read with that URI to get the binary. For txt, returns the text content directly.
| Parameter | Type | Description |
|---|---|---|
mail_namerequired | string | Name of the mail. |
format | stringdefault "png" | Output format — "png" for image, "pdf" for PDF document, "txt" for text export. |
mails_sendSend mail
Trigger sending of a prepared mail.
Description and parameters (3)
Trigger sending of a prepared mail. By default the mail goes to its stored recipients (POST /status with 'send'). Pass `to` to send this one delivery to ad-hoc addresses instead: the supplied addresses replace the stored recipient list for this send only. Ad-hoc sends take direct e-mail addresses only — not cc/bcc, @user handles or groups — and the mail's content, subject and theme are unchanged. Sending to direct addresses requires a paid plan.
| Parameter | Type | Description |
|---|---|---|
mail_namerequired | string | The mail to send. |
to | array of string | null | Optional ad-hoc recipient addresses. When supplied, replaces the stored recipient list for this send only. |
note | string | null | Optional note surfaced in the confirmation prompt. |
mails_updateUpdate mail
Update mail configuration/content/recipients without recreating. Only supplied fields are updated.
Description and parameters (12)
Update mail configuration/content/recipients without recreating. Only supplied fields are updated.
| Parameter | Type | Description |
|---|---|---|
mail_namerequired | string | |
subject | string | null | |
content | string | null | |
display_name | string | null | |
to_recipients | string | null | |
cc_recipients | string | null | |
bcc_recipients | string | null | |
reply_to | string | null | |
size | string | null | |
theme | string | null | |
description | string | null | |
summary | string | null |
Jobs
jobs_createCreate job
Create a new job in Novem that runs a chain step from a git repository.
Description and parameters (7)
Create a new job in Novem that runs a chain step from a git repository.
Jobs are automated tasks that run in isolated Docker containers. They can:
- Process uploaded files (CSV, JSON, TXT)
- Update Novem visualizations
- Fetch data from external APIs
- Run on schedules (cron syntax)
- Execute on-demand via jobs_run_now() or jobs_run_with_file()
The job's /config/chains is set to the short-form repo ref (resolves to
@<owner>/<repo_name>:latest), giving a single-step chain. The image is
produced by the repo's push build — push code via git before running.
For multi-step DAGs (multiple repos piped together) write /config/chains
directly via general_api_POST; see general_help(topic='jobs').
Jobs run in Docker containers with:
- /input/ directory: Files and JSON payloads
- /output/ directory: Results written here
- Environment variables: Credentials and configuration
Returns:
CallToolResult with job configuration and URL
Prerequisites:
1. Repository must exist (create with repos_create())
2. Code must be pushed to repository via git — the push builds the
chain-runnable image at @<owner>/<repo_name>:latest
3. Repository should contain a main Python script (or a Dockerfile)
4. Script must handle /input and /output directories
Job Script Requirements:
- Read /input and write /output directly; the image receives no extra arguments
- List files in /input before processing
- Write results to /output/result.txt
- Access env vars via os.environ
Examples:
# Job that updates Novem plot via API (needs token)
jobs_create(
job_name="plot-updater",
job_description="Fetch data and update plot via API",
repo_name="plot-jobs",
env_vars={
"PLOT_NAME": "sales_dashboard"
},
auto_create_token=True # Declares API access; token injected per run
)
# Job that only processes files (no token needed)
jobs_create(
job_name="csv-processor",
job_description="Process uploaded CSV and output summary",
repo_name="data-jobs",
auto_create_token=False # No API requests, no token needed
)
# Scheduled job with API access
jobs_create(
job_name="daily-sync",
job_description="Sync external data to Novem plots",
repo_name="sync-jobs",
schedule="0 8 * * *", # Daily at 8 AM
auto_create_token=True # Needs API access to update plots
)
Best Practices:
1. Test before scheduling: Use jobs_run_now() to verify execution
2. Store secrets in env_vars, never hardcode in code
3. Use descriptive names: "daily-sales-report" not "job1"
4. Check logs after creation: jobs_get_log(job_name) or jobs_get_log(job_name, run_name=...)
5. Start without schedule, add later: jobs_update(job_name, schedule="...")
Security Notes:
- Tokens only needed for jobs making API requests to Novem
(updating plots, sending mails, etc.)
- Jobs that only process files don't need tokens
- Use auto_create_token=True for jobs that need API access
- Auto-created tokens are never exposed in chat or stored in memory
- Each job gets its own token, isolated from your main account
- Environment variables are stored securely on the backend
- Keys are normalized to lowercase
- Use Content-Type: text/plain for CSV data POSTs to plots
Common Mistakes:
Creating job before pushing code to repository
Hardcoding credentials in job script
Using uppercase in job_name
Scheduling without testing first
Data Integrity:
Jobs that fetch or process data must use REAL data sources. Never generate
synthetic or placeholder data without explicitly informing the user that
the data is artificial.
See also:
- repos_create(): Create repository for job code
- jobs_run_with_file(): Execute with file upload
- jobs_run_now(): Trigger with JSON payload
- jobs_update(): Modify configuration
- jobs_set_env(): Update environment variables
- general_help(topic='ecosystem'): Python library and CLI usage
- general_help(topic='api-structure'): REST API patterns
- general_help(topic='jobs'): Comprehensive jobs documentation
- general_help(topic='jobs-examples'): Working code examples| Parameter | Type | Description |
|---|---|---|
job_namerequired | string | Unique identifier (lowercase, alphanumeric, hyphens only) Example: "daily-sales-report" |
job_descriptionrequired | string | Human-readable description of what the job does Example: "Process sales data and update dashboard" |
repo_namerequired | string | Name of git repository containing job code (must exist) Created via repos_create() tool. The repo's push build produces the image this job's chain step runs. |
schedule | string | null | Optional cron expression for automatic execution Examples: - "0 8 * * *" = Daily at 8 AM - "0 */4 * * *" = Every 4 hours - "0 0 * * 0" = Weekly on Sunday at midnight Use https://crontab.guru/ to validate syntax |
env_vars | object | null | Optional environment variables as key/value pairs. Use for configuration parameters and custom settings. Keys are normalized to lowercase. |
auto_create_token | booleandefault false | If True, names the claim the job runs with (access_claim, default global: the job acts as its owner). A job that already names a claim keeps it unchanged. The platform then provisions NOVEM_TOKEN itself for every run: minted at launch for the job's owner, injected into the job's environment, revoked when the run ends. Only the job's owner can grant this; a scoped or non-owner session is told so in the result, and a job whose other writers hold write shares, or whose config/env still holds a hand-pasted NOVEM_TOKEN, is told what to change first. Only needed for jobs that make API requests to Novem (e.g., updating plots, sending mails). Jobs that only process files don't need it. No token is ever exposed in chat or stored anywhere. Default: False |
access_claim | string | null | Which claim the job runs with when granting access: "global" (everything the owner can do — the default), "repo_ro" (clone the owner's repos, nothing else) or "repo_rw" (clone and push). Pick the narrowest that covers the job's API calls. Setting this implies auto_create_token=True. |
jobs_delete_envDelete job environment variables
Delete one or more environment variable keys from a job.
Description and parameters (2)
Delete one or more environment variable keys from a job. job_name is your job's name, or a job shared with you for write as '@<owner>~<job>' or '/u/<owner>/j/<job>'.
| Parameter | Type | Description |
|---|---|---|
job_namerequired | string | |
keysrequired | array of string |
jobs_get_configGet job config
Retrieve job config (repo, schedule, env names).
Description and parameters (1)
Retrieve job config (repo, schedule, env names). job_name is your job's name, or a job shared with you as '@<owner>~<job>' or '/u/<owner>/j/<job>'.
| Parameter | Type | Description |
|---|---|---|
job_namerequired | string |
jobs_get_logGet job log
Get logs and run history for a specific job in Novem.
Description and parameters (2)
Get logs and run history for a specific job in Novem.
| Parameter | Type | Description |
|---|---|---|
job_namerequired | string | Name of your job, or a job shared with you as '@<owner>~<job>' or '/u/<owner>/j/<job>' |
run_name | string | null | Optional run name. If omitted, fetches the latest run's log. |
jobs_list_envList job environment
List environment variable names for a job. Values are never returned.
Description and parameters (1)
List environment variable names for a job. Values are never returned. job_name is your job's name, or a job shared with you as '@<owner>~<job>' or '/u/<owner>/j/<job>'; a read share lists names only. Keys are returned lowercased as stored, but each is exposed inside the running container in both lowercase and uppercase forms.
| Parameter | Type | Description |
|---|---|---|
job_namerequired | string |
jobs_run_nowRun job now
Trigger a job to run immediately with an optional JSON payload.
Description and parameters (2)
Trigger a job to run immediately with an optional JSON payload.
This tool sends a JSON payload to the job, which creates /input/input.json
in the job's container. Use this for passing configuration parameters or
triggering jobs without file uploads.
**IMPORTANT:** For file uploads, use jobs_run_with_file() instead. This tool
only supports JSON payloads and will not properly handle file uploads.
Returns:
CallToolResult with trigger confirmation and job status
Example:
# Trigger job with configuration
jobs_run_now(
job_name="plot-updater",
payload={"plot_name": "sales", "date_range": "last_7_days"}
)
# Check execution results (fetches latest run's log)
logs = jobs_get_log("plot-updater")
# Or fetch a specific run's log
logs = jobs_get_log("plot-updater", run_name="run-id")
Note:
- Job receives payload in /input/input.json
- Empty payload creates empty JSON object {}
- For file processing, use jobs_run_with_file() instead
- Check jobs_get_log() for execution details (optionally pass run_name)
- A run that outlasts this call's timeout comes back with status
"running" and the trigger time. It is not a failure, so do not
trigger the job again. In jobs_get_log(), an api run started after
that time is a candidate; with other triggers queued it may not be
this one. A queued run can take a while to appear there.
Data Integrity:
Jobs that fetch or process data must use REAL data sources. Never generate
synthetic or placeholder data without explicitly informing the user.
See also:
- general_help(topic='jobs'): Comprehensive job documentation
- general_help(topic='jobs-examples'): Working code examples
- general_help(topic='ecosystem'): Python library for job scripts| Parameter | Type | Description |
|---|---|---|
job_namerequired | string | Name of your job to execute, or a job shared with you as '@<owner>~<job>' or '/u/<owner>/j/<job>' |
payload | object | null | Optional JSON-serializable dictionary passed to the job. Creates /input/input.json with this content. |
jobs_run_with_fileRun job with files
Upload one or more files (text or binary) to a job and execute it synchronously.
Description and parameters (5)
Upload one or more files (text or binary) to a job and execute it synchronously.
This tool uploads files via multipart/form-data, triggers job execution in a
Docker container, and returns the job's output directly. The workflow:
1. File(s) uploaded to job endpoint
2. Job container starts with files in /input/ directory
3. Job processes files and writes to /output/result.txt (or multiple output files)
4. HTTP response returns output (single file as text, multiple files as ZIP)
Jobs run in isolated Docker containers with:
- /input/ directory: Contains uploaded file(s)
- /output/ directory: Where job writes results
- Environment variables: Configured via jobs_set_env()
Returns:
CallToolResult with:
- Summary message
- Structured data including job output from /output/result.txt
- Input/output sizes for verification
Use Cases:
- Process CSV data files
- Analyze text reports
- Update Novem plots from data
- Generate summaries from uploaded content
- Transform data formats
Examples:
# Text file upload (single)
result = jobs_run_with_file(
job_name="sales-analyzer",
filename="sales_2024.csv",
file_content="Date,Amount,Region\n2024-01-01,1000,North\n2024-01-02,1500,South\n"
)
print(result.structuredContent["output"]) # Job's output from /output/result.txt
# Binary file upload (PDF, image, etc.)
import base64
with open("report.pdf", "rb") as f:
pdf_base64 = base64.b64encode(f.read()).decode("utf-8")
result = jobs_run_with_file(
job_name="pdf-analyzer",
filename="report.pdf",
file_content=pdf_base64,
encoding="base64"
)
# Multiple files upload (all values use base64)
result = jobs_run_with_file(
job_name="multi-file-processor",
files={
"document.txt": base64.b64encode(b"Example document").decode("ascii"),
"report.pdf": pdf_base64
},
encoding="base64"
)
# When multiple output files are created, result is a ZIP archive
Job Script Requirements:
Your job script must:
1. Read /input and write /output directly; no extra arguments are supplied
2. List files in /input directory (it's a directory, not a file!)
3. Process the uploaded file(s)
4. Write results to /output/result.txt
Example job script:
```python
import os
input_dir = "/input"
output_dir = "/output"
# List and process files
files = os.listdir(input_dir)
file_path = os.path.join(input_dir, files[0])
with open(file_path, 'r') as f:
data = f.read()
# ... process data ...
# Write results
result_file = os.path.join(output_dir, 'result.txt')
with open(result_file, 'w') as out:
out.write(f"Processed {len(data)} bytes\n")
```
Notes:
- **Synchronous execution**: Response waits for job completion
- **Long runs**: A run that outlasts this call's timeout comes back with
status "running", the trigger time and no output. Do not run the
job again. In jobs_get_log(), an api run started after that time is
a candidate; with other triggers queued it may not be this one. A
queued run can take a while to appear there.
- **File types supported**: Text (CSV, JSON, TXT) and binary (PDF, PNG, JPG, etc.)
For binary files, encode to base64 and set encoding="base64"
- **File placement**: Uploaded file(s) appear in /input/ directory
- **Output format**: Single output file returns as text, multiple outputs as ZIP
- **Multiple files**: Job receives all files in /input/ directory
- **Error handling**: Job failures return in error field of result
- **Base64 encoding**: For binary files, use base64.b64encode(bytes).decode("utf-8")
The tool automatically decodes base64 before uploading to the job
Common Mistakes:
Expecting input and output paths on the command line
Not listing files in /input before processing
Writing to wrong output location
Using jobs_run_now() for file uploads (use this tool instead!)
See also:
- jobs_run_now(): For JSON payloads without files
- jobs_create(): Set up jobs with repositories
- jobs_get_log(): View execution history and debug issues (optional run_name)
- general_help(topic='jobs'): Comprehensive job documentation
- general_help(topic='jobs-examples'): Working code examples
- general_help(topic='ecosystem'): Python library for job scripts| Parameter | Type | Description |
|---|---|---|
job_namerequired | string | Name of the job to execute (must already exist), or a job shared with you as '@<owner>~<job>' or '/u/<owner>/j/<job>' |
filename | string | Name for single uploaded file (e.g., "data.csv", "report.pdf") Optional - use this OR files parameter, not both |
file_content | string | Content of single file as a string. For text files: plain text content For binary files: base64-encoded string (set encoding="base64") Optional - use this OR files parameter, not both |
files | object | Dictionary mapping filenames to their contents (for multiple files) For text files: {"file1.csv": "plain text"} For binary files: {"file1.pdf": "base64encodedstring"} Optional - use this OR filename/file_content, not both |
encoding | stringdefault "text" | Encoding type for file content (default: "text") - "text": Content is plain text (for CSV, JSON, TXT, etc.) - "base64": Content is base64-encoded binary (for PDF, PNG, JPG, etc.) Applies to both single file and all files in files dict |
jobs_set_envSet job environment variables
Set or update environment variables for an existing job.
Description and parameters (4)
Set or update environment variables for an existing job.
**Note**: API_BASE is automatically injected with the correct API endpoint
on your own jobs. You don't need to manually set it.
**Casing**: Variable names are stored lowercased, but each variable is
exposed inside the running container under BOTH its lowercase and uppercase
forms. Setting `PLOT_NAME` makes both `plot_name` and `PLOT_NAME` available
in the job's environment, so code reading either case works.
Auto-injected variables (you don't need to set these):
- API_BASE: Set to correct API endpoint (automatically determined from environment)
- NOVEM_TOKEN: at run time, when the job names a claim (credential_status
in the result says whether it does)
Examples:
# Grant an existing job API access (API_BASE auto-injected)
jobs_set_env(
job_name="plot-updater",
auto_create_token=True
)
# Update env vars (API_BASE auto-injected)
jobs_set_env(
job_name="plot-updater",
env_vars={"PLOT_NAME": "new_plot"}
)| Parameter | Type | Description |
|---|---|---|
job_namerequired | string | Name of your job to update, or a job shared with you for write as '@<owner>~<job>' or '/u/<owner>/j/<job>' |
env_vars | object | null | Optional dictionary of environment variables to set/update |
auto_create_token | booleandefault false | If True, names the claim the job runs with (access_claim, default global: the job acts as its owner); the platform then provisions NOVEM_TOKEN per run — minted at launch for the owner, injected, revoked when the run ends. Only the owner can grant it; the result's credential_status / credential_note say what happened: declared, kept (already named), owner_grant_required (scoped or non-owner session), blocked (others hold write shares), legacy_token (config/env still holds a hand-pasted NOVEM_TOKEN, which keeps winning — delete it first), skipped (you supplied NOVEM_TOKEN yourself), or failed (the result is then an error). Only needed for jobs making API requests to Novem. No token is exposed in chat or stored anywhere. Default: False |
access_claim | string | null | "global" (default), "repo_ro" or "repo_rw" — the narrowest claim that covers the job's API calls. Setting it implies auto_create_token=True. |
jobs_updateUpdate job
Update job config without recreating it. Supply only fields you want to change.
Description and parameters (5)
Update job config without recreating it. Supply only fields you want to change.
job_name is your job's name, or a job shared with you for write as
'@<owner>~<job>' or '/u/<owner>/j/<job>'.
Examples (env_vars):
{ "PLOT_NAME": "my_plot", "API_BASE": "{auto-injected}" }| Parameter | Type | Description |
|---|---|---|
job_namerequired | string | |
job_description | string | null | |
repo_name | string | null | |
schedule | string | null | |
env_vars | object | null |
Repos
repos_createCreate repo
Set up a git repository in Novem.
Description and parameters (2)
Set up a git repository in Novem.
Repositories store code for jobs that automate data processing and visualization updates.
After creating a repo, push your code via git, then create a job that references it.
The response includes the SSH remote URL. In a shell that has both NOVEM_GIT_ORIGIN and
a Novem token ($NOVEM_TOKEN, or a `token = ` line in ~/.config/novem/novem.conf), push
over HTTPS to $NOVEM_GIT_ORIGIN/u/<owner>/r/<repo>.git instead; no SSH key is needed
there. Without the token, use the SSH remote.
If a terminal is available, use standard git commands from that point on — clone,
commit, push, diff, log. The browse tools in this module (repos_diff, repos_read_file,
etc.) exist for contexts without a terminal, such as the claude.ai web interface.
Repository code typically uses:
- Novem Python library (pip install novem)
- Direct REST API calls
- Standard Python libraries for data processing
See also:
- general_help(topic='ecosystem'): Python library installation and usage
- general_help(topic='api-structure'): REST API patterns for job scripts
- general_help(topic='jobs'): Creating jobs that use repo code
- general_help(topic='jobs-examples'): Working examples| Parameter | Type | Description |
|---|---|---|
repo_namerequired | string | |
repo_descriptionrequired | string |
repos_diffDiff repo refs
Show what changed between two refs (branches or commit SHAs).
Description and parameters (6)
Show what changed between two refs (branches or commit SHAs). The public reference for the API this tool calls is https://novem.io/docs/reference/repos/api. Two modes — pick based on what the user needs: **Summary mode** (no path): lists every file that was added, modified, or deleted. Compact output — one line per file. Use this first to understand the scope of changes before drilling into a specific file. **File diff mode** (path provided): shows a unified diff for one file, equivalent to `git diff <from> <to> -- <path>`. Paginated: use offset and limit to page through large diffs. Check has_more in the response to know if more lines are available.
| Parameter | Type | Description |
|---|---|---|
repo_namerequired | string | Name of the repository |
from_refrequired | string | Starting ref — branch name or full 40-char commit SHA |
to_refrequired | string | Ending ref — branch name or full 40-char commit SHA |
path | string | null | File path to diff (omit for changed-files summary) |
offset | integerdefault 0 | Line offset for pagination in file diff mode (default: 0) |
limit | integerdefault 200 | Max diff lines to return in file diff mode (default: 200) |
repos_get_configGet repo config
Retrieve repository configuration (name, description, SSH URL).
Description and parameters (1)
Retrieve repository configuration (name, description, SSH URL).
| Parameter | Type | Description |
|---|---|---|
repo_namerequired | string |
repos_get_logGet repo activity log
Get the activity log for a repository.
Description and parameters (1)
Get the activity log for a repository. Shows repository and build events: creation, pushes, the selected build heuristic, build progress, failure tails, and per-ref failure summaries. Use jobs_get_log for execution logs from runs of a job, not repo builds.
| Parameter | Type | Description |
|---|---|---|
repo_namerequired | string |
repos_list_branchesList repo branches
List all branches in a repository with their HEAD commit SHA.
Description and parameters (1)
List all branches in a repository with their HEAD commit SHA.
| Parameter | Type | Description |
|---|---|---|
repo_namerequired | string |
repos_list_commitsList repo commits
List recent commits in a repository.
Description and parameters (2)
List recent commits in a repository.
| Parameter | Type | Description |
|---|---|---|
repo_namerequired | string | Name of the repository |
limit | integerdefault 20 | Maximum number of commits to return (default 20, max 100) |
repos_list_filesList repo files
List files and directories in a repository at a given path and branch.
Description and parameters (3)
List files and directories in a repository at a given path and branch. The public reference for the API this tool calls is https://novem.io/docs/reference/repos/api.
| Parameter | Type | Description |
|---|---|---|
repo_namerequired | string | Name of the repository |
path | stringdefault "" | Directory path relative to repo root (default: root) |
branch | stringdefault "main" | Branch name (default: main) |
repos_read_fileRead repo file
Read the content of a file in a repository.
Description and parameters (5)
Read the content of a file in a repository. The public reference for the API this tool calls is https://novem.io/docs/reference/repos/api. Paginated by line: use offset and limit to page through large files. Check has_more in the response to know if more lines are available. The response always includes total_lines so you can plan follow-up reads.
| Parameter | Type | Description |
|---|---|---|
repo_namerequired | string | Name of the repository |
pathrequired | string | File path relative to repo root (e.g. 'main.py' or 'src/utils.py') |
branch | stringdefault "main" | Branch name (default: main) |
offset | integerdefault 0 | Line offset for pagination (default: 0) |
limit | integerdefault 200 | Max lines to return (default: 200) |
repos_ssh_keys_addAdd SSH key
Register an SSH public key with Novem for git push access.
Description and parameters (5)
Register an SSH public key with Novem for git push access.
Where there is a terminal, first run `ssh git@<host from the repo URL> keys`.
It lists keys and marks the one used; confirm it belongs to the intended account.
Host-key verification or connection failures leave this check inconclusive;
resolve them and retry.
If authentication is unconfirmed, call repos_ssh_keys_list to inspect the
account's key names. The list cannot establish whether a matching private key
is available here. Without a terminal, use the repository browse tools and
only ask about local setup if a git operation is needed.
Before requesting a keypair, inspect existing local SSH keys, SSH configuration
and the SSH agent where available. "Permission denied (publickey)" can mean an
existing key needs selecting or loading; retry with that identity first.
If a suitable existing key is not registered, register its public half here.
Each machine needs access to the private half of a registered key; registering
a separate key for another machine is normal.
Generate a new keypair locally only if no suitable key exists:
ssh-keygen -t ed25519 -C "your@email.com"
Then paste the contents of the .pub file as public_key.| Parameter | Type | Description |
|---|---|---|
key_namerequired | string | Short identifier for the key (e.g. "laptop", "work-mac") |
public_keyrequired | string | SSH public key content (the full line from your .pub file) |
namerequired | string | Display name for the key |
descriptionrequired | string | What this key is used for |
summaryrequired | string | Short one-line summary |
repos_ssh_keys_listList SSH keys
List all SSH keys registered on this Novem account.
Description and parameters (0)
List all SSH keys registered on this Novem account. Returns key names, descriptions, summaries and logs. Key content is never returned — it stays on your local machine.
No parameters.
repos_updateUpdate repo
Update repository metadata (description/name) without recreating.
Description and parameters (3)
Update repository metadata (description/name) without recreating.
| Parameter | Type | Description |
|---|---|---|
repo_namerequired | string | |
repo_description | string | null | |
display_name | string | null |
Spaces
spaces_copyCopy space file
Copy (or move) a single file across spaces, or copy within one space.
Description and parameters (5)
Copy (or move) a single file across spaces, or copy within one space. The spaces API has no copy primitive and cannot move content across spaces, so this is a client-side workaround: it reads the source file and writes it to the destination (and, when move=True, deletes the source only after the copy succeeds). Because the bytes pass through this tool it is limited to a single text file up to 256 KB — text covers CSV/TSV/TXT/Markdown/HTML as well as JSON, XML and YAML. For binary or larger files, use authenticated HTTP requests: download with `curl --output`, then upload with `curl --data-binary @file`. See `general_help(topic='spaces')` for examples. Copy folders one file at a time. For move/rename WITHIN one space, prefer spaces_move — it is a metadata-only operation with no size limit.
| Parameter | Type | Description |
|---|---|---|
src_spacerequired | string | Source space identifier. |
src_pathrequired | string | Source file path. |
dest_spacerequired | string | Destination space identifier. |
dest_pathrequired | string | Destination file path (parent folders auto-created). |
move | booleandefault false | Delete the source after a successful copy (default False). |
spaces_createCreate space
Create a new space (a file store).
Description and parameters (3)
Create a new space (a file store).
| Parameter | Type | Description |
|---|---|---|
spacerequired | string | The space identifier — lowercase letters, digits, '_' or '-'. |
display_name | string | null | Optional human-friendly name shown in the web app. |
description | string | null | Optional description. |
spaces_create_folderCreate space folder
Create a folder in a space.
Description and parameters (2)
Create a folder in a space.
The public reference for the API this tool calls is https://novem.io/docs/reference/spaces/api.
The path may be nested ('reports/2024/q4') — any missing parent
folders are created in the same call. Creating a folder inside an
existing folder works identically: just give the full path. The call
is idempotent — creating a folder that already exists succeeds.| Parameter | Type | Description |
|---|---|---|
spacerequired | string | The space identifier. |
pathrequired | string | Folder path within the space, e.g. 'reports/2024/q4'. |
spaces_deleteDelete space
Delete an entire space and all of its contents.
Description and parameters (1)
Delete an entire space and all of its contents.
| Parameter | Type | Description |
|---|---|---|
spacerequired | string | The space identifier to delete. |
spaces_delete_fileDelete space file or folder
Delete a file or folder within a space.
Description and parameters (3)
Delete a file or folder within a space. The public reference for the API this tool calls is https://novem.io/docs/reference/spaces/api. Deleting a non-empty folder requires recursive=True. Deleting space content is a write-tier operation (write access implies delete inside a space) — distinct from spaces_delete, which removes the whole space and requires the delete scope.
| Parameter | Type | Description |
|---|---|---|
spacerequired | string | The space identifier. |
pathrequired | string | Path of the file or folder to delete. |
recursive | booleandefault false | Delete a folder and everything under it (default False). |
spaces_get_configGet space config
Read a space's metadata (name, description, shortname, url).
Description and parameters (1)
Read a space's metadata (name, description, shortname, url).
| Parameter | Type | Description |
|---|---|---|
spacerequired | string | The space identifier (see spaces_list). |
spaces_listList spaces
List all spaces you own or can access.
Description and parameters (0)
List all spaces you own or can access. Returns each space's name and metadata. Use this to discover the `space` identifier the other spaces_* tools take.
No parameters.
spaces_list_filesList space files
List files and folders in a space, at the content root or under a folder.
Description and parameters (2)
List files and folders in a space, at the content root or under a folder. The public reference for the API this tool calls is https://novem.io/docs/reference/spaces/api.
| Parameter | Type | Description |
|---|---|---|
spacerequired | string | The space identifier. |
path | string | null | Optional folder path within the space (e.g. 'reports/2024'). Omit to list the content root. |
spaces_moveMove space file or folder
Move or rename a file or folder within a space.
Description and parameters (3)
Move or rename a file or folder within a space. The public reference for the API this tool calls is https://novem.io/docs/reference/spaces/api. `destination` is the new space-relative path. To rename in place, keep the same parent folder and change the leaf (e.g. path='a/old.csv', destination='a/new.csv'). To move, give a different folder. An existing destination file is overwritten.
| Parameter | Type | Description |
|---|---|---|
spacerequired | string | The space identifier. |
pathrequired | string | Current path of the file or folder. |
destinationrequired | string | New space-relative path. |
spaces_read_fileRead space file
Read the contents of a file in a space.
Description and parameters (2)
Read the contents of a file in a space. The public reference for the API this tool calls is https://novem.io/docs/reference/spaces/api. Return text content inline. For binary files, use an authenticated `curl --output` download to save the original bytes. See `general_help(topic='spaces')` for an example.
| Parameter | Type | Description |
|---|---|---|
spacerequired | string | The space identifier. |
pathrequired | string | File path within the space (e.g. 'data/sales.csv'). |
spaces_renameRename space identifier
Rename a space's identifier (e.g. 'my_space' -> 'old_space').
Description and parameters (2)
Rename a space's identifier (e.g. 'my_space' -> 'old_space'). This changes the space's path identifier while keeping all of its contents, folder structure, and shortname/URL intact — it is a metadata-only rename, not a rebuild. To change only the human-facing display name (not the identifier), use spaces_update_config instead.
| Parameter | Type | Description |
|---|---|---|
spacerequired | string | The current space identifier. |
new_namerequired | string | The new identifier — lowercase letters, digits, '_' or '-'. |
spaces_update_configUpdate space config
Update a space's display name and/or description.
Description and parameters (3)
Update a space's display name and/or description.
| Parameter | Type | Description |
|---|---|---|
spacerequired | string | The space identifier. |
display_name | string | null | New display name (optional). |
description | string | null | New description (optional). |
spaces_write_fileWrite space file
Write a text file to a space (create or overwrite).
Description and parameters (3)
Write a text file to a space (create or overwrite).
Any missing parent folders along `path` are created automatically.
The Content-Type is inferred from the file extension.
API upload limits apply. For local text files, use the novem CLI:
novem --space example_data -w content/data.csv @data.csv
This tool and the CLI's `-w` option accept UTF-8 text. Upload binary
files with an authenticated `curl --data-binary @file` request; see
`general_help(topic='spaces')` for an example.| Parameter | Type | Description |
|---|---|---|
spacerequired | string | The space identifier. |
pathrequired | string | File path within the space (e.g. 'data/sales.csv'). Parent folders are created as needed. |
contentrequired | string | The text content to write. |
Themes
themes_createCreate theme
Create an org theme. Admin role on the org is required.
Description and parameters (6)
Create an org theme. Admin role on the org is required.
Reference the new theme from any vis as `+<org>/<theme>` — e.g.
`docs_set_theme(doc_name, theme="+acme/corporate")`.
For assets (logos, fonts), call `themes_upload_asset` *after* creation
and reference them from CSS as `url("./assets/<name>")`.
Prefer setting `--novem-*` CSS custom properties on `.novem--doc--page`
(palette, typography, surfaces) for the broadest cross-vis impact —
embedded custom plots inherit those values automatically.| Parameter | Type | Description |
|---|---|---|
orgrequired | string | Organization name (the `<org>` in the `+org/theme` reference). |
themerequired | string | Theme name (lowercase letters/digits/hyphens/dots, 2–50 chars). |
custom_css | string | null | Initial CSS body (≤5 MiB). |
description | string | null | Long-form description (≤5 KB). |
summary | string | null | Short tagline. |
is_public | boolean | null | Default False (org-internal). Set True only when the theme will be rendered for an audience outside the owning org — public-shared vis or vis owned by users in other orgs. Don't reflexively make themes public during dev. |
themes_deleteDelete theme
Permanently delete a theme and all its assets. Admin role on the org is required.
Description and parameters (2)
Permanently delete a theme and all its assets. Admin role on the org is required. Any vis still referencing this theme renders unstyled (no error).
| Parameter | Type | Description |
|---|---|---|
orgrequired | string | Organization name. |
themerequired | string | Theme name. |
themes_delete_assetDelete theme asset
Delete a single asset from a theme. Admin role on the org is required.
Description and parameters (3)
Delete a single asset from a theme. Admin role on the org is required. Any CSS rule still referencing `./assets/<asset_name>` will fail to load that asset — clean up the CSS before deleting.
| Parameter | Type | Description |
|---|---|---|
orgrequired | string | Organization name. |
themerequired | string | Theme name. |
asset_namerequired | string | Asset file name to remove. |
themes_get_configGet theme config
Get the metadata snapshot for a single theme: description, summary, and `is_public` flag. `is_public` may be null when read by non-admin callers.
Description and parameters (2)
Get the metadata snapshot for a single theme: description, summary, and `is_public` flag. `is_public` may be null when read by non-admin callers. For the CSS body, call `themes_inspect_css`. For the asset listing, call `themes_list_assets`.
| Parameter | Type | Description |
|---|---|---|
orgrequired | string | Organization name. |
themerequired | string | Theme name (e.g. `corporate`). |
themes_inspect_cssInspect theme CSS
Inspect a theme's `custom.css`. Themes can be large; default `summary` returns size + head/tail slices so you don't flood context with the full body until you need to.
Description and parameters (5)
Inspect a theme's `custom.css`. Themes can be large; default `summary` returns size + head/tail slices so you don't flood context with the full body until you need to.
| Parameter | Type | Description |
|---|---|---|
orgrequired | string | Organization name. |
themerequired | string | Theme name. |
mode | stringdefault "summary" | `summary` (default — size + head/tail) or `full` (entire CSS). |
head_lines | integerdefault 60 | Number of leading lines for `summary` mode (default 60). |
tail_lines | integerdefault 40 | Number of trailing lines for `summary` mode (default 40). |
themes_listList themes
List themes available in an org.
Description and parameters (1)
List themes available in an org. Reference any of these from a vis's `/config/theme` as `+<org>/<theme>`.
| Parameter | Type | Description |
|---|---|---|
orgrequired | string | Organization name (the same `<org>` you'd use in `+org/theme`). |
themes_list_assetsList theme assets
List assets (logos, fonts, images) bound to a theme.
Description and parameters (2)
List assets (logos, fonts, images) bound to a theme.
Each asset can be referenced from the theme CSS as
`url("./assets/<asset_name>")`.| Parameter | Type | Description |
|---|---|---|
orgrequired | string | Organization name. |
themerequired | string | Theme name. |
themes_set_metadataSet theme metadata
Update a theme's description or summary text. Admin role on the org is required.
Description and parameters (4)
Update a theme's description or summary text. Admin role on the org is required. Pass an empty string to clear a field; omit to leave it unchanged.
| Parameter | Type | Description |
|---|---|---|
orgrequired | string | Organization name. |
themerequired | string | Theme name. |
description | string | null | Long-form description (≤5 KB). Empty string clears. |
summary | string | null | Short tagline. Empty string clears. |
themes_set_publicSet theme public flag
Toggle a theme's `is_public` flag. Admin role on the org is required.
Description and parameters (3)
Toggle a theme's `is_public` flag. Admin role on the org is required. Set True only when the theme will be rendered for an audience outside the owning org — public-shared vis or vis owned by users in other orgs. A vis whose viewer can't read the theme renders without it (falls back to skeleton styling). For internal-only org work, leave it False.
| Parameter | Type | Description |
|---|---|---|
orgrequired | string | Organization name. |
themerequired | string | Theme name. |
is_publicrequired | boolean | True → readable by anyone; False → readable only by members of the owning org. |
themes_update_cssReplace theme CSS
Replace a theme's `custom.css` body. Admin role on the org is required.
Description and parameters (3)
Replace a theme's `custom.css` body. Admin role on the org is required. Every vis referencing the theme picks up the new CSS on next render — no per-vis update needed. **CLI handoff:** if the CSS is already on disk (or you've read it with the `Read` tool), prefer **`novem -O <org> -w admin/themes/<theme>/custom.css @theme.css`**. The CLI streams the file directly — no context burn. Use this MCP tool only when you're producing the CSS in-conversation, or when no shell is available. See `general_help(topic='cli-handoff')`.
| Parameter | Type | Description |
|---|---|---|
orgrequired | string | Organization name. |
themerequired | string | Theme name. |
custom_cssrequired | string | New CSS body (≤5 MiB). |
themes_upload_assetUpload theme asset
Upload a binary asset (logo, font, image) to a theme. Admin role on the org is required.
Description and parameters (5)
Upload a binary asset (logo, font, image) to a theme. Admin role on the org is required.
Use this tool for content generated in the conversation or when no
shell is available. For local binary files, use an authenticated
`curl --data-binary @file` upload; see `general_help(topic='themes')`
for an example. The CLI's `-w` option accepts UTF-8 text, such as SVG,
rather than binary images or fonts.
Reference the asset from the theme CSS as `url("./assets/<asset_name>")`.| Parameter | Type | Description |
|---|---|---|
orgrequired | string | Organization name. |
themerequired | string | Theme name. |
asset_namerequired | string | File name (lowercase letters/digits/hyphens, optional `.ext`, ≤64 chars). The extension determines auto-inferred content type — e.g. `logo.png`, `brand-font.woff2`. |
content_base64required | string | Asset bytes encoded as base64. |
content_type | string | null | Optional override. Allowed: image/png, image/jpeg, image/gif, image/svg+xml, image/webp, font/woff, font/woff2, font/ttf, font/otf. If omitted, inferred from the file extension. |
Assets
assets_deleteDelete asset
Delete an asset from a VDE.
Description and parameters (2)
Delete an asset from a VDE.
Any `{{ img ref: <asset_name> }}` block or `render.assets['<name>']`
lookup still referencing this asset will break.| Parameter | Type | Description |
|---|---|---|
vderequired | string | VDE FQNP (see assets_list). |
asset_namerequired | string | Asset to remove. |
assets_inspectInspect asset
Inspect a single asset's metadata (size, content type, timestamps).
Description and parameters (2)
Inspect a single asset's metadata (size, content type, timestamps). Does NOT download the bytes — only metadata. Use the listing or the direct URL for byte access.
| Parameter | Type | Description |
|---|---|---|
vderequired | string | VDE FQNP (see assets_list). |
asset_namerequired | string | Name of the asset on the VDE. |
assets_listList assets
List assets attached to a VDE (plot, doc, or mail).
Description and parameters (1)
List assets attached to a VDE (plot, doc, or mail).
| Parameter | Type | Description |
|---|---|---|
vderequired | string | VDE FQNP, e.g. `/u/alice/p/myplot`, `/u/alice/d/q4-report`, or `/u/alice/m/welcome`. The long form (`/users/alice/vis/plots/myplot`) is also accepted. |
assets_uploadUpload asset
Upload a binary asset (image, font) to a VDE.
Description and parameters (4)
Upload a binary asset (image, font) to a VDE.
Use this tool for content generated in the conversation or when no
shell is available. For local binary files, use an authenticated
`curl --data-binary @file` upload; see `general_help(topic='assets')`
for an example. The CLI's `-w` option accepts UTF-8 text, such as SVG,
rather than binary images or fonts.
Reference the uploaded asset:
* from a doc / mail: `{{ img ref: <asset_name> }}`
* from a custom plot: `render.assets['<asset_name>']`| Parameter | Type | Description |
|---|---|---|
vderequired | string | VDE FQNP (see assets_list). |
asset_namerequired | string | File name (lowercase letters/digits/hyphens, optional `.ext`, ≤64 chars). Extension determines auto-inferred type. |
content_base64required | string | Asset bytes encoded as base64. |
content_type | string | null | Optional override. Allowed: image/png, image/jpeg, image/gif, image/svg+xml, image/webp, font/woff, font/woff2, font/ttf, font/otf. Inferred from extension when omitted. |
Prompts
Prompts are prepared instructions a client can offer you, usually as a slash command.
jobs_debug_failed_job
Systematic workflow to debug a failing job
Arguments: job_name (required)
jobs_setup_automated_report
Complete workflow for setting up an automated scheduled report
Resources
Resources are read-only URIs a client can fetch. A {name} in a URI is a
placeholder for the resource's name.
| URI | Type | Scope | Description |
|---|---|---|---|
novem://api-schema | text/plain | any scope | Show valid API path patterns for general_api_GET, general_api_POST, and general_api_PUT. |
novem://api-schema/{module} | text/plain | any scope | Show the API path schema for a single Novem module. |
custom-plots:// | text/plain | Custom Plots | List all available custom plot resources. |
custom-plots://{plot_name}/config | text/plain | Custom Plots | Read the full JSON configuration for a custom plot. |
custom-plots://{plot_name}/css | text/css | Custom Plots | Fetch the CSS source for a custom plot. |
custom-plots://{plot_name}/data | text/csv | Custom Plots | Fetch the CSV data backing a custom plot. |
custom-plots://{plot_name}/js | text/javascript | Custom Plots | Fetch the JavaScript source for a custom plot. |
custom-plots://{plot_name}/pdf | application/pdf | Custom Plots | Fetch the rendered PDF for a custom plot. |
custom-plots://{plot_name}/pngplots://{plot_name}/png | image/png | Custom Plots | Fetch the rendered PNG for a plot, including native plot types. |
custom-plots://{plot_name}/share/{target} | image/png | Custom Plots | Fetch a share-surface PNG render for a custom plot. |
docs:// | text/plain | Docs | List all available doc resources. |
docs://{doc_name} | text/plain | Docs | Read the config snapshot for a specific doc. |
docs://{doc_name}/content | text/markdown | Docs | Fetch the raw Novem markdown content for a doc. |
docs://{doc_name}/css | text/css | Docs | Fetch the per-doc custom CSS body (the file at `/config/custom/custom.css`). |
docs://{doc_name}/pdf | application/pdf | Docs | Fetch the rendered PDF for a doc. |
docs://{doc_name}/pptx | application/vnd.openxmlformats-officedocument.presentationml.presentation | Docs | Fetch the rendered PPTX export for a doc. |
grids:// | text/plain | Grids | List all available grid config resources. |
grids://{grid_name}/config | text/plain | Grids | Read JSON configuration for a specific grid. |
grids://{grid_name}/pdf | application/pdf | Grids | Fetch the rendered PDF for a grid. |
grids://{grid_name}/png | image/png | Grids | Fetch the rendered PNG image for a grid. |
mails:// | text/plain | Mails | List all available mail config resources. |
mails://{mail_name}/config | text/plain | Mails | Read JSON configuration for a specific mail. |
mails://{mail_name}/pdf | application/pdf | Mails | Fetch the rendered PDF for a mail. |
mails://{mail_name}/png | image/png | Mails | Fetch the rendered PNG image for a mail. |
jobs:// | text/plain | Jobs & Repos | List all available job config resources. |
jobs://{job_name}/config | text/plain | Jobs & Repos | Read configuration for a specific job. |
repos:// | text/plain | Jobs & Repos | List all available repo config resources. |
repos://{repo_name}/config | text/plain | Jobs & Repos | Read configuration for a specific repo. |
spaces:// | text/plain | Spaces | List all available spaces as resource URIs. |
spaces://{space}/config | text/plain | Spaces | Read metadata for a specific space. |
themes://{org}/{theme}/assets | text/plain | Themes | List the assets uploaded to a theme. Each asset can be referenced from the theme CSS as `url("./assets/<asset_name>")`. |
themes://{org}/{theme} | text/plain | Themes | Read the metadata snapshot for a theme: description and summary. Use `themes://{org}/{theme}/css` for the CSS body and `themes://{org}/{theme}/assets` for the asset listing. |
themes://{org}/{theme}/css | text/css | Themes | Fetch a theme's `custom.css` body as raw CSS. Use the `themes_inspect_css` tool for a head/tail summary on large stylesheets. |