docs(api): TRA-742 BB43 F1+F2 — info.contact.url + external_key symmetry sweep

static/api/openapi.json

@@ -461,13 +461,16 @@
         "additionalProperties": false,
         "properties": {
           "description": {
+            "example": "Main warehouse forklift",
             "maxLength": 1024,
             "minLength": 1,
             "nullable": true,
             "pattern": "^[^\\x00-\\x08\\x0B\\x0C\\x0E-\\x1F\\x7F]*$",
             "type": "string"
           },
           "external_key": {
+            "description": "external_key is optional. Omit to receive a server-assigned key in the\nformat ASSET-NNNN (per-organization sequence). When supplied, must\nsatisfy the external_key_pattern.",
+            "example": "forklift-3",
             "maxLength": 255,
             "minLength": 1,
             "pattern": "^[A-Za-z0-9-]+$",
@@ -482,6 +485,7 @@
             "type": "object"
           },
           "name": {
+            "example": "Forklift 3",
             "maxLength": 255,
             "minLength": 1,
             "pattern": "^[^\\x00-\\x08\\x0B\\x0C\\x0E-\\x1F\\x7F]*$",
@@ -1184,20 +1188,23 @@
       "UpdateAssetRequest": {
         "properties": {
           "description": {
+            "example": "Updated description",
             "maxLength": 1024,
             "minLength": 1,
             "nullable": true,
             "pattern": "^[^\\x00-\\x08\\x0B\\x0C\\x0E-\\x1F\\x7F]*$",
             "type": "string"
           },
           "is_active": {
+            "example": true,
             "type": "boolean"
           },
           "metadata": {
             "additionalProperties": {},
             "type": "object"
           },
           "name": {
+            "example": "Forklift 3",
             "maxLength": 255,
             "minLength": 1,
             "pattern": "^[^\\x00-\\x08\\x0B\\x0C\\x0E-\\x1F\\x7F]*$",
@@ -1303,7 +1310,7 @@
     "contact": {
       "email": "support@trakrf.id",
       "name": "TrakRF Support",
-      "url": "https://app.trakrf.id/api"
+      "url": "https://docs.trakrf.id/"
     },
     "description": "TrakRF public REST API. See /api for the customer-facing reference.\n\nSpec available as YAML (/api/openapi.yaml) and JSON (/api/openapi.json).\n\nHTTP method coverage (HEAD, OPTIONS, 405 / Allow): /api/http-method-coverage\n\nSurrogate ID width: declared `format: int64` on the wire so SDK regeneration does not break when the ID namespace eventually outgrows int32. Service-side ID generation stays within int32 (2^31-1) during v1; values above that bound are rejected with 400 validation_error / `too_large`. The wider wire type is a long-horizon contract, not a claim that current values exceed int32.\n\nNullable field interpretation: OpenAPI 3.0's `nullable: true` keyword is interpreted differently across codegen targets. Verified-working: `openapi-typescript@7.x` emits `string | null` correctly, and the `openapi-generator-cli` python target emits `Optional[StrictStr]` correctly — both round-trip CRUD against null-bearing responses unmodified. Known-broken: `datamodel-codegen@0.57.0` emits `nullable: true` read-shape fields as non-Optional required fields, so Pydantic validation fails on every nullable field that is actually null. Integrators using `datamodel-codegen` should either switch to the `openapi-generator-cli` python target or apply `--use-annotated --use-union-operator` with a custom post-processing pass.",
     "license": {

static/api/openapi.yaml

@@ -339,12 +339,18 @@ components:
             additionalProperties: false
             properties:
                 description:
+                    example: Main warehouse forklift
                     maxLength: 1024
                     minLength: 1
                     nullable: true
                     pattern: ^[^\x00-\x08\x0B\x0C\x0E-\x1F\x7F]*$
                     type: string
                 external_key:
+                    description: |-
+                        external_key is optional. Omit to receive a server-assigned key in the
+                        format ASSET-NNNN (per-organization sequence). When supplied, must
+                        satisfy the external_key_pattern.
+                    example: forklift-3
                     maxLength: 255
                     minLength: 1
                     pattern: ^[A-Za-z0-9-]+$
@@ -356,6 +362,7 @@ components:
                     additionalProperties: {}
                     type: object
                 name:
+                    example: Forklift 3
                     maxLength: 255
                     minLength: 1
                     pattern: ^[^\x00-\x08\x0B\x0C\x0E-\x1F\x7F]*$
@@ -880,17 +887,20 @@ components:
         UpdateAssetRequest:
             properties:
                 description:
+                    example: Updated description
                     maxLength: 1024
                     minLength: 1
                     nullable: true
                     pattern: ^[^\x00-\x08\x0B\x0C\x0E-\x1F\x7F]*$
                     type: string
                 is_active:
+                    example: true
                     type: boolean
                 metadata:
                     additionalProperties: {}
                     type: object
                 name:
+                    example: Forklift 3
                     maxLength: 255
                     minLength: 1
                     pattern: ^[^\x00-\x08\x0B\x0C\x0E-\x1F\x7F]*$
@@ -970,7 +980,7 @@ info:
     contact:
         email: support@trakrf.id
         name: TrakRF Support
-        url: https://app.trakrf.id/api
+        url: https://docs.trakrf.id/
     description: |-
         TrakRF public REST API. See /api for the customer-facing reference.
 

static/api/platform-meta.json

@@ -1,5 +1,5 @@
 {
-  "commit": "07b5edb",
-  "source_url": "https://github.com/trakrf/platform/commit/07b5edb0f593eb04bb0a1d22c8a0c3fc2a94fec0",
-  "spec_refreshed_at": "2026-05-16T11:36:28Z"
+  "commit": "24db422",
+  "source_url": "https://github.com/trakrf/platform/commit/24db422ef313cf6c65de118aaebe090d5f922fbc",
+  "spec_refreshed_at": "2026-05-16T12:53:03Z"
 }