Knowledge base
Spaces and pages of the knowledge base: read, search, write, move and delete them.
All paths are under https://your-workspace.albaticket.com/api/v1. A program reads and writes the knowledge base as the member whose token it holds: a space it may not read does not exist for it, a page behind a view restriction is 404 like one that was never written, and a change needs write access to the space and passes the page's edit restrictions. A read-only token reads. Every change is a new version of the page, with the agent's name in its history beside the member's.
Spaces are named by key (HANDBOOK, or a project's key for its space) and pages by slug, the last part of their address (release-process), or by id.
Spaces
GET /knowledge/spaces
The spaces the member may read, each with can_edit and can_manage.
{"spaces": [{"key": "HANDBOOK", "name": "Handbook", "kind": "global", "project": null, "source": "native", "home_page": "welcome", "can_edit": true, "can_manage": false}]}
GET /knowledge/spaces/{space}/tree
The space's current pages and folders in the tree's order, each with its parent (a slug, null at the top) and depth. Drafts, blog posts and deleted pages are not in the tree.
Pages
GET /knowledge/spaces/{space}/pages/{page}
One page. body is as stored, with its format (markdown, or confluence_storage, html or plain for an imported page), and is never converted here; text is the page's words whatever the format. parent and path place it in the tree; backlinks are the pages linking to it and tickets those it mentions that the member may see. version is the page's current version.
GET /knowledge/search
| Argument | |
|---|---|
query |
The words, required |
space |
A space's key, to keep to one |
limit |
Up to 100, 20 by default |
Pages the member may read that match, best first, each with the passage it matched in.
POST /knowledge/spaces/{space}/pages
Writes a page. title is required; body is Markdown. kind is page (the default), folder (no body) or blog_post (outside the tree); parent is a page's slug or id; draft: true keeps it to its author and those who manage the space; published: true lets customers read it where the space allows; message is a note for its history. Answers 201 with the page.
{"title": "Release process", "body": "## Steps\n\n1. Tag the build\n2. Ship it", "parent": "runbooks", "message": "First draft"}
PATCH /knowledge/spaces/{space}/pages/{page}
Changes any of title, body, published, draft (false publishes a draft), with a message. A body replaces the page's body with Markdown whatever its format was; the version before keeps the original. Give version, the one you read, and the change is refused with 409 stale when somebody has saved since, rather than written over their version. A page of a space kept in a Git repository is its file's: a change to anything but published is refused with 422 git_space, and so are writing, moving and deleting pages in that space. A space's source says git for such a space.
POST /knowledge/spaces/{space}/pages/{page}/move
Moves a page or folder: parent (a slug or id, null for the top of the space) and before or after one of its new siblings, or neither for the end. A page cannot go under itself or a page below it (422 cycle), and a blog post has no place in the tree.
DELETE /knowledge/spaces/{space}/pages/{page}
Deletes the page and the pages under it from the space. Those who manage the space can restore them from its trash; nothing is lost.