Confluence offers a powerful feature called labels, which can help you categorize and organize pages with ease. Whether you’re managing a roadmap, project plan, or knowledge base, labels provide a way to add context and structure to your content. In this post, we’ll walk through how to add and manage labels in Confluence, including a look at how to work with them using the REST API.
What Are Labels in Confluence?
Labels are essentially tags that you can add to your Confluence pages to categorize and organize them. They make it easier to filter, search, and perform advanced tasks like creating dynamic content lists or automating processes through integrations.
For example, if you’re working on a roadmap page, you could use labels like roadmap, project-plan, or 2025-strategy. Labels can also be used programmatically to fetch or update content via Confluence’s API, enabling developers to build advanced solutions.
Adding Labels in Confluence (Manually)
To add a label to a page in Confluence:
- Open the page you want to label.
- Scroll to the bottom of the page.
- Click the “Add Label” option.
- Enter your desired label name (e.g.,
roadmap,2025-plan) and click Add.
Remember that labels in Confluence don’t support spaces, so use hyphens (-) to separate words instead.
Working with Labels Using the REST API
For more advanced scenarios, you can use Confluence’s REST API to fetch, add, or update labels. Below are step-by-step instructions for fetching and adding labels programmatically.
Fetching Existing Labels
To fetch existing labels for a page, use the following API endpoint:
<your-confluence-url>/wiki/rest/api/content/<content-id>/label
Here’s how you can do it using curl:
curl -u <username>:<password> -X GET "<your-confluence-url>/wiki/rest/api/content/<content-id>/label"
You’ll get a JSON response that lists the labels, including their types (global, my, team) and names. For better readability, you can pipe the output through a tool like jq:
curl -u <username>:<password> -X GET "<your-confluence-url>/wiki/rest/api/content/<content-id>/label" | jq
Adding a New Label
To add a label to a page, you’ll need to use a POST request to the same endpoint. Here’s the endpoint format:
<your-confluence-url>/wiki/rest/api/content/<content-id>/label
Below is an example of a JSON body for adding a label:
[
{
"prefix": "global",
"name": "demo-label"
}
]
Here’s how you can send the request:
curl -u <username>:<password> -X POST -H "Content-Type: application/json" \
-d '[{"prefix": "global", "name": "demo-label"}]' \
"<your-confluence-url>/wiki/rest/api/content/<content-id>/label"
Once the request is successful, the label will be added to the page.
Use Case: Synchronizing Confluence and Jira Labels
One interesting use case for labels is synchronizing them between Confluence pages and Jira issues. While this is not a built-in feature, you could use the APIs of both platforms to achieve this. By fetching labels from Confluence and Jira, you could create a script to ensure consistency across both tools.
Conclusion
Labels are an underrated but powerful feature in Confluence that can simplify page management and categorization. By combining manual label management with the REST API, you can unlock advanced capabilities that make your content even more dynamic and actionable.
Whether you’re a Confluence admin, content creator, or developer, mastering labels will make your workflow smoother and more efficient.
Let me know if this resonates or if you'd like further tweaks!