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

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

Documents the account-scoped document type catalog (GET /documents/types) and the new on-demand detail endpoint (GET /documents/types/{code}) that returns a type's sanitized extraction-field structure. Regenerates the TypeScript SDK contract from the updated spec.

Changes

GET /documents/types: code and label stay required for every option; catalog-visible types additionally return description and schema.{id,version,detail_url}.
GET /documents/types/{code}: new operation returning document_type_detail with a recursive sanitized_extraction_schema payload. Option-only codes return 404.
Clarifies in the spec and MDX that this structure is distinct from the versioned document_schemas/{id} payload used to validate document_representation.payload.
Adds the previously dangling #/components/schemas/user component (id, type, open attributes) so the SDK generator resolves every $ref.
Error responses reuse #/components/schemas/error like the rest of the spec; additionalProperties: false is kept only on sanitized_extraction_schema, where it encodes the sanitizer's key allow-list.
Regenerates sdks/typescript-sdk/src/generated/terminal49.ts. The undocumented /containers/{id}/route path drops out of the generated types, so ContainerManager.route() now uses transport.executeManual, matching the existing custom_fields calls.
New Mintlify page documents/get-a-document-type and nav entry; descriptions updated on the list and document-schema pages.

Test plan

Run locally on the rebased head:

npm run generate:types --workspace @terminal49/sdk (committed output)
npm run build --workspace @terminal49/sdk, npm run type-check --workspace @terminal49/sdk, npm run lint --workspace @terminal49/sdk
npm run test --workspace @terminal49/sdk -- --run (106 passed, 1 skipped)
npm run docs --workspace @terminal49/sdk leaves docs/sdk/reference unchanged
npm run build --workspace @terminal49/mcp && npm run test --workspace @terminal49/mcp -- --run (223 passed)
npx tsc --noEmit -p tsconfig.json
cd docs && npx -y mintlify@latest broken-links (no broken links)
git diff --check
spectral lint --ruleset .spectral.mjs docs/openapi.json fails to fetch the remote ruleset (HTTP 404 for branch feat/container-event-timestamps). Pre-existing; not fixed here.

Not verified: the shapes above against a live backend response. user.attributes is left open for that reason.

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	Sep 13, 2026 2:10am 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-09-13T02:13:53.034823Z	`71e2d65`	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 👍 / 👎.

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

Navigation Menu

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

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

dodeja commented Aug 25, 2026 •

edited

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!

dodeja Sep 13, 2026

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!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Sep 13, 2026

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

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

Uh oh!

Changes

Test plan

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!

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