Manage Tags
/api/external/tags, api/external/tags/:id
Info
This API requires authentication with an API key. See our API Authentication article for more details.
The tags API allows for fetching, creating, and updating a workspace's tags.
List All Tags
Retrieve a list of all tags.
GET https://your-workspace.revision.app/api/external/tagsThis returns a JSON response with an array of all of your tags, following this example structure:
[
{
"id": "ZxuuNkpG9I31",
"name": "Demo Tag",
"desc": "With a really cool description",
"color": "purple"
},
{
"id": "zEnyt0WpKkkm",
"name": "Other Demo Tag",
"desc": null,
"color": "green",
"apiContext": "2026-01-01 01:01:01"
}
]Get Tag
Retrieve a specific tag by ID.
GET https://your-workspace.revision.app/api/external/tags/{id}This returns a JSON response with the tag:
{
"id": "ZxuuNkpG9I31",
"name": "Demo Tag",
"desc": "With a really cool description",
"color": "purple"
}Create Tag
Create a new tag.
POST https://your-workspace.revision.app/api/external/tagsExample of creating a new tag:
{
"name": "Production Ready",
"desc": "Components that are ready for production deployment",
"color": "green"
}Update Tag
Update an existing tag.
PATCH https://your-workspace.revision.app/api/external/tags/{id}Example of updating an existing tag:
{
"name": "Production Ready",
"desc": "Updated description for production components",
"color": "blue"
}Partial Updates
When updating, you only need to send the fields you want to change. Omitted fields remain unchanged. Set a field to null to clear its value.
Upsert Batch Tags
Create or update multiple tags in a single batch operation.
PATCH https://your-workspace.revision.app/api/external/tags/upsert-batchExample of upserting multiple tags:
[
{
"name": "Infrastructure",
"desc": "Core infrastructure components",
"color": "blue"
},
{
"id": "ZxuuNkpG9I31",
"name": "Updated Tag Name",
"desc": "Now with a description!",
"color": "purple"
},
{
"name": "External",
"desc": "External services and dependencies",
"color": "orange"
}
]Tip
In batch operations, include an id to update an existing tag, or omit it to create a new one.
Delete Tag
Not Implemented
This endpoint is not yet implemented and will return a 501 status code.
DELETE https://your-organization.revision.app/api/external/tags/{id}Data Types
| Value | Description |
|---|---|
id?: string | System-generated ID. Use this to update existing tags. |
name: string | The tag's name. |
desc?: string | Optional description of the tag. |
color: string | Tag color: "gray", "red", "orange", "yellow", "green", "blue", or "purple". |
apiContext?: string | Optional tracking field. Defaults to current timestamp. |
Examples
Creating a new tag
curl -X POST https://your-workspace.revision.app/api/external/tags \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-api-key-here" \
-d '{
"name": "Production Ready",
"desc": "Components that are ready for production deployment",
"color": "green"
}'Getting a tag by ID
curl -X GET https://your-workspace.revision.app/api/external/tags/ZxuuNkpG9I31 \
-H "Authorization: Bearer a0e08cad-184b-48a4-miku-14776a549b79"Updating an existing tag
curl -X PATCH https://your-workspace.revision.app/api/external/tags/ZxuuNkpG9I31 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-api-key-here" \
-d '{
"name": "Production Ready",
"desc": "Updated description for production components",
"color": "blue"
}'Upserting batch tags
curl -X PATCH https://your-workspace.revision.app/api/external/tags/upsert-batch \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-api-key-here" \
-d '[
{
"name": "Infrastructure",
"desc": "Core infrastructure components",
"color": "blue"
},
{
"id": "ZxuuNkpG9I31",
"name": "Updated Tag",
"color": "purple"
}
]'Manage Attributes
API reference for managing attributes in Revision. Learn to create, update, and configure custom metadata fields for your architecture components.
Manage Types
API reference for retrieving component types in Revision. Learn to access the catalog of available component types for your architecture.