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

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

Documents the proposed account-scoped document type catalog and its extraction-field detail endpoint. Depends on backend Terminal49/t49#3311, which remains open; do not publish or merge these endpoint claims before that backend contract is available. No live endpoint response has been verified.

Every allowed list item keeps code and label; catalog-visible items add description and schema metadata. Option-only detail requests return 404.
Detail payloads retain only the sanitizer's six structural keys, including recursive properties and array items. This is distinct from the versioned schema that validates document representations.
Compared the contract against the exact proposed backend catalog service at 86644c4b581009575d73bbb1e40f21eb1189daf5.
Synchronized current main, resolved the generated Postman conflict by regeneration, and regenerated SDK types. The missing user component in the existing source prevented baseline type regeneration; this branch supplies an open attributes contract rather than inventing user fields.
Postman's generator now uses its supported example-resolution mode, with consistent CI/review/local commands. Generated examples contain structural JSON instead of circular-reference placeholders. This changes other explicitly defined collection examples as well.

Validation: Node 24 frozen root install, all workspace builds/checks, 381 tests passed and one live-token test skipped; SDK docs generation leaves the current generated docs unchanged. JSON parsing, all six sanitizer structural keys, and the generated detail response were checked. SDK type regeneration succeeds and git diff --check passes.

SDK route() keeps the manual transport while the route path is absent from this spec. The separately stacked PR #384 documents that route.

Final-head CI, Claude review, both HTTP protocol previews and Mintlify validation passed at 44bb9d9841658b4ae1d7c622b1f0682512c73078. Local Spectral lint remains blocked by the existing remote ruleset returning 404; the ruleset was not replaced.

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

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

Project	Status	Preview	Updated
terminal49	🟢 Ready	View Preview	Sep 13, 2026, 2:10 AM

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
api	Ready	Preview	Oct 6, 2026 5:18am UTC

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.

Dismissing. Terminal49-API.postman_collection.json is generated by .github/workflows/generate_postman.yml on every push that touches docs/openapi.json and is not hand-edited (AGENTS.md). The <Circular reference ...> placeholder is openapi-to-postman's schema faker hitting sanitized_extraction_schema, which is genuinely recursive (a JSON Schema whose properties/items are schemas). Fixing the placeholder would mean either flattening the real contract or hand-editing a generated artifact; neither is worth it for a sample value.

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.

Drops unrelated formatting churn, reuses #/components/schemas/error for the 401/404 responses, removes non-conventional additionalProperties:false, removes a customer name from a public description, and narrows the user component to verified fields.

Also inlines the single-use route include constant.

chatgpt-codex-connector · 2026-09-13T02:06:55Z

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-06T05:21:47.235233Z	`44bb9d9`	New commits

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 71e2d65302

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-09-13T02:13:51Z

@@ -9366,12 +9366,12 @@
                                    "value": "application/json"
                                }
                            ],
-                            "body": "{\n  \"document_types\": [\n    {\n      \"code\": \"<string>\",\n      \"label\": \"<string>\"\n    },\n    {\n      \"code\": \"<string>\",\n      \"label\": \"<string>\"\n    }\n  ]\n}",
+                            "body": "{\n  \"document_types\": [\n    {\n      \"code\": \"<string>\",\n      \"label\": \"<string>\",\n      \"description\": \"<string>\",\n      \"schema\": {\n        \"id\": \"<string>\",\n        \"version\": \"<string>\",\n        \"detail_url\": \"<string>\"\n      }\n    },\n    {\n      \"code\": \"<string>\",\n      \"label\": \"<string>\",\n      \"description\": \"<string>\",\n      \"schema\": {\n        \"id\": \"<string>\",\n        \"version\": \"<string>\",\n        \"detail_url\": \"<string>\"\n      }\n    }\n  ]\n}",


Publish usable document-type examples in Postman

When consumers import the regenerated Postman collection, this example shows every list item with schema, contradicting the newly documented option-only shape; the detail example also contains literal <Circular reference ... detected> placeholders instead of a usable extraction schema. Ensure the OpenAPI source/generation configuration emits the concrete examples already defined in the spec, then regenerate the collection rather than publishing these schema-faked responses.

AGENTS.md reference: AGENTS.md:L51-L53

Useful? React with 👍 / 👎.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 44bb9d9841

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-10-06T05:21:43Z

+                    "value": {
+                      "errors": [
+                        {
+                          "detail": "invalid API token"


Include the required title in 401 examples

When consumers validate the newly added 401 examples, they fail the documented response schema: each errors item references #/components/schemas/error, where title is required, but both document-type 401 examples contain only detail. Add the actual title (and any other returned fields), or use a response schema that accurately permits the detail-only payload, so the OpenAPI and generated Postman examples do not contradict their contract.

Useful? React with 👍 / 👎.

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

greptile-apps Bot reviewed Aug 25, 2026

View reviewed changes

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

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

dodeja and others added 4 commits September 12, 2026 18:51

docs: expose supported document type schemas

e3ea992

fix(sdk): regenerate document type contract

ab60798

fix(sdk): regenerate types after openapi cleanup

8c515e6

Also inlines the single-use route include constant.

dodeja force-pushed the vorflux/dev-12120-supported-document-types branch from b6ef855 to 8c515e6 Compare September 13, 2026 02:06

vercel Bot deployed to Preview September 13, 2026 02:08 View deployment

chore: Auto-generate Postman collection from openapi.json

71e2d65

dodeja force-pushed the vorflux/dev-12120-supported-document-types branch from 1c926b0 to 71e2d65 Compare September 13, 2026 02:09

mintlify Bot deployed to staging - docs September 13, 2026 02:10 View deployment

vercel Bot deployed to Preview September 13, 2026 02:10 View deployment

chatgpt-codex-connector Bot reviewed Sep 13, 2026

View reviewed changes

dodeja and others added 4 commits October 5, 2026 22:16

chore: synchronize document type contract with current main

0b69c80

fix(docs): generate Postman responses from explicit examples

fc9e901

chore: Auto-generate Postman collection from openapi.json [skip ci]

d5e7304

chore: validate regenerated document contract on current head

44bb9d9

vercel Bot deployed to Preview October 6, 2026 05:18 View deployment

chatgpt-codex-connector Bot reviewed Oct 6, 2026

View reviewed changes

Conversation

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

Uh oh!

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!

dodeja Sep 13, 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!

chatgpt-codex-connector Bot commented Sep 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codex Review Summary

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Sep 13, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Oct 6, 2026

Choose a reason for hiding this comment

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

dodeja commented Aug 25, 2026 •

edited

Loading

mintlify Bot commented Aug 25, 2026 •

edited

Loading

vercel Bot commented Aug 25, 2026 •

edited

Loading

chatgpt-codex-connector Bot commented Sep 13, 2026 •

edited

Loading