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.

Getting all tags

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

This returns a JSON response with an array of all of your attributes, 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"
  }
]

Creating tags

Create new tags using the POST endpoint without providing an id field.

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

Example of creating a new tag:

[
  {
    "name": "New example tag",
    "color": "red"
  }
]

Example of creating multiple tags:

[
  {
    "name": "Infrastructure",
    "desc": "Core infrastructure components",
    "color": "blue"
  },
  {
    "name": "External",
    "desc": "External services and dependencies", 
    "color": "orange"
  }
]

Updating tags

Update existing tags using the POST endpoint with the tag's id field.

Create vs Update

Learn about Create vs Update to understand how to identify resources for create and update operations.

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

Example of updating an existing tag:

[
  {
    "id": "ZxuuNkpG9I31",
    "name": "Updated Tag Name",
    "desc": "Now with a description!",
    "color": "purple"
  }
]

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"
    }
  ]'

Updating an existing 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 '[
    {
      "id": "ZxuuNkpG9I31",
      "name": "Production Ready",
      "desc": "Updated description for production components",
      "color": "blue"
    }
  ]'