I want to bulk replace normal text across a space with a Insert Excerpt macro

[Sonal Kumar]

I want to bulk-replace normal text across a space with an Insert Excerpt macro where the excerpt is defined on a common page. I am using Confluence Cloud and tried doing it via API but it didn't work. It adds the insert excerpt macro in the destination page but the value of the excerpt is missing. It throws the error  - Error loading excerpt from "".

Is there a way to achieve this? I have to update around 1000 pages.

[Stavros_Rougas_EasyApps]

@Sonal Kumar this isn't exactly what you are trying to do and it uses an app. Maybe not for the current problem but I suspect you might have similar needs now and then.

A feature of Space Content Manager is bulk find and replace. Has a free trial.

[Andrii Maliuta]

Hello @Sonal Kumar ,

It is possible to do this via REST API - if you have such an error, then most probably, you used some incorrect data for text replacement. Could you please provide more details on what text you inserted and what type you selected for data rendering () ?

you van try to use existing libraries that are already implemented to perform actions on Confluence like https://github.com/orgs/Sumy-Coding/repositories or https://atlassian-python-api.readthedocs.io/.

The main approach would be:

1. Get pages via CQL search or via /space/content
2. Get each page body text
3. replace text with macro markup (Excerpt Include) - https://confluence.atlassian.com/doc/confluence-storage-format-790796544.html

[Sonal Kumar]

hi @Andrii Maliuta 

Thanks for sharing the info. I will have a look. In the meantime, I am sharing the Python script that I am using to achieve the above bulk find and replace

import requests
import json
import base64

# === CONFIGURE YOUR CONFLUENCE DETAILS ===
BASE_URL = "Comp URL" #
USERNAME = "abc" #
API_TOKEN = "APIToken" # Replace with your API token

PARENT_PAGE_ID = "1112943554" # Replace with your actual Parent Page ID

# Source page details
SOURCE_PAGE_ID = "1121544444"
EXCERPT_NAME = "abcxyz"

# Text to replace
OLD_TEXT = "qwerty" # The text you want to replace
NEW_TEXT = f"""
<p>Placeholder Text: Refreshing Excerpt...</p>
<ac:structured-macro ac:name="excerpt-include">
<ac:parameter ac:name="name">{EXCERPT_NAME}</ac:parameter>
<ac:parameter ac:name="page">{SOURCE_PAGE_ID}</ac:parameter>
</ac:structured-macro>
"""
# Encode authentication credentials
auth_string = f"{USERNAME}:{API_TOKEN}"
auth_encoded = base64.b64encode(auth_string.encode("utf-8")).decode("utf-8")

HEADERS = {
"Authorization": f"Basic {auth_encoded}",
"Content-Type": "application/json"
}

def get_child_pages(parent_id):
"""Fetch all child pages of a given parent page."""
url = f"{BASE_URL}/rest/api/content/{parent_id}/child/page?expand=body.storage,version"
response = requests.get(url, headers=HEADERS)

if response.status_code == 200:
pages = response.json().get("results", [])
return [
{"id": page["id"], "title": page["title"], "content": page["body"]["storage"]["value"], "version": page["version"]["number"]}
for page in pages
]
else:
print(f"Error fetching child pages: {response.text}")
return []

def update_page(page_id, title, new_content, version):
"""Update a Confluence page with modified content."""
url = f"{BASE_URL}/rest/api/content/{page_id}"

payload = {
"id": page_id,
"type": "page",
"title": title,
"version": {"number": version + 1},
"body": {"storage": {"value": new_content, "representation": "storage"}}
}

response = requests.put(url, headers=HEADERS, data=json.dumps(payload))
if response.status_code == 200:
print(f"✅ Updated page: {title}")
else:
print(f"❌ Error updating page {title}: {response.text}")

def replace_text_in_child_pages():
"""Find and replace text in all child pages of the parent page."""
child_pages = get_child_pages(PARENT_PAGE_ID)

if not child_pages:
print("No child pages found.")
return

for page in child_pages:
page_id, title, content, version = page["id"], page["title"], page["content"], page["version"]

if OLD_TEXT in content:
new_content = content.replace(OLD_TEXT, NEW_TEXT)
update_page(page_id, title, new_content, version)
else:
print(f"🔍 No changes needed for page: {title}")

if __name__ == "__main__":
replace_text_in_child_pages()

All the information about the source page and macro name are all correct. When I manually insert the macro it works but the code doesn't seem to work. I will really appriciate If you can help me understand what I am doing wrong.

Thanks...