DEV-12120: document supported document type schemas

.github/workflows/claude.yml

@@ -144,7 +144,7 @@ jobs:
             Useful commands:
             - cd docs && mintlify dev
             - spectral lint --ruleset .spectral.mjs docs/openapi.json
-            - openapi2postmanv2 -s docs/openapi.json -o Terminal49-API.postman_collection.json -p -O folderStrategy=Tags,enableOptionalParameters=false
+            - node tools/generate-postman.mjs
 
             If API behavior or schemas change, update docs/openapi.json first. Regenerate the Postman collection only when explicitly needed.
             You have no shell. File edits are limited to the checked-out repository and commits go through the GitHub API; when validation needs shell commands, report the exact commands for a maintainer to run."

.github/workflows/generate_postman.yml

@@ -6,6 +6,7 @@ on:
       - 'docs/openapi.json'
       - '.github/workflows/generate_postman.yml'
       - 'tools/postman-generation.test.mjs'
+      - 'tools/generate-postman.mjs'
 
 jobs:
   generate-postman-collection:
@@ -29,7 +30,7 @@ jobs:
       - name: Generate Postman Collection
         run: |
           echo "Generating Postman collection from OpenAPI spec..."
-          openapi2postmanv2 -s docs/openapi.json -o Terminal49-API.postman_collection.json -p -O folderStrategy=Tags,enableOptionalParameters=false
+          node tools/generate-postman.mjs
 
       - name: Test Postman generation
         run: node --test tools/postman-generation.test.mjs

AGENTS.md

@@ -61,7 +61,7 @@ For substantive documentation writing, use the repo-local skill at `skills/termi
 ### Docs
 - Preview locally: `cd docs && mintlify dev`
 - Lint the OpenAPI spec: `spectral lint --ruleset .spectral.mjs docs/openapi.json`
-- Regenerate Postman: `openapi2postmanv2 -s docs/openapi.json -o Terminal49-API.postman_collection.json -p -O folderStrategy=Tags,enableOptionalParameters=false`
+- Regenerate Postman: `node tools/generate-postman.mjs`
 
 ### Code (npm workspaces)
 - Install: `vp install` at the root (`npm ci` remains the frozen CI and Vercel install command).

docs/AGENTS.md

@@ -40,7 +40,7 @@ For substantive documentation writing, use the repo-local skill at `../skills/te
 ## When updating API reference
 - If you change API behavior or schemas, update `docs/openapi.json` first.
 - Regenerate the Postman collection with:
-  `openapi2postmanv2 -s docs/openapi.json -o Terminal49-API.postman_collection.json -p -O folderStrategy=Tags,enableOptionalParameters=false`
+  `node tools/generate-postman.mjs`
 
 ## MDX conventions
 - Every page must include frontmatter with a `title`.

docs/api-docs/api-reference/document-schemas/get-a-document-schema.mdx

@@ -1,10 +1,12 @@
 ---
 title: "Get a document schema"
-description: "Retrieve a Terminal49 document schema for an extraction output, including the schema version and the structured payload contract for parsed fields."
+description: "Retrieve a versioned Terminal49 JSON Schema that validates a document_representation.payload."
 og:title: Get a Document Schema | Terminal49 API
-og:description: Retrieve a document schema by ID from the Terminal49 API. Returns the schema definition used to validate and extract structured shipping documents.
+og:description: Retrieve a versioned JSON Schema by ID from the Terminal49 API to validate a document representation payload.
 openapi: get /document_schemas/{id}
 ---
 <Info>
   **Beta Feature** - This endpoint is currently in beta. The API is stable, but the schema and behavior may evolve based on feedback.
 </Info>
+
+Returns the versioned JSON Schema used to validate `document_representation.payload`. It does not return the sanitized extraction-field structure for a supported document type; use [Get a document type](/api-docs/api-reference/documents/get-a-document-type) for that structure.

docs/api-docs/api-reference/documents/get-a-document-type.mdx

@@ -0,0 +1,17 @@
+---
+title: "Get a document type"
+description: "Retrieve one account-visible document type and its sanitized extraction-field structure."
+openapi: "get /documents/types/{code}"
+---
+
+<Info>
+  **Beta Feature** - This endpoint is currently in beta. The API is stable, but the schema and behavior may evolve based on feedback.
+</Info>
+
+Returns one document type visible to the authenticated account. A code that is not in that account's catalog returns `404`.
+
+## Schema payload
+
+`schema.payload` is a sanitized structural projection for rendering the type's extraction fields. It can contain field types, formats, enum values, nested properties, array items, and required fields. A field type can be a string or an array of strings, such as `["string", "null"]`. Array `items` can be one schema or an array of schemas. It omits internal extensions, prompts, instructions, titles, and descriptions.
+
+This extraction-field structure does not validate `document_representation.payload`. For the versioned JSON Schema used to validate a document representation payload, use [Get a document schema](/api-docs/api-reference/document-schemas/get-a-document-schema).

docs/api-docs/api-reference/documents/list-document-types.mdx

@@ -1,9 +1,13 @@
 ---
 title: "List document types"
-description: "List the allowed document types and labels configured for your Terminal49 account so your app can populate selectors and validate uploads correctly."
+description: "List every document type allowed for your Terminal49 account, with public descriptions and schema links when available."
 openapi: "get /documents/types"
 ---
 
 <Info>
   **Beta Feature** - This endpoint is currently in beta. The API is stable, but the schema and behavior may evolve based on feedback.
-</Info>
+</Info>
+
+Returns every document type allowed for the authenticated account so existing selectors and upload validation remain compatible.
+
+Types included in the public catalog also contain a description and `schema.detail_url` for retrieving their extraction-field structure on demand. The list does not include schema payloads, field counts, or derived field paths. See [Get a document type](/api-docs/api-reference/documents/get-a-document-type) for the detail response.

docs/docs.json

@@ -161,6 +161,7 @@
               "api-docs/api-reference/documents/edit-a-document",
               "api-docs/api-reference/documents/delete-a-document",
               "api-docs/api-reference/documents/list-document-types",
+              "api-docs/api-reference/documents/get-a-document-type",
               "api-docs/api-reference/documents/get-a-document-download-url",
               "api-docs/api-reference/documents/re-extract-a-document",
               "api-docs/api-reference/documents/re-classify-a-document",