diff --git a/docs/api/rest-contract.md b/docs/api/rest-contract.md
index 4065a47..2feddd4 100644
--- a/docs/api/rest-contract.md
+++ b/docs/api/rest-contract.md
@@ -29,6 +29,15 @@ De API gebruikt **lowercase** statussen. De database gebruikt UPPER_SNAKE; de ve
 | Task status | `todo`, `in_progress`, `review`, `done` |
 | Story status | `open`, `in_sprint`, `done` |
 
+## Entity codes
+
+PBI's, stories en tasks hebben elk een verplichte `code` (max 30 chars, regex `^[A-Za-z0-9._-]+$`) die als stabiele identifier dient binnen het product:
+
+- **Auto-generatie** wanneer niet meegegeven: `PBI-N`, `ST-N` (3-digit padded), `T-N` — eigen sequence per product.
+- **Uniek per `(product_id, code)`** voor alle drie entiteiten.
+- **Stabiel bij re-parenting**: een task die naar een andere story wordt verplaatst behoudt zijn `code` (Jira-stijl).
+- POST-body `code` is **optioneel** (server vult bij ontbreken); response bevat `code` altijd.
+
 ## Foutcodes
 
 | Code | Betekenis |
@@ -142,7 +151,7 @@ Hoogst geprioriteerde open story in de actieve sprint.
   "tasks": [
     {
       "id": "...",
-      "code": "ST-356.1",
+      "code": "T-42",
       "title": "Store stores/solo-store.ts",
       "description": "...",
       "implementation_plan": null,