Add API docs reliability checks

.github/workflows/docs-quality.yml

@@ -0,0 +1,51 @@
+name: Docs Quality
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  docs-quality:
+    name: Docs Quality
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Run public asset tests
+        run: python3 -m unittest scripts/test_sync_public_assets.py
+
+      - name: Verify generated assets are current
+        run: python3 scripts/sync-public-assets.py --check
+
+      - name: Validate JSON and OpenAPI artifacts
+        run: |
+          jq empty docs.json api-catalog.json openapi.json api-reference/openapi.json api-reference-backup/openapi.json
+          cmp -s openapi.json api-reference/openapi.json
+          cmp -s openapi.json api-reference-backup/openapi.json
+
+      - name: Reject legacy API key guidance
+        run: |
+          if rg -n 'uak_' README.md index.mdx authentication.mdx guides concepts llms.txt llms-full.txt openapi.json api-reference/openapi.json api-catalog.json scripts; then
+            exit 1
+          fi
+
+      - name: Lint OpenAPI
+        run: npx --yes @redocly/cli@2.39.0 lint openapi.json

api-reference-backup/contacts/unlock-phone-task.mdx

@@ -10,7 +10,7 @@ Use this endpoint after `POST /external/contacts/unlock-phone` returns `task_id`
 
 ## When to use this endpoint
 
-Use `GET /external/contacts/unlock-phone-tasks/{taskId}` to poll until the job completaskStatus` is `completed` or `failed`. If some items remain failed while the task is completed, handle those item statuses individually.
+Use `GET /external/contacts/unlock-phone-tasks/{taskId}` to poll until the job completes or fails. Stop polling when `taskStatus` is `completed` or `failed`, and handle item-level failures independently.
 
 ## Notes
 - Phone number is present only when the individual item has been unlocked successfully.

api-reference-backup/contacts/unlock-task.mdx

@@ -14,6 +14,72 @@ Use `GET /external/contacts/unlock-tasks/{taskId}` to make email unlock workflow
 
 Do not assume the unlock result is ready immediately after creating the task.
 
+## Endpoint
+`GET /external/contacts/unlock-tasks/{taskId}`
+
+## Authentication
+See [Authentication](/authentication)
+
+## Success status code
+`200 OK`
+
+## Path parameters
+| Name | Required | Type | Notes |
+| --- | --- | --- | --- |
+| `taskId` | Yes | string | The `task_id` returned by contact unlock. |
+
+## Request example
+```bash
+curl "https://platform.lensmor.com/external/contacts/unlock-tasks/321" \
+  -H "Authorization: Bearer $LENSMOR_API_KEY"
+```
+
+## Response example
+```json
+{
+  "taskId": "321",
+  "taskStatus": "processing",
+  "items": [
+    {
+      "personnelId": "789",
+      "status": "unlocked",
+      "email": "jane@acme.example"
+    },
+    {
+      "personnelId": "790",
+      "status": "processing"
+    }
+  ]
+}
+```
+
+## Response fields
+
+| Field | Description |
+| --- | --- |
+| `taskId` | Contact unlock task identifier. |
+| `taskStatus` | Overall task state. |
+| `items` | Per-person unlock results. |
+| `items[].personnelId` | Personnel identifier submitted in the unlock request. |
+| `items[].status` | Item-level unlock state. |
+| `items[].email` | Email address when the item is unlocked successfully. |
+| `items[].errorCode` | Error code when an individual item fails, if provided. |
+
+## Status values
+Task status:
+
+- `pending`
+- `processing`
+- `completed`
+- `failed`
+
+Item status:
+
+- `pending`
+- `processing`
+- `unlocked`
+- `failed`
+
 ## Result interpretation
 
 Treat each `items[]` entry independently:
@@ -33,6 +99,11 @@ Use a backoff schedule instead of polling aggressively:
 
 Stop polling when `taskStatus` is `completed` or `failed`. If some items remain failed while the task is completed, handle those item statuses individually.
 
+## Error responses
+- `401 Unauthorized`
+- `404 Not Found`
+- `429 Too Many Requests`
+
 ## Notes
 - `email` is present only when the individual item has been unlocked successfully.
 - Failed items can include `errorCode`.

api-reference-backup/contacts/unlock.mdx

@@ -19,9 +19,72 @@ This endpoint is intentionally asynchronous because email unlock can involve mul
 </Note>
 
 <Warning>
-  A `201 Created` response means the unlock task was accepted. It does not guaubmitted personnel record will return an email. Always inspect item-level task results before counting a contact as enriched.
+  A `201 Created` response means the unlock task was accepted. It does not guarantee that every submitted personnel record will return an email. Always inspect item-level task results before counting a contact as enriched.
 </Warning>
 
+## Endpoint
+`POST /external/contacts/unlock`
+
+## Authentication
+See [Authentication](/authentication)
+
+## Success status code
+`201 Created`
+
+## Request body
+| Name | Required | Type | Notes |
+| --- | --- | --- | --- |
+| `personnel_ids` | Yes | string[] | One or more personnel identifiers. Maximum `100` per request. |
+| `event_id` | Yes | string | Supports event `id` or `eventId` returned by event responses. |
+
+## Headers
+| Name | Required | Type | Notes |
+| --- | --- | --- | --- |
+| `x-call-source` | No | string | Optional usage source. Use `api` or `agent`; defaults to `api`. |
+
+## Request example
+```bash
+curl -X POST "https://platform.lensmor.com/external/contacts/unlock" \
+  -H "Authorization: Bearer $LENSMOR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -H "x-call-source: api" \
+  -d '{"event_id":"139574","personnel_ids":["789","790"]}'
+```
+
+## Response example
+```json
+{
+  "status": "accepted",
+  "task_id": "321",
+  "job_id": "321"
+}
+```
+
+## Response fields
+
+| Field | Description |
+| --- | --- |
+| `status` | Initial task acceptance state. Usually `accepted` when the task was created. |
+| `task_id` | Identifier used to poll task status. Store this value. |
+| `job_id` | Alias for the background job identifier. It currently matches `task_id`. |
+
+## Polling pattern
+
+After receiving `task_id`, poll the task endpoint:
+
+```bash
+curl "https://platform.lensmor.com/external/contacts/unlock-tasks/321" \
+  -H "Authorization: Bearer $LENSMOR_API_KEY"
+```
+
+Use backoff instead of a tight polling loop. A practical pattern is:
+
+1. Wait a few seconds after task creation.
+2. Poll every few seconds for short jobs.
+3. Increase the interval if the job remains in progress.
+4. Stop polling when the task completes or fails.
+5. Re-fetch personnel or contact records if your UI needs the latest `email` and `contactUnlockStatus` values.
+
 ## Credit behavior
 
 Contact email unlock currently costs `15` credits per chargeable contact.
@@ -32,6 +95,15 @@ Contact email unlock currently costs `15` credits per chargeable contact.
 - Insufficient balance returns `402 Payment Required`.
 - Retry behavior should be tied to the task state, not only the create response.
 
+## Error responses
+- `400 Bad Request`
+- `401 Unauthorized`
+- `402 Payment Required`
+- `404 Not Found`
+- `409 Conflict`
+- `429 Too Many Requests`
+
 ## Notes
-- This endpoint creates an asynchronous unlock job. Poll [Get contact unlock task](/api-reference/contacts/get-contact-unlock-task) with `taskot create duplicate unlock tasks while a prior task for the same selected contacts is still pending or processing.
+- This endpoint creates an asynchronous unlock job. Poll [Get contact unlock task](/api-reference/contacts/get-contact-unlock-task) with `task_id`.
+- Do not create duplicate unlock tasks while a prior task for the same selected contacts is still pending or processing.
 - See [Credits and access](/concepts/credits-and-access) for shared credit behavior.