Manage Tags

/api/external/tag

info

This API requires authentication with an API key from your organization. See our API Authentication article for more details.

---

The tags API allows for fetching, creating, and updating your organization's tags.

List All Tags

Retrieve a list of all tags.

GET https://your-organization.revision.app/api/external/tag

This 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-organization.revision.app/api/external/tag/{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-organization.revision.app/api/external/tag

Example 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-organization.revision.app/api/external/tag/{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-organization.revision.app/api/external/tag/upsert-batch

Example 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.

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".

---

Examples

Creating a new tag

curl -X POST https://your-organization.revision.app/api/external/tag \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer a0e08cad-184b-48a4-miku-14776a549b79" \
  -d '{
    "name": "Production Ready",
    "desc": "Components that are ready for production deployment",
    "color": "green"
  }'

Getting a tag by ID

curl -X GET https://your-organization.revision.app/api/external/tag/ZxuuNkpG9I31 \
  -H "Authorization: Bearer a0e08cad-184b-48a4-miku-14776a549b79"

Updating an existing tag

curl -X PATCH https://your-organization.revision.app/api/external/tag/ZxuuNkpG9I31 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer a0e08cad-184b-48a4-miku-14776a549b79" \
  -d '{
    "name": "Production Ready",
    "desc": "Updated description for production components",
    "color": "blue"
  }'

Upserting batch tags

curl -X PATCH https://your-organization.revision.app/api/external/tag/upsert-batch \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer a0e08cad-184b-48a4-miku-14776a549b79" \
  -d '[
    {
      "name": "Infrastructure",
      "desc": "Core infrastructure components",
      "color": "blue"
    },
    {
      "id": "ZxuuNkpG9I31",
      "name": "Updated Tag",
      "color": "purple"
    }
  ]'