DEV-12120: document supported document type schemas by dodeja · Pull Request #348 · Terminal49/API

dodeja · 2026-08-25T16:20:23Z

Documents the account-scoped supported document type catalog and its on-demand extraction schema detail. The contract preserves every account-allowed option while exposing public catalog metadata only where a detail response exists.

Changes

Extend GET /documents/types with optional description and schema metadata while keeping code and label required for every option.
Add GET /documents/types/{code} for catalog-visible sanitized extraction-field structure and clarify that option-only list values return 404 from detail.
Distinguish extraction-field schemas from versioned document_representation.payload validation in the API reference.
Regenerate the TypeScript SDK contract and use the SDK transport's manual path for the existing undocumented container route.
Add the missing public-safe user component required to resolve existing OpenAPI references.
Synchronize the MCP locked-listing assertion with the approved ChatGPT app subtitle so the repository-wide MCP suite remains green.

Out-of-Scope Feedback

Repair the API docs Spectral ruleset source — Pending

Testing

Passed: OpenAPI JSON assertions for required code/label, optional catalog metadata, the detail endpoint, option-only example, and public-safe user schema.
Passed: TypeScript SDK generation, build, typecheck, and lint.
- npm run generate:types --workspace @terminal49/sdk
- npm run build --workspace @terminal49/sdk
- npm run type-check --workspace @terminal49/sdk
- npm run lint --workspace @terminal49/sdk
Passed: targeted MCP annotation test and full MCP suite.
- npm run test --workspace @terminal49/mcp -- --run src/annotations.test.ts
- npm run test --workspace @terminal49/mcp -- --run
Passed: replacement GitHub Actions CI run 32874453982, including MCP tests and all protocol preview jobs.
Passed: cd docs && npx -y mintlify@latest broken-links.
Passed: docs browser walkthrough and git diff --check.
Confirmed: Terminal49-API.postman_collection.json is unchanged from origin/main.
Blocked: npx -y @stoplight/spectral-cli@6.16.3 lint --ruleset .spectral.mjs docs/openapi.json cannot fetch the deleted remote branch feat/container-event-timestamps and returns HTTP 404.

Evidence:

Attached Images and Videos

🎥 View recording: dev12120-final-docs-flow.webm

Session Details

Session: View Session
Requested by: Akshay Dodeja (akshay@terminal49.com)
Address comments on this PR. Add (aside) to your comment to have me ignore it.

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

Greptile Summary

This PR documents account-visible document-type metadata and a detail endpoint exposing sanitized extraction-field structure, while clarifying the distinction from versioned payload-validation schemas.

Adds list and detail contracts and recursive document-type schemas to the OpenAPI description.
Adds Mintlify reference content and navigation for the detail endpoint.
Regenerates the Postman collection with the new operations.

Confidence Score: 4/5

The generated TypeScript contract should be synchronized before merging; the malformed Postman detail example should also be corrected.

The OpenAPI source exposes a new typed operation that is absent from the committed SDK definitions, while the generated Postman response presents circular-reference diagnostics as example data.

Files Needing Attention: docs/openapi.json, sdks/typescript-sdk/src/generated/terminal49.ts, Terminal49-API.postman_collection.json

Important Files Changed

Filename	Overview
docs/openapi.json	Adds the document-type detail contract and recursive schemas, but the corresponding committed TypeScript definitions remain stale.
Terminal49-API.postman_collection.json	Adds generated document-type requests, but the detail response example includes circular-reference diagnostics as payload values.
docs/api-docs/api-reference/documents/get-a-document-type.mdx	Adds a focused reference page explaining account visibility, sanitizer boundaries, and the distinction from validation schemas.
docs/docs.json	Adds the new document-type detail page to Documents navigation.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  OpenAPI[docs/openapi.json] --> Docs[Mintlify API reference]
  OpenAPI --> Postman[Postman collection]
  OpenAPI --> Generator[SDK generate:types]
  Generator --> SDK[Generated TypeScript paths and schemas]
  List[GET /documents/types] --> Detail[GET /documents/types/code]
  Detail --> Sanitized[Sanitized extraction-field structure]
  Versioned[GET /document_schemas/id] --> Validator[Representation payload validator]

Prompt To Fix All With AI

### Issue 1
docs/openapi.json:9506-9507
**Generated SDK contract is stale**

When TypeScript SDK consumers use the newly documented detail endpoint, the committed generated contract contains neither `GET /documents/types/{code}` nor its response schemas, so the endpoint and response types are unavailable from the package. Regenerate `sdks/typescript-sdk/src/generated/terminal49.ts` from this OpenAPI update.

### Issue 2
Terminal49-API.postman_collection.json:9455
**Circular-reference diagnostics pollute example**

The generated detail response contains literal `<Circular reference ... detected>` values under `payload.properties` and `payload.items`. This exposes generator diagnostics instead of realistic response data, making the new endpoint's primary Postman example misleading and unusable as a sample payload.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "chore: Auto-generate Postman collection ..." | Re-trigger Greptile}

Greptile also left 2 inline comments on this PR.

mintlify · 2026-08-25T16:20:27Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
terminal49	🟢 Ready	View Preview	Aug 25, 2026, 4:22 PM

linear-code · 2026-08-25T16:20:27Z

DEV-12120

vercel · 2026-08-25T16:20:30Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
api	Ready	Preview	Aug 25, 2026 4:52pm

greptile-apps · 2026-08-25T16:24:14Z

+    "/documents/types/{code}": {
+      "get": {


Generated SDK contract is stale

When TypeScript SDK consumers use the newly documented detail endpoint, the committed generated contract contains neither GET /documents/types/{code} nor its response schemas, so the endpoint and response types are unavailable from the package. Regenerate sdks/typescript-sdk/src/generated/terminal49.ts from this OpenAPI update.

Knowledge Base Used: TypeScript SDK models and generation

Prompt To Fix With AI

This is a comment left during a code review. Path: docs/openapi.json Line: 9506-9507 Comment: **Generated SDK contract is stale** When TypeScript SDK consumers use the newly documented detail endpoint, the committed generated contract contains neither `GET /documents/types/{code}` nor its response schemas, so the endpoint and response types are unavailable from the package. Regenerate `sdks/typescript-sdk/src/generated/terminal49.ts` from this OpenAPI update. **Knowledge Base Used:** [TypeScript SDK models and generation](https://app.greptile.com/terminal49/-/custom-context/knowledge-base/terminal49/api/-/docs/typescript-sdk-models-and-generation.md) --- For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

Addressed in 4057614. The TypeScript SDK contract was regenerated from the updated OpenAPI source; SDK build, typecheck, and lint all pass.

greptile-apps · 2026-08-25T16:24:14Z

+                                    "value": "application/json"
+                                }
+                            ],
+                            "body": "{\n  \"document_type\": {\n    \"code\": \"<string>\",\n    \"label\": \"<string>\",\n    \"description\": \"<string>\",\n    \"schema\": {\n      \"id\": \"<string>\",\n      \"version\": \"<string>\",\n      \"format\": \"json_schema\",\n      \"payload\": {\n        \"type\": \"<string>\",\n        \"format\": \"<string>\",\n        \"enum\": [\n          \"\",\n          \"\"\n        ],\n        \"properties\": {\n          \"key_0\": {\n            \"value\": \"<Circular reference to #/components/schemas/sanitized_extraction_schema detected>\"\n          }\n        },\n        \"items\": {\n          \"value\": \"<Circular reference to #/components/schemas/sanitized_extraction_schema detected>\"\n        },\n        \"required\": [\n          \"<string>\",\n          \"<string>\"\n        ]\n      }\n    }\n  }\n}",


Circular-reference diagnostics pollute example

The generated detail response contains literal <Circular reference ... detected> values under payload.properties and payload.items. This exposes generator diagnostics instead of realistic response data, making the new endpoint's primary Postman example misleading and unusable as a sample payload.

Prompt To Fix With AI

This is a comment left during a code review. Path: Terminal49-API.postman_collection.json Line: 9455 Comment: **Circular-reference diagnostics pollute example** The generated detail response contains literal `<Circular reference ... detected>` values under `payload.properties` and `payload.items`. This exposes generator diagnostics instead of realistic response data, making the new endpoint's primary Postman example misleading and unusable as a sample payload. --- For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Resolved by rebasing onto current main and force-pushing the reviewed source changes. Terminal49-API.postman_collection.json is now unchanged from origin/main, so the generated circular-reference example is no longer part of this PR.

chatgpt-codex-connector · 2026-08-25T16:47:06Z

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

chatgpt-codex-connector · 2026-08-25T16:51:36Z

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

docs: expose supported document type schemas

787a21e

mintlify Bot deployed to staging - docs August 25, 2026 16:22 View deployment

greptile-apps Bot reviewed Aug 25, 2026

View reviewed changes

fix(sdk): regenerate document type contract

4057614

dodeja force-pushed the vorflux/dev-12120-supported-document-types branch from 311fb49 to 4057614 Compare August 25, 2026 16:47

vercel Bot deployed to Preview August 25, 2026 16:48 View deployment

mintlify Bot deployed to staging - docs August 25, 2026 16:48 View deployment

test(mcp): sync ChatGPT listing subtitle

b6ef855

dodeja force-pushed the vorflux/dev-12120-supported-document-types branch from 9bb386e to b6ef855 Compare August 25, 2026 16:51

mintlify Bot deployed to staging - docs August 25, 2026 16:52 View deployment

vercel Bot deployed to Preview August 25, 2026 16:52 View deployment

Navigation Menu

Uh oh!

DEV-12120: document supported document type schemas - #348

DEV-12120: document supported document type schemas#348
dodeja wants to merge 3 commits into
mainfrom
vorflux/dev-12120-supported-document-types

dodeja commented Aug 25, 2026 •

edited by vorflux Bot

Loading

Uh oh!

mintlify Bot commented Aug 25, 2026 •

edited

Loading

Uh oh!

linear-code Bot commented Aug 25, 2026

Uh oh!

vercel Bot commented Aug 25, 2026 •

edited

Loading

Uh oh!

greptile-apps Bot Aug 25, 2026

Uh oh!

vorflux Bot Aug 25, 2026

Uh oh!

greptile-apps Bot Aug 25, 2026

Uh oh!

vorflux Bot Aug 25, 2026

Uh oh!

chatgpt-codex-connector Bot commented Aug 25, 2026

Uh oh!

chatgpt-codex-connector Bot commented Aug 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

dodeja commented Aug 25, 2026 • edited by vorflux Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Out-of-Scope Feedback

Testing

Greptile Summary

Confidence Score: 4/5

Important Files Changed

Flowchart

Uh oh!

mintlify Bot commented Aug 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

linear-code Bot commented Aug 25, 2026

Uh oh!

vercel Bot commented Aug 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

greptile-apps Bot Aug 25, 2026

Choose a reason for hiding this comment

Uh oh!

vorflux Bot Aug 25, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot Aug 25, 2026

Choose a reason for hiding this comment

Uh oh!

vorflux Bot Aug 25, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot commented Aug 25, 2026

Uh oh!

chatgpt-codex-connector Bot commented Aug 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

dodeja commented Aug 25, 2026 •

edited by vorflux Bot

Loading

mintlify Bot commented Aug 25, 2026 •

edited

Loading

vercel Bot commented Aug 25, 2026 •

edited

Loading