[Trace] Accuracy fixes from SDK-main/backend-master review

Author: Nicolas Fry

docs/API/create-image-variable-folder.api.mdx

@@ -40,7 +40,7 @@ curl -X POST "https://api.turbodocx.com/Variable" \
   }'
 ```
 
-Send exactly one of `templateFolderId` (scopes the variable to that folder) or `isGlobal: true` (adds it to your org-wide knowledge base); sending both is rejected. `text` must be a base64 `data:` URI when `mimeType` is `"image"`, or plain text/HTML otherwise. `placeholder` must be unique within its folder or knowledge base and, if set, must be wrapped in curly braces, for example `{CompanyLogo}`.
+Optionally send `templateFolderId` (scopes the variable to that folder) or `isGlobal: true` (adds it to your org-wide knowledge base); at most one may be set, and sending both is rejected. `text` must be a base64 `data:` URI when `mimeType` is `"image"`, or plain text/HTML otherwise. `placeholder` must be unique within its folder or knowledge base and, if set, must be wrapped in curly braces, for example `{CompanyLogo}`.
 
 ## Example response
 
@@ -73,8 +73,9 @@ On success the endpoint returns the created variable:
 | ------ | ---- | ------------- |
 | 401 | Missing or invalid API key/token, or the organization cannot be resolved | Empty (status only) |
 | 403 | The key's role is not administrator, contributor, or user | Empty (status only) |
-| 400 | `mimeType` or `text` is missing, `placeholder` is not wrapped in `{ }`, or both `isGlobal` and `templateFolderId` are set | `{ "message", "type": "ValidationError", "data": { "errors": [...] } }` |
-| 400 | `placeholder` already exists in that folder or knowledge base | `{ "message", "type": "TemplateError", "data": [{ "message", "type", "data": { "explanation", "context" } }] }` |
+| 403 | `isGlobal: true` and the key's role is `user` (creating a knowledge-base variable requires administrator or contributor) | Empty (status only) |
+| 400 | `mimeType` or `text` is missing, or both `isGlobal` and `templateFolderId` are set | `{ "message", "type": "ValidationError", "data": { "errors": [...] } }` |
+| 400 | `placeholder` is not wrapped in `{ }`, or already exists in that folder or knowledge base | `{ "message", "type": "TemplateError", "data": [{ "message", "type", "data": { "explanation", "context" } }] }` |
 
 ## Related endpoints
 

docs/API/create-webhook.api.mdx

@@ -17,7 +17,7 @@ custom_edit_url: null
 
   # Create Webhook
 
-The Create Webhook endpoint registers a webhook that TurboDocx calls when TurboSign events happen in your organization, such as a document being signed or completed. Each webhook needs a unique `name` within your org; every TurboDocx SDK sends `"signature"`, so a second create call with the default name fails with a conflict instead of creating a duplicate.
+The Create Webhook endpoint registers a webhook that TurboDocx calls when TurboSign events happen in your organization, such as a document being signed or completed. Each webhook needs a unique `name` among your org's active webhooks; every TurboDocx SDK sends `"signature"`. A second create call with that name conflicts (409) only while an active webhook already has it; if you paused a webhook via [Update Webhook](/docs/API/update-webhook)'s `isActive: false` instead of deleting it, creating a new one with the same name succeeds and leaves two rows sharing that name, and by-name lookups on the other endpoints may then hit either one. Delete the old webhook (see [Delete Webhook](/docs/API/delete-webhook)) before reusing its name, rather than just pausing it.
 
 ## When to use it
 
@@ -70,7 +70,7 @@ On success the endpoint returns `201 Created`:
 | ------ | ---- | ------------- |
 | 401 | Missing or invalid API key/token, or the organization cannot be resolved | Empty (status only) |
 | 403 | The key's role is not administrator | Empty (status only) |
-| 400 | `name`, `urls`, or `events` is missing or invalid, or any URL is not HTTPS | `{ "error": "..." }` (validation) |
+| 400 | `name`, `urls`, or `events` is missing or invalid, or any URL is not HTTPS | `{ "message", "type": "ValidationError", "data": { "errors": [...] } }` |
 | 409 | A webhook named `signature` already exists in your organization | `{ "message", "error": "WebhookNameTaken", "data": { "constraint", "orgId", "name" } }` |
 
 ## Related endpoints

docs/API/extract-template-placeholders-and-generate-preview.api.mdx

@@ -57,7 +57,7 @@ With `skipFile=true`:
 }
 ```
 
-Without `skipFile`, the response also includes `templatePdf`, a base64-encoded PDF rendering of the uploaded file. Pass the `vars` array as the `variables` field (JSON-stringified) when you subsequently call [Upload Template with Optional Default Values](/docs/API/upload-template-with-optional-default-values).
+Without `skipFile`, the response also includes `templatePdf`, the rendered PDF of the uploaded file. It is a JSON-serialized Node.js Buffer, not a base64 string: an object of the form `{"type": "Buffer", "data": [37, 80, 68, 70, ...]}`, where `data` is an array of the PDF's raw bytes. To use it, reconstruct the binary from the byte array, for example `Buffer.from(templatePdf.data)` in Node.js or `new Uint8Array(templatePdf.data)` in the browser. Pass the `vars` array as the `variables` field (JSON-stringified) when you subsequently call [Upload Template with Optional Default Values](/docs/API/upload-template-with-optional-default-values).
 
 ## Common errors
 

docs/API/list-webhook-deliveries.api.mdx

@@ -34,6 +34,8 @@ curl "https://api.turbodocx.com/api/webhooks/signature/deliveries?limit=20&offse
 
 Supported filters: `eventType`, `isDelivered` (`true`/`false`), and `httpStatus` (an exact status code). `limit` defaults to `20`, `offset` to `0`.
 
+> **Known limitation:** `isDelivered=true` and `httpStatus` do not currently filter results correctly due to a backend issue: `isDelivered=true` returns the same (undelivered-only) results as `isDelivered=false`, and `httpStatus` is ignored entirely regardless of value. Only `isDelivered=false` behaves as documented today.
+
 ## Example response
 
 ```json
@@ -64,7 +66,7 @@ Supported filters: `eventType`, `isDelivered` (`true`/`false`), and `httpStatus`
 }
 ```
 
-`status` summarizes the row as `"delivered"`, `"failed"` (all `maxAttempts` attempts exhausted), `"retrying"`, or `"pending"`. Failed deliveries retry automatically with backoff (1, 5, then 10 minutes) up to `maxAttempts` (3) before landing in the dead-letter state.
+`status` summarizes the row as `"delivered"`, `"failed"` (all `maxAttempts` attempts exhausted), `"retrying"`, or `"pending"`. Failed deliveries retry automatically with backoff (immediate, then +1 minute, then +5 minutes) for up to `maxAttempts` (3) attempts total before landing in the dead-letter state.
 
 ## Common errors
 

docs/API/read-tag.api.mdx

@@ -17,7 +17,7 @@ custom_edit_url: null
 
   # Read Tag
 
-The Read Tag endpoint lists the active tags in your organization, sorted alphabetically by `label` by default. Despite the singular name, it returns a paginated array, not a single tag; there is no dedicated "get tag by ID" endpoint.
+The Read Tag endpoint lists the active tags in your organization, sorted alphabetically by `label` by default. Despite the singular name, it returns a paginated array, not a single tag. To fetch one tag by its ID, use `GET /Tag/:id`, which returns a single tag object under `data.results` (404 if not found).
 
 ## When to use it
 
@@ -67,6 +67,7 @@ curl "https://api.turbodocx.com/Tag?limit=25&offset=0&query=legal" \
 - [Create Tag](/docs/API/create-tag) to add a new tag
 - [Update Tag](/docs/API/update-tag) to rename an existing tag
 - [Delete Tags (by IDs)](/docs/API/delete-tags-by-i-ds) to remove tags in bulk
+- `GET /Tag/:id` to fetch a single tag by ID
 
   <DisplayEndpoint method="GET" endpoint="/Tag"/>
   <QueryTable title="query" data="W3sia2V5IjoibGltaXQiLCJleGFtcGxlIjoiIn1d" />

docs/API/read-variables-folder.api.mdx

@@ -32,7 +32,7 @@ curl "https://api.turbodocx.com/Variable?isGlobal=true&limit=25&offset=0&showTag
   -H "Accept: application/json"
 ```
 
-Pass exactly one of `isGlobal=true` (your org-wide knowledge base) or `templateFolderId=<folder id>` (a specific folder); the two are mutually exclusive. `limit` defaults to `6`, `offset` to `0`, and `query` filters by name.
+Optionally pass `isGlobal=true` (your org-wide knowledge base) or `templateFolderId=<folder id>` (a specific folder) to scope the list; at most one may be set, and passing both is rejected. Omit both to list across your accessible scope. `limit` defaults to `6`, `offset` to `0`, and `query` filters by name.
 
 ## Example response
 

docs/API/replay-webhook-delivery.api.mdx

@@ -1,7 +1,7 @@
 ---
 id: replay-webhook-delivery
 title: "Replay Webhook Delivery"
-description: "Manually retry one past delivery by its ID. Creates a new delivery row and immediately attempts redelivery to all configured URLs."
+description: "Manually retry one past delivery by its ID. Creates a new delivery row and immediately re-sends the event to the URL the original delivery targeted."
 sidebar_label: "Replay Webhook Delivery"
 hide_title: true
 hide_table_of_contents: true
@@ -17,7 +17,7 @@ custom_edit_url: null
 
   # Replay Webhook Delivery
 
-The Replay Webhook Delivery endpoint manually retries a specific past delivery, identified by its `deliveryId`. It creates a brand-new delivery row for the attempt (the original row is left as-is) and immediately re-sends the event to the webhook's configured URL.
+The Replay Webhook Delivery endpoint manually retries a specific past delivery, identified by its `deliveryId`. It creates a brand-new delivery row for the attempt (the original row is left as-is) and immediately re-sends the event to the URL the original delivery was made to (not every URL configured on the webhook, if it has more than one).
 
 ## When to use it
 

docs/API/test-webhook.api.mdx

@@ -61,7 +61,7 @@ Both `eventType` and `payload` are optional; omit them to send a default sample
 }
 ```
 
-If a URL returns a non-2xx status or times out, its entry has `isDelivered: false`, `status: "retrying"` or `"failed"`, and the failure is counted in `summary.failed` with a message in `summary.errors`.
+If a URL returns a non-2xx status or times out, its entry has `isDelivered: false` and `status: "retrying"` (while attempts remain) or `"failed"` (once all attempts are exhausted), with details in `errorMessage`. `summary.failed`/`summary.errors` do not currently reflect HTTP-level failures; they only count a database error while creating the delivery record, so a URL that returns 4xx/5xx or times out through all attempts still increments `summary.successful` and leaves `summary.errors` empty. Inspect each `deliveries[]` entry's `isDelivered`, `status`, and `errorMessage` to detect a failing receiver rather than relying on `summary.failed`.
 
 ## Common errors
 

docs/API/update-tag.api.mdx

@@ -17,7 +17,7 @@ custom_edit_url: null
 
   # Update Tag
 
-The Update Tag endpoint changes a tag's `label`. It is a `PUT`, but in practice `label` is the only field you can usefully send; the tag's other fields (`id`, `orgId`) are not accepted in the body.
+The Update Tag endpoint changes a tag's `label`. It is a `PUT`, but in practice `label` is the only field you should send. `orgId` is not an accepted body field and returns a validation error if sent. `id` is different: it isn't rejected by validation, and it isn't ignored either; the endpoint applies whatever body you send, so an `id` that differs from the `TagId` in the URL will overwrite the tag's actual `id` instead of being discarded. Omit `id` from the body and let the URL path segment identify the tag to update.
 
 ## When to use it
 

docs/API/update-variable-by-id.api.mdx

@@ -17,7 +17,7 @@ custom_edit_url: null
 
   # Update Variable (by ID)
 
-The Update Variable (by ID) endpoint replaces a knowledge-base or template-folder variable's content and metadata. Unlike [Edit Template Metadata](/docs/API/edit-template-metadata), this is a full replace, not a partial patch: `mimeType` and `text` are required on every call, along with either `isGlobal` or `templateFolderId`.
+The Update Variable (by ID) endpoint replaces a knowledge-base or template-folder variable's content and metadata. Unlike [Edit Template Metadata](/docs/API/edit-template-metadata), this is a full replace, not a partial patch: `mimeType` and `text` are required on every call. `isGlobal` and `templateFolderId` are both optional; at most one may be set.
 
 ## When to use it
 
@@ -41,7 +41,7 @@ curl -X PUT "https://api.turbodocx.com/Variable/e4f5a6b7-8c9d-4e0f-a1b2-3c4d5e6f
   }'
 ```
 
-`{VariableId}` in the path is the `variableMapId` returned by [Read Variables (Folder)](/docs/API/read-variables-folder), not the underlying `Variable.id`. Send exactly one of `isGlobal: true` or `templateFolderId`; sending both is rejected. For an image variable, set `mimeType` to `"image"` and `text` to a base64 data string.
+`{VariableId}` in the path is the `variableMapId` returned by [Read Variables (Folder)](/docs/API/read-variables-folder), not the underlying `Variable.id`. Optionally send `isGlobal: true` or `templateFolderId`, but not both; sending both is rejected. For an image variable, set `mimeType` to `"image"` and `text` to a base64 data string.
 
 ## Example response
 
@@ -67,8 +67,7 @@ On success the endpoint returns `200 OK` with the updated variable wrapped in a
 | Status | When | Response body |
 | ------ | ---- | ------------- |
 | 401 | Missing or invalid API key/token, or the organization cannot be resolved | Empty (status only) |
-| 403 | The key's role is not administrator, contributor, or user | Empty (status only) |
-| 423 | The template the variable belongs to is locked | `{ "error": "Resource is locked", "message", "data": { "locked": true, "lockedBy", "lockedOn" } }` |
+| 403 | The key's role is not administrator, contributor, or user. For `isGlobal: true` updates (as in the example above), only administrator and contributor are allowed; the `user` role is also rejected with `403`. | Empty (status only) |
 | 400 | `mimeType` or `text` is missing, or both `isGlobal` and `templateFolderId` are set | `{ "message", "type": "ValidationError", "data": { "errors": [...] } }` |
 | 409 | The variable was deleted or modified by someone else before this update landed | `{ "error", "data": { "explanation" } }` |