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

mintlifyBotdeployed to staging - docs August 25, 2026 16:22 View deployment

greptile-appsBot 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 4057614Compare August 25, 2026 16:47

vercelBotdeployed to Preview August 25, 2026 16:48 View deployment

mintlifyBotdeployed 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 b6ef855Compare August 25, 2026 16:51

mintlifyBotdeployed to staging - docs August 25, 2026 16:52 View deployment

vercelBotdeployed 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!

mintlifyBot commented Aug 25, 2026•
edited
Loading

Uh oh!

linear-codeBot commented Aug 25, 2026

Uh oh!

vercelBot commented Aug 25, 2026•
edited
Loading

Uh oh!

greptile-appsBotAug 25, 2026

Uh oh!

vorfluxBotAug 25, 2026

Uh oh!

greptile-appsBotAug 25, 2026

Uh oh!

vorfluxBotAug 25, 2026

Uh oh!

chatgpt-codex-connectorBot commented Aug 25, 2026

Uh oh!

chatgpt-codex-connectorBot 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 BotLoading 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!

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

Uh oh!

Uh oh!

linear-codeBot commented Aug 25, 2026

Uh oh!

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

Uh oh!

Uh oh!

greptile-appsBotAug 25, 2026

Choose a reason for hiding this comment

Uh oh!

vorfluxBotAug 25, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-appsBotAug 25, 2026

Choose a reason for hiding this comment

Uh oh!

vorfluxBotAug 25, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connectorBot commented Aug 25, 2026

Uh oh!

chatgpt-codex-connectorBot 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

mintlifyBot commented Aug 25, 2026•
edited
Loading

vercelBot commented Aug 25, 2026•
edited
Loading