From d56f598d5cdcd04c3406e27ceb89fc57e1d6ef6d Mon Sep 17 00:00:00 2001
From: Laurence <laurence.jones@live.co.uk>
Date: Tue, 26 May 2026 16:32:21 +0100
Subject: [PATCH] docs: explain resource identifiers

---
 manage/blueprints.mdx        |  2 ++
 manage/common-api-routes.mdx | 15 ++++++++++++++-
 2 files changed, 16 insertions(+), 1 deletion(-)

diff --git a/manage/blueprints.mdx b/manage/blueprints.mdx
index 5774cfb..a43c5e0 100644
--- a/manage/blueprints.mdx
+++ b/manage/blueprints.mdx
@@ -43,6 +43,8 @@ sites:
 
 Think of the resource key as your stable ID inside the blueprint. The fields under that key describe what Pangolin should create or maintain.
 
+These keys are the same idea as the **Identifier** shown in the Pangolin app, called `niceId` in the API. Choose readable, stable keys such as `warehouse-west` or `web-app`; blueprints use them to match and update the same sites and resources on later applies. For more detail, see [What is an identifier?](/manage/common-api-routes#what-is-an-identifier).
+
 ## Choose A Format
 
 Pangolin supports two blueprint formats:
diff --git a/manage/common-api-routes.mdx b/manage/common-api-routes.mdx
index b69dad7..66b201e 100644
--- a/manage/common-api-routes.mdx
+++ b/manage/common-api-routes.mdx
@@ -9,6 +9,19 @@ All routes in this guide require an API key. See [Integration API](/manage/integ
 This guide is a **minimal** walkthrough for creating core Pangolin components (sites, resources, targets) via the API. It is not exhaustive — some elements are omitted for simplicity — but everything shown here works and illustrates patterns used elsewhere in the API. For full coverage of endpoints (get, update, delete, list, etc.), use the [Swagger docs](https://api.pangolin.net/v1/docs).
 </Note>
 
+## What is an identifier?
+
+In the Pangolin app, sites, public resources, private resources, and clients have an **Identifier**. In the API, this value is called `niceId`.
+
+The identifier is a human-readable, organization-unique value you can use when you want something more stable and memorable than a numeric ID. For example, a site might have a numeric `siteId` like `8723` and a `niceId` like `warehouse-west`.
+
+Identifiers are especially useful for automation:
+
+- In [Blueprints](/manage/blueprints), resource and site keys act as stable identifiers. A target can reference a site by its identifier, such as `site: warehouse-west`.
+- In the API, responses include both the numeric ID and `niceId` when the object supports identifiers. Some routes can also look up objects by `niceId`, such as `GET /org/{orgId}/site/{niceId}` for sites.
+
+Use the numeric ID when an endpoint asks for `siteId`, `resourceId`, or `siteResourceId`. Use `niceId` when an endpoint or blueprint field asks for an identifier.
+
 ## Create site
 
 This section assumes you're creating a **Newt** site. For all Site endpoints, see [Site API (Swagger)](https://api.pangolin.net/v1/docs/#/Site).
@@ -373,4 +386,4 @@ Both return `{ "data": {}, "success": true, "error": false, "message": "...", "s
 
 **POST** `/site-resource/{siteResourceId}/users/add` — **Path:** `siteResourceId` (number). **Body:** `{ "userId": string }`.
 
-Same response shape as above. Role must belong to the same org as the site resource. For more endpoints (list/remove), see [Resource API](https://api.pangolin.net/v1/docs/#/Resource).
\ No newline at end of file
+Same response shape as above. Role must belong to the same org as the site resource. For more endpoints (list/remove), see [Resource API](https://api.pangolin.net/v1/docs/#/Resource).