Spaces Tools¶
The spaces_* tools find, read, join, star, create and delete spaces.
All six tools are in the spaces tool group and need Huddo Spaces.
Tools that act on one space take its slug or its url. Give one of them.
spaces_find¶
Finds the spaces the user can read, by name, tags, starred or owned.
Read-only · Needs: Spaces
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
query |
string | No | Words to match, up to 200 characters | |
tags |
array of strings | No | Tags to filter by | |
sort |
string | No | name, updated, visited or trending |
|
starredOnly |
boolean | No | false | Only the spaces the user has starred |
ownedOnly |
boolean | No | false | Only the spaces the user owns |
includeArchived |
boolean | No | false | Include archived spaces |
limit |
integer | No | 20 | 1 to 50 |
offset |
integer | No | 0 | Spaces to skip, to read the next page |
Returns: spaces, each with id, slug, name, a short description, tags, archived, starred, latestActivity, contentCounts (wikis, boards, labs and whiteboards) and url; and total, the number that match.
Example: "Which spaces have I starred?"
spaces_get_space¶
A space in full: its about text, the user's relationship to it (member, reader or visitor), what they're allowed to do in it, and member counts. More detail can be added with include.
Read-only · Needs: Spaces (wikis, whiteboards, activity and pulse need Wikis; labs need Ideas)
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
slug |
string | No | The space's slug | |
url |
URL | No | Instead of slug: the space's URL |
|
include |
array of strings | No | wikis |
Any of members, wikis, labs, whiteboards, activity and pulse |
activityLimit |
integer | No | 10 | 1 to 20. The number of recent page changes, with activity |
members: the first 20 members, with their roles.wikis: the first 10 wikis, with page counts.labs: the space's idea labs, with idea counts.whiteboards: recent whiteboards.activity: recent page changes in the wikis the user can read.pulse: views, edits and unique viewers over the last 30 days, when activity tracking is on in the organisation.
Returns: id, slug, name, description, about (as Markdown), tags, archived and url; viewer, the user's access and what they can do (join, request to join, contribute, add content, edit, manage access); members (counts, and with members, the list); the parts asked for in include; and unavailable, any part that couldn't be read.
Example: "Tell me about the Engineering space and who's in it."
spaces_join¶
Joins a space for the user. An open space is joined straight away. In a moderated space, a join request is sent to the space's owners, who must approve it.
Write · Needs: Spaces
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
slug |
string | No | The space's slug | |
url |
URL | No | Instead of slug: the space's URL |
|
message |
string | No | A message to the owners with a join request, up to 1,000 characters |
Returns: outcome: joined, requested, alreadyMember, notAllowed or archived.
Example: "Join the Design Guild space."
spaces_star¶
Stars or unstars a space, so it shows in the user's favourites.
Write · Needs: Spaces
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
slug |
string | No | The space's slug | |
url |
URL | No | Instead of slug: the space's URL |
|
starred |
boolean | Yes | true to star, false to unstar |
Returns: starred, and starredCount, the number of spaces the user has starred.
Example: "Star the Product space for me."
spaces_create_space¶
Creates a space. The user becomes its owner. A private space is for members only; an org space is open to the whole organisation, who can find, read and join it. Everything else (theme, tags, layout) starts with the defaults and can be changed in the space's settings.
Write · Needs: Spaces
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
name |
string | Yes | 1 to 120 characters | |
description |
string | No | Up to 2,000 characters | |
visibility |
string | No | private |
private or org |
Returns: slug, name, groupId, url, visibility and next, what to tell the user. Pass groupId to wikis_create_wiki or ideas_create_lab to create a wiki or lab in the space.
Example: "Create a private space called Project Falcon with a wiki for meeting notes."
spaces_delete_space¶
Permanently deletes a space, with its members and access list, join requests, about text, images and feed comments. Only a space owner or an organisation admin can delete a space.
The space's wikis aren't deleted: they keep every page, but are no longer in a space and lose the access the space gave them. Its idea labs aren't deleted either, but lose the access they had through the space.
Delete · Needs: Spaces
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
slug |
string | No | The space's slug | |
url |
URL | No | Instead of slug: the space's URL |
|
confirmName |
string | Yes | The space's exact name. A name that doesn't match is refused |
Returns: deleted, slug, name, wikisDetached and labsOrphaned, the numbers of wikis and labs that were in the space.
Example: "Delete the Test Space I created earlier."