Confluence tools for agents

Nineteen tools let an agent work directly against Confluence Cloud: discover spaces, search and read pages, create content, and edit pages in place. They are separate from the Confluence pipeline source, which ingests Confluence pages into a corpus — these tools act in Confluence at conversation time.

These tools target Confluence Cloud (*.atlassian.net) and use the Confluence Cloud REST API v2. Confluence Data Center and Server use a different API and are not supported here. The pipeline source, by contrast, works against both Cloud and Data Center.

Tool names carry a version suffix

Every tool name ends in a date suffix, and the suffix is part of the identifier you configure. The bare family name (confluence_fetch) is the tool's lineage, not its name, and does not resolve to a tool — lookup is exact-match.

The suffixes are not uniform across the family. Four different dates are in use:

Suffix	Tools
_20260622	confluence_fetch_20260622
_20260703	confluence_get_attachment_20260703
_20260714	confluence_search_20260714, confluence_get_page_20260714, confluence_create_page_20260714, confluence_create_blog_post_20260714, confluence_update_page_20260714, confluence_append_to_page_20260714, confluence_insert_after_heading_20260714, confluence_replace_section_20260714, confluence_add_comment_20260714, confluence_add_label_20260714
_20260722	confluence_list_spaces_20260722, confluence_get_space_20260722, confluence_space_page_tree_20260722, confluence_replace_text_20260722, confluence_edit_table_20260722, confluence_insert_image_20260722, confluence_delete_content_20260722

Authentication

Every Confluence tool takes the same three credential arguments, which the agent never sees: confluence_base_url, confluence_username, and confluence_api_token. Together they authenticate to Confluence with HTTP basic authentication — the Atlassian account email as the user and the API token as the password.

You do not have to write the wiring yourself. All nineteen tools ship the same default argument_override, which reads each credential from a fixed location on the agent — the base URL and username from metadata, since they are not sensitive, and the API token from an agent secret, so it is encrypted at rest and masked on read:

{
  "argument_override": {
    "confluence_base_url": { "$ref": "agent.metadata.confluence_base_url" },
    "confluence_username": { "$ref": "agent.metadata.confluence_username" },
    "confluence_api_token": { "$ref": "agent.secrets.confluence_api_token" }
  }
}

Store the token under exactly that secret name and put the other two in agent metadata, and the tools resolve on their own once attached — no per-tool configuration needed:

curl -X PUT https://api.vectara.io/v2/agents/<agent_key>/secrets \
  -H "x-api-key: $VECTARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"secrets": {"confluence_api_token": "your-token"}}'

{
  "metadata": {
    "confluence_base_url": "https://company.atlassian.net/wiki",
    "confluence_username": "user@company.com"
  }
}

Confluence Cloud uses the same Atlassian API token as Jira. Generate one at id.atlassian.com/manage-profile/security/api-tokens.

All three references must resolve, and none of them carries a fallback value. If any one is missing, the session fails to start with Failed to resolve eager references rather than failing later on the individual tool call.

Override the defaults only if your credentials live somewhere else — a session secret holding a per-caller token, for instance. Setting argument_override on the tool replaces the defaults wholesale, not key by key: an override that names only confluence_base_url drops the username and token wiring along with it. Restate every credential argument you still need.

Confluence enforces its own permissions on the acting user. A write the account is not entitled to make — creating a page in a space where it lacks the permission to add pages, for example — is rejected by Confluence with a 403.

Markdown in, markdown out

Confluence stores page bodies in its own storage format, not markdown. The tools translate in both directions so the agent works in markdown throughout.

Reads convert the storage-format body to markdown, preserving headings, bold, italic, code blocks, and links. Writes convert markdown back to storage format. Fenced code blocks become Confluence code macros, carrying the language when the fence declares one, and GitHub-style callout blockquotes — > [!INFO], > [!NOTE], > [!WARNING], > [!TIP] — become the corresponding Confluence panel macros. Tables are supported in both directions.

How page edits are versioned

Confluence updates are version-based: a write reads the page's current version and submits the next one. The tools handle this for you and return the new version number.

When the page changed between the read and the write, Confluence rejects the write with a conflict. What happens next depends on the tool, and the split follows what the edit does to the body.

The fine-grained editors — confluence_append_to_page_20260714, confluence_replace_section_20260714, confluence_insert_after_heading_20260714, confluence_replace_text_20260722, confluence_edit_table_20260722, confluence_insert_image_20260722, and confluence_delete_content_20260722 — merge into the body they read. They re-read the page and re-apply the change once, so your edit lands on top of the concurrent one and both survive.

confluence_update_page_20260714 replaces the whole body, so re-applying it would overwrite whatever the other writer just saved. It does not retry: the conflict surfaces as an error saying the page was modified concurrently. Re-read with confluence_get_page_20260714, rebuild the body from what is now there, and write again.

Discovering spaces and content

confluence_list_spaces_20260722

Finds spaces by free-text name, by type, or by status. query is an optional free-text search over space names. type is global, personal, collaboration, or knowledge_base, and status is current (the default) or archived. limit defaults to 25.

The filters behave differently depending on whether you search. Without a query, spaces are listed and both type and status apply. With a query, spaces are matched by name, status is not applied at all, and type filtering is best-effort. Each result carries the space's key, name, type, status, and url.

confluence_get_space_20260722

Returns one space's details: id, key, name, type, status, description (converted to markdown), homepage_id, homepage_title, and url. Identify the space by space_key (preferred) or space_id.

confluence_space_page_tree_20260722

Lists a space's pages as a lightweight hierarchy for navigation, without any page bodies. Identify the space by space_key (preferred) or space_id; limit defaults to 200.

Returns a flat list of {id, title, parent_id} — reconstruct the tree from parent_id, which is absent on top-level pages — plus a truncated flag when the space holds more pages than limit.

confluence_search_20260714

The primary discovery tool: to act on "the Q3 planning page", search for it first to get its id. query is free text matched against page and blog text and titles, narrowed optionally by space (a space key) and type (page or blogpost). limit defaults to 25.

Alternatively, pass a raw CQL expression as cql, such as text ~ "roadmap" AND space = "MKT" AND type = page. When cql is set it is used verbatim and query, space, and type are ignored.

Each hit carries id, title, type, space_key, url, and a short excerpt with search-term context. Use the returned id with confluence_get_page_20260714, confluence_update_page_20260714, confluence_add_label_20260714, or confluence_add_comment_20260714.

Reading pages and attachments

confluence_get_page_20260714

Fetches a single page. Identify it by page_id, or, when you don't have the id, by space plus the exact title — the tool then locates the page by CQL search.

Returns id, title, space_key, version, body as markdown, labels, attachments (filenames only), and url. The version is what you use to reason about an update. An attachment filename from this list is what you pass as the attachment parameter to confluence_insert_image_20260722.

confluence_fetch_20260622

Fetches many pages from a space at once. space_key is required. status selects which pages to fetch — current (published, the default), archived, draft, or trashed — and max_results caps how many are returned, defaulting to 50.

Three flags control the per-page enrichment: include_comments (default true) fetches footer comments, include_attachments (default true) fetches attachment metadata, and include_labels (default false) fetches labels. Each enabled flag costs one extra API call per page, so raising max_results with all three on raises latency proportionally.

Each page carries id, title, space_key, space_name, status, body as markdown, version, updated, author (the last author's display name), labels, comments in Author: text form, url, and attachments. Attachment entries are metadata only — id, filename, media_type, file_size, and download_url — never the file bytes.

Because the full response can be large, this tool ships with a default output_transform that reduces each page to its id, title, space key, version, and attachment count. Override it with your own jq expression when the agent needs more; for example, .pages | map({id, title, url}) for a summary view or .pages | map({id, title, body: .body[0:200]}) for truncated bodies.

confluence_get_attachment_20260703

Downloads one attachment's bytes into a session artifact. Pass the download_url from a confluence_fetch_20260622 attachment entry, and optionally a filename to record for the stored artifact — it defaults to attachment. The bytes are only fetched when this tool is called, so large binaries are never pulled up front.

The download URL must be on the same host as confluence_base_url; off-host URLs are refused.

Returns artifact_id plus the attachment's filename, mime_type, and size_bytes. The artifact_id is the handle to the content: pass it to image_read to view an image, to the artifact tools to read or grep a text-like file, or to a *_to_core_document tool to index a document.

Creating content

confluence_create_page_20260714

Creates a page. space (a space key), title, and body in markdown are required. parent_id nests the new page under an existing one, and status is current (published, the default) or draft.

Returns the new page's id, title, version, and url.

confluence_create_blog_post_20260714

Publishes a blog post. space, title, and body in markdown are required, and status is current (the default) or draft. Returns the new post's id, title, version, and url.

Rewriting a page or a section

These tools replace a whole page or a whole section. When the change you want is narrower — fix a word, edit a cell, add or remove an image — prefer the in-place tools in the next section, which change only what you target and leave everything else untouched.

confluence_update_page_20260714

Updates a page's title, body, or both. page_id is required; whichever of title and body you omit is preserved. The body is markdown and replaces the entire page body.

Returns the page's id, title, new version, and url. This is the one editing tool that does not retry on a concurrent-edit conflict: because it replaces the body wholesale, a retry would discard the other writer's change, so the conflict is surfaced to you instead. See How page edits are versioned.

confluence_replace_section_20260714

Replaces everything under a named heading, up to the next same-or-higher-level heading. The heading itself is kept. page_id, heading, and content (markdown) are required. The heading is matched case- and whitespace-insensitively; when it isn't found, the error lists the page's headings.

confluence_append_to_page_20260714

Adds markdown content to an existing page without rewriting it. position is end (the default) or start. page_id and content are required.

confluence_insert_after_heading_20260714

Inserts markdown content directly under a named heading, leaving the rest of the page alone. page_id, heading, and content are required. The heading is matched case- and whitespace-insensitively; when it isn't found, the error lists the page's headings.

Editing a page in place

These tools change only what you target and preserve all other content, formatting, images, and macros. Each returns the page's id, title, new version, and url.

confluence_replace_text_20260722

Replaces a specific run of visible text — to fix a typo, reword a phrase, delete it, bold or italicize it, or turn it into a hyperlink. page_id, find, and replace are required.

find is literal visible text and must be specific enough to be unambiguous. replace is markdown rendered inline, so **API** bolds and [API](url) links; an empty string deletes the found text. section scopes the search to one heading's body, and occurrence is first (the default) or all.

Matching happens within a single text run. If the target text spans existing formatting, scope the find more narrowly.

confluence_edit_table_20260722

Changes an existing table without re-authoring it. page_id and operation are required, where operation is add_row, delete_row, add_column, delete_column, or set_cell.

Locate the table with the optional section (a heading whose section holds it) and table_index, the 0-based index among matches, defaulting to 0.

row_index and column_index are 0-based. For add_row and add_column, the index inserts before that position, and omitting it appends. delete_row and delete_column require their index, and set_cell requires both.

Cell content is markdown rendered inline. add_row and add_column take values — one per column, or one per row top to bottom — while set_cell takes a single value. Set header to true to add a header cell (th) rather than a data cell (td); it defaults to false.

confluence_insert_image_20260722

Inserts an image, from exactly one of three sources. url embeds an image hosted at an external URL without uploading it. fetch_url downloads the image and uploads it as a page attachment first, so it stays durable even if the source URL later disappears. attachment embeds an image already attached to the page, by filename — the filenames come from confluence_get_page_20260714.

page_id is required. Place the image with after_heading (matched case- and whitespace-insensitively), or, when that is omitted, with position: end (the default) or start. alt sets alt text and width sets a display width in pixels.

confluence_delete_content_20260722

Removes something within a page, leaving the page itself and all other content intact. This does not delete the page.

page_id is required, along with exactly one target. section names a heading and deletes it along with its body up to the next same-or-higher heading. block_containing_text deletes the block element — paragraph, list, table — whose text contains that string. image deletes the image whose alt text or attachment filename matches, or the first image on the page when left empty.

When the target isn't found, the edit fails with a message saying so.

Commenting and labeling

confluence_add_comment_20260714

Posts a footer comment on a page. page_id and body (markdown) are required. Pass an existing comment's id as reply_to to thread the new comment under it. Returns the new comment's id and url.

confluence_add_label_20260714

Adds one or more labels to a page. page_id and labels, an array of label names, are required. Each label is added with the global prefix. Returns the page's full label set after the add.

If you only have a page title, find its id first with confluence_search_20260714.