Rename Namespace

Bulk-rename a tag namespace across every tag that uses it.

Tags follow a namespace:value convention (e.g. part_number:12345). This endpoint rewrites the namespace on every oldNamespace:* tag in your organization to newNamespace:* in one operation — part_number:12345 → part:12345, part_number:678 → part:678, and so on. Only the namespace changes; each tag's value is preserved verbatim (case, spaces, and all).

The :namespace path segment is the source namespace to rename; the namespace field in the body is the target. Both are matched case-insensitively and normalised (see below).

Namespace normalisation

Namespaces are always stored as lowercase snake_case, so the target you send is normalised before it is applied:

lowercased,
every run of non-alphanumeric characters (spaces, hyphens, etc.) collapsed to a single _,
leading/trailing _ trimmed.

So "Part Number", "part-number", and "PART_NUMBER" all resolve to part_number. The response echoes the normalised namespace (target) and previous_namespace (source) so you can see exactly what was applied. A target that normalises to an empty string (no letters or digits) is rejected with 400.

The namespace must be colon-free — the colon is the reserved namespace:value separator. A body namespace containing a colon returns 400.

Collision merge

If renaming would produce a tag name that already exists — i.e. a value exists under both the old and new namespace (part_number:12345 renamed while part:12345 already exists) — the two tags are merged, not rejected. Every resource tagged with the old tag is re-linked to the surviving target tag (a resource already carrying both keeps a single link, not a duplicate), and the redundant old tag is removed. This is the default behaviour — there is no separate merge flag.

The operation is strictly scoped to your organization: a namespace with the same name owned by another organization is never touched. It runs in a single transaction, so a partial rename can never leave dangling or duplicated tag links.

Response

Field	Description
`namespace`	The new (normalised) namespace.
`previous_namespace`	The source namespace that was renamed.
`tags_renamed`	Number of tags moved to the new namespace (renamed + merged).

Use cases

Standardise a namespace convention (partno → part_number) across every tag in one call.
Merge two namespaces by renaming one onto the other — colliding values fold together automatically.

Errors

Status	Code	Cause
400	`VALIDATION_ERROR`	Body `namespace` missing, contains a colon/whitespace, or normalises to empty.
401	`MISSING_API_KEY` / `INVALID_API_KEY`	Auth missing or invalid.
403	`FORBIDDEN`	API key lacks `tags:write`.
404	`NOT_FOUND`	No tags exist in the source namespace for your organization.

Required scope: tags:write