---
updatedAt: 2026-05-19T17:58:37.000Z
agentTools:
  projectIndex: https://docs.vizionapi.com/llms.txt
---

# Update tag

Update a tag's name.

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Endpoints",
    "description": "Real-Time Container Tracking API",
    "version": "1.12.20",
    "contact": {
      "name": "API Support",
      "email": "support@vizionapi.com"
    }
  },
  "servers": [
    {
      "url": "https://demo.vizionapi.com",
      "description": "Vizion API Demo API"
    },
    {
      "url": "https://prod.vizionapi.com",
      "description": "Vizion API Production API"
    }
  ],
  "components": {
    "securitySchemes": {
      "apikeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Account API Key"
      }
    }
  },
  "security": [
    {
      "apikeyAuth": []
    }
  ],
  "paths": {
    "/references": {
      "get": {
        "tags": [
          "References"
        ],
        "summary": "List active references",
        "description": "List all `active` references, sorted by creation date (newest first).",
        "operationId": "reference_list",
        "parameters": [
          {
            "name": "include_metadata",
            "description": "Include pagination metadata in response. See [pagination](ref:pagination).",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false,
              "example": true
            }
          },
          {
            "$ref": "#/paths/~1tags/get/parameters/0"
          },
          {
            "$ref": "#/paths/~1tags/get/parameters/1"
          },
          {
            "in": "query",
            "name": "active",
            "schema": {
              "type": "boolean",
              "description": "Filter on `active`",
              "default": true,
              "example": false
            }
          },
          {
            "in": "query",
            "name": "container_id",
            "schema": {
              "$ref": "#/paths/~1references/post/requestBody/content/application~1json/schema/oneOf/0/properties/container_id",
              "description": "Filter on `container_id`"
            }
          },
          {
            "in": "query",
            "name": "bill_of_lading",
            "schema": {
              "$ref": "#/paths/~1references/post/requestBody/content/application~1json/schema/oneOf/1/properties/bill_of_lading",
              "description": "Filter on `bill_of_lading`"
            }
          },
          {
            "in": "query",
            "name": "booking_number",
            "schema": {
              "$ref": "#/paths/~1references/post/requestBody/content/application~1json/schema/oneOf/2/properties/booking_number",
              "description": "Filter on `booking_number`"
            }
          },
          {
            "in": "query",
            "name": "callback_urls",
            "style": "form",
            "explode": true,
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "description": "URL to receive [webhook](ref:webhooks) based updates from Vizions API.",
                "example": "https://www.yourdomain.com"
              },
              "minItems": 1,
              "maxItems": 5,
              "description": "Filter on `callback_url`. Repeat the parameter to filter on more than one (`?callback_urls=https://www.foobar.com&callback_urls=https://www.bizzbazz.com`).",
              "example": [
                "https://www.foobar.com",
                "https://www.bizzbazz.com"
              ]
            }
          },
          {
            "in": "query",
            "name": "carrier_code",
            "schema": {
              "$ref": "#/paths/~1references/post/requestBody/content/application~1json/schema/oneOf/0/properties/carrier_code",
              "description": "Filter on `carrier_code`"
            }
          },
          {
            "in": "query",
            "name": "last_update_status",
            "schema": {
              "$ref": "#/paths/~1references~1{referenceId}/get/responses/200/content/application~1json/schema/properties/last_update_status",
              "description": "Filter on `last_update_status`"
            }
          },
          {
            "in": "query",
            "name": "deactivate_reason",
            "style": "form",
            "explode": true,
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "description": "Specifies the reason a reference was deactivated.\n\n - `carrier_not_found`: Used when an ACI reference is deactivated because the carrier could not be identified.\n - `data_not_found`: Used when an ACI reference is deactivated because no carrier returned matching data for the shipment identifier.\n - `newer_data_found_on_another_carrier`: Used when an ACI reference is deactivated because a different carrier reported more recent data for the same shipment identifier.\n - `auto_unsubscribed`: Generic reason for auto-unsubscribe behavior.\n - `container_removed_from_bol`: Used for child references when the container is no longer found on the parent bill of lading.\n - `customer_unsubscribed`: Used when the customer manually unsubscribes from the reference.\n - `exceeded_extraction_attempt_threshold`: Used when the maximum number of extraction attempts has been reached without success.\n - `inferred_shipment_completion`: Used to indicate that based on similar journeys, the reference is not expected to yield any new events.\n - `internal_operations`: Used when the reference is deactivated by vizion for internal operations.\n - `invalid_container`: Used when the carrier reports that the specified identifier is not a valid container.\n - `invalid_bill_of_lading`: Used when the carrier reports that the specified identifier is not a valid bill of lading.\n - `invalid_booking_number`: Used when the carrier reports that the specified identifier is not a valid booking number.\n - `shipment_completed`: Used when we detect that the shipment has been completed and no further updates are expected.\n - `too_long_without_updates`: Used when a reference has gone too long without any new updates and is automatically deactivated.",
                "enum": [
                  "carrier_not_found",
                  "data_not_found",
                  "newer_data_found_on_another_carrier",
                  "auto_unsubscribed",
                  "container_removed_from_bol",
                  "customer_unsubscribed",
                  "exceeded_extraction_attempt_threshold",
                  "inferred_shipment_completion",
                  "internal_operations",
                  "invalid_container",
                  "invalid_bill_of_lading",
                  "invalid_booking_number",
                  "shipment_completed",
                  "too_long_without_updates"
                ]
              },
              "minItems": 1,
              "description": "Filter on `deactivate_reason`. Repeat the parameter to filter on multiple reasons (`?deactivate_reason=shipment_completed&deactivate_reason=customer_unsubscribed`). Combine with `active=false` to return deactivated references — by default only active references (where `deactivate_reason` is null) are returned.",
              "example": [
                "shipment_completed",
                "customer_unsubscribed"
              ]
            }
          },
          {
            "in": "query",
            "name": "created_start",
            "schema": {
              "$ref": "#/paths/~1tags/post/responses/201/content/application~1json/schema/properties/tag/properties/created_at",
              "description": "Filter start range of `created_at`",
              "example": "2024-01-30T06:45:00.000+00:00"
            }
          },
          {
            "in": "query",
            "name": "created_end",
            "schema": {
              "$ref": "#/paths/~1tags/post/responses/201/content/application~1json/schema/properties/tag/properties/created_at",
              "description": "Filter end range of `created_at`",
              "example": "2024-02-01T00:00:00.000+00:00"
            }
          },
          {
            "in": "query",
            "name": "updated_start",
            "schema": {
              "$ref": "#/paths/~1tags/post/responses/201/content/application~1json/schema/properties/tag/properties/created_at",
              "description": "Return only references whose `updated_at` is at or after this time (inclusive). `updated_at` changes whenever a reference is modified, including when it is deactivated, so combine with `active=false` to fetch references deactivated since a point in time.",
              "example": "2024-01-30T06:45:00.000+00:00"
            }
          },
          {
            "in": "query",
            "name": "updated_end",
            "schema": {
              "$ref": "#/paths/~1tags/post/responses/201/content/application~1json/schema/properties/tag/properties/created_at",
              "description": "Return only references whose `updated_at` is at or before this time (inclusive).",
              "example": "2024-02-01T00:00:00.000+00:00"
            }
          },
          {
            "in": "query",
            "name": "tag_ids",
            "style": "form",
            "explode": true,
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "format": "uuid",
                "example": "6f907cf6-3dd5-489f-8bed-f65370ec6778",
                "description": "Unique identifier."
              },
              "minItems": 1,
              "maxItems": 10,
              "description": "Filter on `tag_ids`. Repeat the parameter to filter on more than one (`?tag_ids=6f907cf6-3dd5-489f-8bed-f65370ec6778&tag_ids=9c8b7a6d-1e2f-4a3b-8c9d-0e1f2a3b4c5d`).",
              "example": [
                "6f907cf6-3dd5-489f-8bed-f65370ec6778",
                "9c8b7a6d-1e2f-4a3b-8c9d-0e1f2a3b4c5d"
              ]
            }
          },
          {
            "in": "query",
            "name": "tag_names",
            "style": "form",
            "explode": true,
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "description": "Tag name. Must be 1-50 characters. Allowed characters: alphanumeric, spaces, hyphens, underscores, colons, and forward slashes. Tag names must be unique. Original casing is preserved.",
                "minLength": 1,
                "maxLength": 50,
                "pattern": "^[a-zA-Z0-9\\s\\-_:/]+$",
                "example": "priority:high"
              },
              "minItems": 1,
              "maxItems": 10,
              "description": "Filter on `tag_names`. Repeat the parameter to filter on more than one (`?tag_names=priority:high&tag_names=reefer`). Matching is case-insensitive.",
              "example": [
                "priority:high",
                "reefer"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of active references",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "title": "Paginated response",
                      "allOf": [
                        {
                          "$ref": "#/paths/~1references~1{referenceId}~1trace/get/responses/200/content/application~1json/schema/allOf/0"
                        },
                        {
                          "type": "object",
                          "properties": {
                            "data": {
                              "type": "array",
                              "items": {
                                "anyOf": [
                                  {
                                    "$ref": "#/paths/~1tags~1{tagId}~1references/get/responses/200/content/application~1json/schema/oneOf/0/items/anyOf/0"
                                  },
                                  {
                                    "$ref": "#/paths/~1tags~1{tagId}~1references/get/responses/200/content/application~1json/schema/oneOf/0/items/anyOf/1"
                                  },
                                  {
                                    "$ref": "#/paths/~1tags~1{tagId}~1references/get/responses/200/content/application~1json/schema/oneOf/0/items/anyOf/2"
                                  }
                                ]
                              }
                            }
                          }
                        }
                      ]
                    },
                    {
                      "title": "Array of references",
                      "type": "array",
                      "items": {
                        "oneOf": [
                          {
                            "$ref": "#/paths/~1tags~1{tagId}~1references/get/responses/200/content/application~1json/schema/oneOf/0/items/anyOf/0"
                          },
                          {
                            "$ref": "#/paths/~1tags~1{tagId}~1references/get/responses/200/content/application~1json/schema/oneOf/0/items/anyOf/1"
                          },
                          {
                            "$ref": "#/paths/~1tags~1{tagId}~1references/get/responses/200/content/application~1json/schema/oneOf/0/items/anyOf/2"
                          }
                        ]
                      }
                    }
                  ]
                },
                "examples": {
                  "ReferenceExample": {
                    "summary": "Response",
                    "value": [
                      {
                        "id": "421f1c94-001e-4a0a-8c5e-c3593b8d000b",
                        "container_id": "CMAU2118620",
                        "bill_of_lading": null,
                        "carrier_scac": "CMDU",
                        "callback_url": "http://4395918f.ngrok.io/webhook",
                        "organization_id": "d5fe91ab-cffa-46fb-979d-aee03e59d3a3",
                        "parent_reference_id": null,
                        "active": true,
                        "last_update_status": "data_received",
                        "created_at": "2020-01-31T06:51:54.397Z",
                        "updated_at": "2020-01-31T21:25:01.764Z",
                        "last_update_attempted_at": "2020-01-31T21:25:01.739Z",
                        "retry_count": 4,
                        "organization": {
                          "id": "d5fe91ab-cffa-46fb-979d-aee03e59d3a3",
                          "name": "Vizion",
                          "active": true,
                          "created_at": "2020-01-31T05:06:14.548Z",
                          "updated_at": "2020-01-31T05:06:14.548Z"
                        }
                      },
                      {
                        "id": "a8f4e867-3fc4-46c4-b3e4-7f9717f3c3ce",
                        "container_id": "KKFU1752206",
                        "bill_of_lading": null,
                        "carrier_scac": "ONEY",
                        "callback_url": "http://4395918f.ngrok.io/webhook",
                        "organization_id": "d5fe91ab-cffa-46fb-979d-aee03e59d3a3",
                        "parent_reference_id": null,
                        "active": true,
                        "last_update_status": "data_received",
                        "created_at": "2020-01-31T05:24:16.674Z",
                        "updated_at": "2020-01-31T23:40:10.114Z",
                        "last_update_attempted_at": "2020-01-31T23:40:10.051Z",
                        "retry_count": 5,
                        "organization": {
                          "id": "d5fe91ab-cffa-46fb-979d-aee03e59d3a3",
                          "name": "Vizion",
                          "active": true,
                          "created_at": "2020-01-31T05:06:14.548Z",
                          "updated_at": "2020-01-31T05:06:14.548Z"
                        }
                      }
                    ]
                  },
                  "PaginatedExample": {
                    "summary": "Paginated response",
                    "value": {
                      "data": [
                        {
                          "id": "11b5a19f-e799-409d-9283-6650a5ef0710",
                          "container_id": "GLDU7685366",
                          "bill_of_lading": "MEDUMJ799185",
                          "carrier_scac": "MSCU",
                          "callback_url": "https://webhook.site/c1eb08ef-ebe1-42e6-8e10-6e062400d25d",
                          "organization_id": "29c06a5d-efb1-4871-b173-b3022113d1c1",
                          "parent_reference_id": "0f3df09b-170b-4f01-be34-67b519b39427",
                          "carrier_id": 6,
                          "active": true,
                          "auto_carrier": false,
                          "last_update_status": "data_received",
                          "created_at": "2022-05-04T20:30:47.890Z",
                          "updated_at": "2022-05-04T20:31:12.966Z",
                          "last_update_attempted_at": "2022-05-04T20:31:11.203Z",
                          "retry_count": 1,
                          "organization": {
                            "id": "29c06a5d-efb1-4871-b173-b3022113d1c1",
                            "name": "Vizion",
                            "active": true,
                            "created_at": "2020-01-17T01:35:25.139Z",
                            "updated_at": "2021-07-23T16:55:34.935Z"
                          },
                          "carrier": {
                            "id": 6,
                            "name": "MSC",
                            "code": "MSCU",
                            "enabled": true,
                            "created_at": "2021-03-03T18:30:27.457Z",
                            "updated_at": "2021-03-03T18:30:27.457Z"
                          }
                        },
                        {
                          "id": "33e80a4d-c023-4f9e-a807-fe8f0dd1d18a",
                          "container_id": "MEDU8381210",
                          "bill_of_lading": "MEDUMJ799185",
                          "carrier_scac": "MSCU",
                          "callback_url": "https://webhook.site/c1eb08ef-ebe1-42e6-8e10-6e062400d25d",
                          "organization_id": "29c06a5d-efb1-4871-b173-b3022113d1c1",
                          "parent_reference_id": "0f3df09b-170b-4f01-be34-67b519b39427",
                          "carrier_id": 6,
                          "active": true,
                          "auto_carrier": false,
                          "last_update_status": "data_received",
                          "created_at": "2022-05-04T20:30:47.889Z",
                          "updated_at": "2022-05-04T20:31:01.008Z",
                          "last_update_attempted_at": "2022-05-04T20:30:59.246Z",
                          "retry_count": 1,
                          "organization": {
                            "id": "29c06a5d-efb1-4871-b173-b3022113d1c1",
                            "name": "Vizion",
                            "active": true,
                            "created_at": "2020-01-17T01:35:25.139Z",
                            "updated_at": "2021-07-23T16:55:34.935Z"
                          },
                          "carrier": {
                            "id": 6,
                            "name": "MSC",
                            "code": "MSCU",
                            "enabled": true,
                            "created_at": "2021-03-03T18:30:27.457Z",
                            "updated_at": "2021-03-03T18:30:27.457Z"
                          }
                        }
                      ],
                      "metadata": {
                        "page": 1,
                        "page_count": 382,
                        "per_page": 2,
                        "item_count": 763
                      }
                    }
                  }
                }
              }
            }
          },
          "4XX": {
            "$ref": "#/paths/~1tags/get/responses/4XX"
          }
        }
      }
    },
    "/tags": {
      "post": {
        "tags": [
          "Tags"
        ],
        "summary": "Create a tag",
        "description": "Create a new tag.",
        "operationId": "tag_create",
        "requestBody": {
          "description": "Tag creation parameters",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "$ref": "#/paths/~1references/get/parameters/16/schema/items"
                  }
                },
                "required": [
                  "name"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Tag successfully created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tag": {
                      "title": "Tag schema",
                      "type": "object",
                      "properties": {
                        "id": {
                          "$ref": "#/paths/~1references/get/parameters/15/schema/items"
                        },
                        "name": {
                          "$ref": "#/paths/~1references/get/parameters/16/schema/items"
                        },
                        "organization_id": {
                          "description": "Unique identifier of the organization.",
                          "type": "string",
                          "format": "uuid",
                          "example": "6f907cf6-3dd5-489f-8bed-f65370ec6778"
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time",
                          "description": "ISO8601 DateTime string.",
                          "example": "2024-01-30T06:45:00.000+00:00"
                        },
                        "updated_at": {
                          "$ref": "#/paths/~1tags/post/responses/201/content/application~1json/schema/properties/tag/properties/created_at"
                        }
                      },
                      "required": [
                        "id",
                        "name",
                        "organization_id",
                        "created_at",
                        "updated_at"
                      ]
                    }
                  }
                }
              }
            }
          },
          "4XX": {
            "$ref": "#/paths/~1tags/get/responses/4XX"
          }
        }
      },
      "get": {
        "tags": [
          "Tags"
        ],
        "summary": "List tags",
        "description": "List all tags.",
        "operationId": "tag_list",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 2000,
              "default": 25,
              "example": 25
            },
            "description": "Requested limit per paginated page"
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "example": 1
            },
            "description": "Requested paginated page"
          }
        ],
        "responses": {
          "200": {
            "description": "List of tags",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "array",
                      "items": {
                        "$ref": "#/paths/~1tags/post/responses/201/content/application~1json/schema/properties/tag"
                      }
                    },
                    {
                      "title": "Paginated tags response",
                      "allOf": [
                        {
                          "$ref": "#/paths/~1references~1{referenceId}~1trace/get/responses/200/content/application~1json/schema/allOf/0"
                        },
                        {
                          "type": "object",
                          "properties": {
                            "data": {
                              "type": "array",
                              "items": {
                                "$ref": "#/paths/~1tags/post/responses/201/content/application~1json/schema/properties/tag"
                              }
                            }
                          }
                        }
                      ]
                    }
                  ]
                }
              }
            }
          },
          "4XX": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "title": "Array of validation errors",
                      "type": "object",
                      "properties": {
                        "errors": {
                          "type": "array",
                          "items": {
                            "title": "Array of validation errors",
                            "type": "array",
                            "items": {
                              "title": "Validation error",
                              "type": "object",
                              "properties": {
                                "property": {
                                  "type": "string",
                                  "description": "The parameter which failed validation",
                                  "example": "limit"
                                },
                                "value": {
                                  "description": "The value which failed validation",
                                  "example": "-1",
                                  "nullable": true,
                                  "oneOf": [
                                    {
                                      "type": "string"
                                    },
                                    {
                                      "type": "number"
                                    },
                                    {
                                      "type": "integer"
                                    },
                                    {
                                      "type": "boolean"
                                    },
                                    {
                                      "type": "array",
                                      "items": {}
                                    },
                                    {
                                      "type": "object"
                                    }
                                  ]
                                },
                                "name": {
                                  "type": "string",
                                  "description": "The name of the failing validation",
                                  "example": "is_positive"
                                },
                                "message": {
                                  "type": "string",
                                  "description": "A human readable description",
                                  "example": "limit must be a positive number"
                                },
                                "detail": {
                                  "type": "string",
                                  "description": "Used to provide additional information to the developer",
                                  "example": "For pagination documentation, see https://docs.vizionapi.com/reference/pagination"
                                }
                              },
                              "required": [
                                "property",
                                "name",
                                "message",
                                "value"
                              ]
                            }
                          }
                        }
                      }
                    },
                    {
                      "title": "Generic error response",
                      "type": "object",
                      "properties": {
                        "error": {
                          "example": "Limit Exceeded",
                          "type": "string",
                          "description": "A human readable description"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/tags/{tagId}": {
      "get": {
        "tags": [
          "Tags"
        ],
        "summary": "Get tag",
        "description": "Returns a tag for a given id.",
        "operationId": "tag_get",
        "parameters": [
          {
            "in": "path",
            "name": "tagId",
            "schema": {
              "$ref": "#/paths/~1references/get/parameters/15/schema/items"
            },
            "required": true,
            "description": "Tag ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Tag details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tag": {
                      "$ref": "#/paths/~1tags/post/responses/201/content/application~1json/schema/properties/tag"
                    }
                  }
                }
              }
            }
          },
          "4XX": {
            "$ref": "#/paths/~1tags/get/responses/4XX"
          }
        }
      },
      "patch": {
        "tags": [
          "Tags"
        ],
        "summary": "Update tag",
        "description": "Update a tag's name.",
        "operationId": "tag_update",
        "parameters": [
          {
            "$ref": "#/paths/~1tags~1{tagId}/get/parameters/0"
          }
        ],
        "requestBody": {
          "description": "Tag update parameters",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "$ref": "#/paths/~1references/get/parameters/16/schema/items"
                  }
                },
                "required": [
                  "name"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/paths/~1tags~1{tagId}/get/responses/200"
          },
          "4XX": {
            "$ref": "#/paths/~1tags/get/responses/4XX"
          }
        }
      }
    }
  }
}
```