---
title: "Rename external id or set tenant scope"
method: PATCH
path: "/v2/organizations/{organizationId}/templates/{externalId}"
tags: ["Templates"]
---

# Rename external id or set tenant scope

`PATCH /v2/organizations/{organizationId}/templates/{externalId}`

## Request

- Base URL: `https://api.pdfs.build`
- URL: `https://api.pdfs.build/v2/organizations/{organizationId}/templates/{externalId}`
- Auth: HTTP bearer

Renames the template's external id and/or sets its delegated-access `scopePath`. At least one field is required. After a rename the old v2 URL stops resolving immediately; the internal id, the v1 URL and historical render-log references do not change. Requires template ownership or organization admin access; `scopePath` additionally requires a key owned by an organization owner or admin.

## Request body

- UpdateTemplateRequest
  - `externalId` string: Organization-scoped template id you control. 1–128 ASCII letters, digits, `.`, `_`, `~` or `-`; `.` and `..` are reserved. Case-sensitive.
  - `scopePath` string: Tenant scope for delegated agent access: zero or more segments, each 1–128 chars from the external-id charset and each ending in `/`, e.g. `acct_9f3/entity_dubai/`. Empty means unscoped — invisible to every delegated grant.

## Response `200`

The updated template.

- Template
  - `internalId` string, required: Generated, immutable. What v1 URLs and the embedded SDK address.
  - `externalId` string, required: Organization-scoped template id you control. 1–128 ASCII letters, digits, `.`, `_`, `~` or `-`; `.` and `..` are reserved. Case-sensitive.
  - `name` string, required
  - `description` string, nullable
  - `status` 'draft' | 'published', required
  - `scopePath` string, required: Tenant scope for delegated agent access: zero or more segments, each 1–128 chars from the external-id charset and each ending in `/`, e.g. `acct_9f3/entity_dubai/`. Empty means unscoped — invisible to every delegated grant.
  - `createdAt` string, required: UTC, ISO 8601 without a timezone suffix.
  - `updatedAt` string, required: UTC, ISO 8601 without a timezone suffix.
  - `schema` object, nullable: JSON Schema of the render `data` payload.
  - `schemaLocked` boolean, required: When true the data contract is frozen: embedded editing can restyle the document but cannot add, remove or retype a field.
  - `sampleData` object, nullable: Example data satisfying `schema`.
  - `baseTemplateId` string, nullable: Internal id of the base template this one layers on, if any.
  - `version` integer, nullable: Present when `version` was given: the frozen version `schema` and `sampleData` come from, or null for the working copy.
  - `channel` string, nullable: Present when `version` was given: the channel the selector resolved through, if any.

## Other responses

- `400`: Neither field provided, `invalid_external_id`, or `invalid_scope_path`.
- `401`: Missing, invalid or expired API key.
- `403`: `organization_scope_mismatch`, `forbidden` (no edit access), or `scope_path_admin_required`.
- `404`: No template with that id is accessible to this key. Another user's draft is indistinguishable from a missing template.
- `409`: `external_id_conflict` — the new external id is already reserved.

---

[API](https://skmtc.dev/pdfs/apis/pdfs-build-api.md) · [All operations](https://skmtc.dev/pdfs/apis/pdfs-build-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pdfs/apis/pdfs-build-api/revisions/1c7340b9521d?raw)