Wikis Tools¶
The wikis_* tools work with wikis and their pages: finding and reading them, page history, templates and properties, creating, importing, editing, moving and deleting pages, likes and follows, and the review and approvals workflow.
All 19 tools are in the wikis tool group and need Huddo Wikis.
Naming a wiki or a page¶
Tools that act on one wiki take its url or its wikiSlug. Tools that act on one page take one of:
| Parameter | Type | Notes |
|---|---|---|
url |
URL | The page's URL |
wikiSlug, pageSlug |
string | The wiki's and page's slugs |
pageId |
id | The page's id |
These are listed as "page" in the parameter tables below.
Approvals¶
A wiki can use an approvals workflow. On a wiki without approvals, a page is live as soon as it's saved. On a wiki with approvals, new pages and changes stay unpublished until an approver accepts them or they're published: a new page is listed and opens straight away, but readers see it blank until then. Tools that create pages submit them for approval automatically on such a wiki.
wikis_list_wikis¶
Lists the wikis the user can read.
Read-only · Needs: Wikis
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
search |
string | No | Words in the wiki's name, up to 200 characters | |
tags |
array of strings | No | Up to 10 tags | |
scope |
string | No | mine (created by the user), shared (shared with them) or public (open to the organisation) |
|
starredOnly |
boolean | No | false | Only the wikis the user has starred |
sort |
string | No | activity |
activity (latest activity), accessed (the user's last visit), visits or starred |
limit |
integer | No | 20 | 1 to 50 |
skip |
integer | No | 0 | Wikis to skip, to read the next page |
Returns: wikis, each with id, slug, name, a short description, tags, pageCount, latestActivity and url; and hasMore and nextSkip when there are more.
Example: "Which wikis have I been using most?"
wikis_get_wiki¶
A wiki's overview, with its page outline.
Read-only · Needs: Wikis
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
url |
URL | No | The wiki's URL, or the URL of one of its pages | |
wikiSlug |
string | No | Instead of url: the wiki's slug |
|
maxPages |
integer | No | 200 | 1 to 200. The most pages in the outline |
Returns: id, slug, name, description, tags, documentId, url, indexPage (the home page's slug and title), following, workflowOn (whether the verified-pages workflow is on), latestActivity, pageCount, and outline, the pages with their id, slug, title and depth.
Example: "Give me an outline of the Engineering Handbook wiki."
wikis_find_pages¶
Finds pages by words in their title: in one wiki, or, without wikiSlug, among the pages the user created across all wikis. To search page text, assistants use search_content.
Read-only · Needs: Wikis
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
query |
string | Yes | Words in the title, 1 to 200 characters | |
wikiSlug |
string | No | The wiki to look in | |
limit |
integer | No | 20 | 1 to 50 |
Returns: pages, each with id, slug, title, wiki, updatedAt and url, and total or hasMore.
Example: "Find the page called Release Checklist in the Platform wiki."
wikis_get_page¶
A wiki page as Markdown, with its properties, breadcrumb, child pages, owner, dates, version, top contributors, review status, and what changed since the user last visited. Content included from other pages is shown in place, up to 10 includes. Readers see the published version of a page; servedPublished says when that's what was returned. Comments are read with huddo_get_comments.
Read-only · Needs: Wikis
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
| page | Yes | See Naming a wiki or a page | ||
maxChars |
integer | No | 20,000 | 500 to 100,000. Longer pages are cut short, with a note |
resolveIncludes |
boolean | No | true | Show included content in place |
includeInfo |
boolean | No | true | Include the owner, version, contributors, review status and changes since the last visit |
Returns: id, slug, title, documentId, wiki, url, breadcrumb, isDraft, excerpt; markdown and truncated; sequence (the version number, needed to edit the page), publishedSequence and servedPublished; properties, the page's property records that have fields, in page order, each with its recordId, its kind (such as property, idea or risk; a block with no kind counts as property) and its values as key and value pairs. Records are grouped as wiki reports group them: properties blocks with the same recordId and kind make one record, and a block with no record id is a record of its own, with recordId null. A key that appears twice in a record keeps its first value. There are up to 30 fields across all records, with propertiesTruncated set when fields or long values were cut, and propertyRowsSkipped counting the repeated or unreadable rows left out (omitted when there are none); rows with no key are dropped without being counted; includes; owner, createdAt, updatedAt; with includeInfo, version, totalVersions, contributors, review and sinceVisit; and children.
An image on the page appears in the Markdown as . An assistant that edits the page keeps that text as it is, so the image stays.
Example: "Read the Onboarding page and tell me what a new starter does in week one."
wikis_get_page_history¶
Who changed a page and when, with the workflow events (verified, flagged, submitted, approved, published), and optionally what changed between two versions.
Read-only · Needs: Wikis
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
| page | Yes | See Naming a wiki or a page | ||
limit |
integer | No | 20 | 1 to 50 |
cursor |
integer | No | A version number. Returns the versions older than it | |
includeWorkflowEvents |
boolean | No | true | Include up to 20 workflow events |
diff |
object | No | {from, to}: two version numbers to compare |
Readers never see versions newer than the published one.
Returns: url (the page's history), total, revisions (version number, author, date, label, change statistics), nextCursor, events (type, who, when, reason), and with diff, the changed text between the two versions and a link to compare them in Huddo.
Example: "Who changed the Security Policy page last week, and what did they change?"
wikis_property_report¶
Collects structured records from across a wiki or a space: every properties block of one kind (by default property; wikis can define others, such as decisions or risks), as rows of fields.
Read-only · Needs: Wikis
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
wikiSlug |
string | No | The wiki to report on | |
groupId |
string | No | Instead of wikiSlug: a space's groupId |
|
kind |
string | No | property |
The kind of record, up to 120 characters |
listKinds |
boolean | No | false | With groupId: list the kinds of record in the space instead |
limit |
integer | No | 50 | 1 to 50 |
Give either wikiSlug or groupId.
Returns: kind, and records, each with its page, url, recordId and fields; on a wiki, supersededBy, the record that replaced it, where known; and truncated. With listKinds, kinds.
Example: "List all the decisions recorded in the Architecture wiki."
wikis_list_templates¶
Lists the page templates a wiki offers for new pages.
Read-only · Needs: Wikis
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
wikiSlug |
string | Yes | The wiki | |
search |
string | No | Words in the name, description or tags, up to 200 characters | |
limit |
integer | No | 20 | 1 to 50 |
Returns: templates, each with id, name, description, purpose, tags and usageCount, and truncated.
Example: "What templates can I use for a new page in the Team wiki?"
wikis_recent_changes¶
What changed in a wiki or a space since a date: each page change, who made it, and whether the page was created or edited.
Read-only · Needs: Wikis
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
wikiSlug |
string | No | The wiki | |
groupId |
string | No | Instead of wikiSlug: a space's groupId |
|
since |
date or date-time | Yes | At most 90 days ago | |
limit |
integer | No | 20 | 1 to 50 |
Give either wikiSlug or groupId.
Returns: since, and changes, newest first, each with pageTitle, wikiName, action, label, stats, actor, createdAt and url; and truncated when there are more.
Example: "What changed in the Product space's wikis since Monday?"
wikis_create_wiki¶
Creates a wiki. The user becomes its owner. It can be created inside a space, and can start with the approvals workflow switched on.
Write · Needs: Wikis
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
name |
string | Yes | 1 to 120 characters | |
description |
string | No | Up to 1,000 characters | |
groupId |
id | No | Create the wiki in a space (the space's groupId). The user needs the right to manage the space's content |
|
approvals |
boolean | No | false | Switch on approvals, so new pages and changes stay unpublished until approved or published |
approverIds |
array of user ids | No | Up to 10 approvers. Without it, the user is the only approver |
When the user is the only approver, they can't submit their own pages for approval; they publish them instead, from the page or with wikis_review_action.
Returns: slug, name, url, approvals and next, what to tell the user.
Example: "Create a wiki called Project Falcon Notes in the Project Falcon space, with approvals on so I can review pages before anyone sees them."
wikis_create_page¶
Creates a wiki page from Markdown, optionally under another page. Creating a page notifies only the people mentioned in it.
Write · Needs: Wikis
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
wikiSlug |
string | Yes | The wiki | |
title |
string | Yes | 1 to 300 characters | |
markdown |
string | Yes | The page body, up to 200,000 characters | |
parentSlug |
string | No | A page to create it under | |
templateId |
id | No | Records which template the page came from. The assistant writes the template's content itself | |
excerpt |
string | No | Up to 500 characters |
The slug comes from the title, and may get a number added to make it unique. javascript: and data: links keep their text but lose the link, and embedded data: images are refused: to add an image, the assistant uploads it with huddo_upload_file first.
Returns: id, slug, title, url and next, what to tell the user.
Example: "Create a page under Meeting Notes in the Team wiki with today's notes."
wikis_import¶
Creates a wiki page from Markdown text or from a web page. A web page is fetched (public pages only, up to 2 MB of HTML), its scripts, styles and embedded media other than images are removed, unsafe links are unlinked, mentions become plain text, and the page starts with an "Imported from" link. Nobody is notified, apart from people mentioned in Markdown text.
Write · Needs: Wikis
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
wikiSlug |
string | Yes | The wiki | |
parentSlug |
string | No | A page to create it under | |
title |
string | No | 1 to 300 characters. Defaults to the web page's title or the Markdown's first heading | |
markdown |
string | No | Markdown text, up to 200,000 characters | |
url |
URL | No | Instead of markdown: a web page to import |
Give exactly one of markdown and url.
Returns: id, slug, title, url and next, what to tell the user.
Example: "Import https://example.com/blog/release-notes into the Product wiki."
wikis_update_page¶
Changes a page's body from Markdown: replaces the whole body, replaces one section, or adds a section to the end. Parts of the page that aren't changed keep their comments.
Overwrite · Needs: Wikis
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
| page | Yes | See Naming a wiki or a page | ||
markdown |
string | Yes | Up to 200,000 characters | |
mode |
string | Yes | replace (the whole body), replaceSection (the section under heading) or appendSection (add to the end) |
|
heading |
string | No | The text of a heading on the page. Required for replaceSection |
|
expectedSequence |
integer | No | The page's sequence from wikis_get_page. Required for replace and replaceSection |
|
publish |
boolean | No | false | Also publish the change, on a wiki with approvals that the user owns |
Safeguards:
- If someone else changed the page after the assistant read it,
expectedSequenceno longer matches and the change is refused. replaceandreplaceSectionare refused when the page (or the section) holds formatting Markdown can't carry, such as text alignment, indents, merged table cells, column widths, image sizes, or callouts other than info, tip, warning and danger.- Embedded
data:images are refused.
Someone editing the page in Huddo at the same time overwrites this change when they save.
Returns: changed, sequenceBefore and sequenceAfter, published (with publish), url, and cannotReadMentions, any mentioned person who can't read the page. If the Markdown makes no difference, changed is false.
Example: "Update the Status section of the Project Falcon page to say we're on track for March."
wikis_update_page_details¶
Changes a page's title or excerpt. Only the fields given change. The page's slug and URL stay the same.
Write · Needs: Wikis
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
| page | Yes | See Naming a wiki or a page | ||
title |
string | No | 1 to 300 characters | |
excerpt |
string | No | Up to 500 characters |
Give title, excerpt or both.
Returns: id, slug, title and url.
Example: "Rename the Q3 Plan page to Q3 Plan (Final)."
wikis_move_page¶
Moves a page within its wiki: under another page, to the top level, or to a different position among its siblings. The page's slug and URL stay the same.
Write · Needs: Wikis
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
| page | Yes | See Naming a wiki or a page | ||
newParentSlug |
string or null | No | The current parent | The new parent page. null makes it a top-level page |
beforeSlug |
string | No | Last | The sibling to put it before. Without it, the page goes last |
Returns: id, slug, parentSlug, order and url.
Example: "Move the Retro Notes page under the Archive page."
wikis_delete_wiki¶
Permanently deletes a wiki, with all its pages and their history. Only a wiki owner can delete it.
Delete · Needs: Wikis
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
url |
URL | No | The wiki's URL | |
wikiSlug |
string | No | Instead of url: the wiki's slug |
|
confirmName |
string | Yes | The wiki's exact name. A name that doesn't match is refused |
Returns: deleted, slug and name.
Example: "Delete the Sandbox wiki."
wikis_delete_page¶
Permanently deletes a page, together with every page under it, their history and their whiteboards. A wiki's home page can't be deleted.
Delete · Needs: Wikis
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
| page | Yes | See Naming a wiki or a page | ||
confirmTitle |
string | Yes | The page's exact title. A title that doesn't match is refused |
Returns: deleted, slug, title and visiblePagesDeleted, the number of pages deleted that the user could see. Pages under it that the user can't see, such as restricted pages and other people's drafts, are deleted too, but aren't counted.
Example: "Delete the Old Roadmap page and everything under it."
wikis_set_reaction¶
Likes or unlikes a page, and follows or unfollows a page or a whole wiki. Only the fields given change.
Write · Needs: Wikis
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
| page | Yes | See Naming a wiki or a page. To follow a whole wiki, give wikiSlug alone |
||
like |
boolean | No | true likes the page, false unlikes it | |
follow |
boolean | No | true follows the page or wiki, false unfollows it |
Give like, follow or both. A wiki can be followed but not liked.
Returns: likes and likedByMe (with like), and following (with follow).
Example: "Follow the Release Notes wiki so I hear about new pages."
wikis_review_queue¶
What needs review in a wiki: open approval requests, pages flagged for review with the reason, and stale pages that haven't been edited for a while. Up to 20 of each.
Read-only · Needs: Wikis
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
wikiSlug |
string | Yes | The wiki | |
forMe |
boolean | No | false | Only the approval requests waiting on the user |
include |
array of strings | No | approvals, flagged and stale |
Any of approvals, flagged and stale |
Stale pages need access to the wiki's analytics. Without it, the list is empty and staleUnavailable is true.
Returns: approvals (request id, page, status, step, who asked and when, URL), flagged (page, reason, when, URL) and stale (page, last updated, URL), each with a …Truncated flag.
Example: "What's waiting for my approval in the Policies wiki?"
wikis_review_action¶
Acts on a page's review or approval:
action |
What it does | Needs |
|---|---|---|
submit |
Submits the page's latest changes for approval | Optional note |
approve |
Approves an open approval request | Optional comment |
request_changes |
Asks for changes on an open approval request | comment |
cancel |
Cancels the user's own approval request | |
verify |
Marks the page as verified and up to date | |
flag |
Flags the page for review | reason |
dismiss_flag |
Removes the flag | |
publish |
Publishes the latest version to every reader of the page (wiki owners). This tool can't undo it | Optional note |
Overwrite · Needs: Wikis
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
| page | Yes | See Naming a wiki or a page | ||
action |
string | Yes | One of the actions above | |
note |
string | No | For submit and publish, 1 to 280 characters |
|
comment |
string | No | For approve and request_changes, 1 to 2,000 characters |
|
requestId |
id | No | The page's open request | The approval request to act on |
reason |
string | No | For flag, 1 to 280 characters |
When the workflow refuses an action, the assistant gets the reason, for example sole_approver (the user is the only approver, so they can't submit to themselves) or nothing_to_approve.
Returns: the action, url, and its outcome: requestId, status and step for approvals, flagged for verify and flag, or publishedSequence for publish.
Example: "Approve the pending changes on the Travel Policy page."