Why your OpenAPI spec will not import into a ChatGPT app

Most OpenAPI import failures are not mysterious. They fall into three groups: the document cannot be parsed under the current contract, an operation is visible but incompatible, or inspection succeeds and the explicit operation test fails. Identify the group first; otherwise you will edit the wrong layer.

Inspection is not a universal converter

DraftYourApp inspects a local OpenAPI document and proposes one supported tool. It does not fetch a URL, discover every endpoint or translate an authenticated production API into a public one. The screen can list an operation for context while marking it unsupported. That visibility is useful diagnostics, not a promise that the operation can become a draft.

Check the document before the operations

Start with format and size. The current path accepts OpenAPI 3.0.x or 3.1.x encoded as JSON, not YAML, up to 512 KiB. The document needs info.title, info.version and a paths object, and every imported operation needs an operationId. References must stay inside the document; remote schema URLs are rejected rather than fetched. If the parser stops here, no operation-level diagnosis will help yet.

Read operation diagnostics separately

Once the document loads, inspect each operation’s issue codes. AUTH_UNSUPPORTED_RUNTIME means the operation declares a security requirement; do not strip security from a private API to make the badge disappear. WRITE_UNSUPPORTED_RUNTIME means only GET is currently executable. SERVER_UNSUPPORTED, PARAMETER_UNSUPPORTED, RESPONSE_UNSUPPORTED and SCHEMA_UNSUPPORTED point to different repairs. Fix the contract or choose another operation; renaming the operation will not change eligibility.

Check the server and the parameters

The first server must be an absolute HTTPS URL without credentials, a query string, a fragment or template variables. A relative server or an HTTP URL is rejected even when the endpoint works in a browser. Path and query parameters must be scalar strings, numbers or booleans with supported schemas. Deep objects, headers and cookies are outside the current contract. If a required path placeholder has no matching path parameter, the proposal cannot be built.

Match the success response to the supported schema

Select an operation with a concrete 2xx response that declares application/json and a schema the runtime can validate. The importer reads the first 200 response, or the first other 2xx response, and wraps the JSON data in a bounded envelope. Unsupported schema keywords, missing types, cyclic references and schemas deeper than the supported limit produce diagnostics. A visually valid example response is not a substitute for a declared schema.

When inspection passes but the test fails

A compatible operation still needs an explicit test with representative input. Changing the document, the selected operation or an input value invalidates the prior result, so test again after every edit. Creation requires a successful operation test, demonstrated by a signed receipt for the exact document, operation and account; that receipt lasts fifteen minutes. Test failures usually mean the server rejected the request, the values were wrong, the destination was unreachable or the returned JSON did not match the contract.

A short triage sequence

1. Validate the JSON, version, size and local references.
2. Read the operation issue codes and separate document errors from incompatible operations.
3. Repair the server URL or choose another operation; never remove auth from private data.
4. Confirm scalar path/query parameters and a declared JSON 2xx schema.
5. Run the operation test with representative input and inspect the returned data.
6. Re-test after any document or input change, then create the draft before the receipt expires.

What not to do

Do not add a fake public operation, disable authentication, invent a response field or assume that YAML, remote references or writes will work because another tool accepts them. Do not treat a green local preview as a remote test. If the service is private, use a supported connection or an existing MCP contract rather than weakening the API.

A realistic next step

If the document is valid and one public GET operation is compatible, the remaining work is design rather than import plumbing. Decide what the result should say, test the exact operation and keep the scope narrow. If no operation fits, document the blocking diagnostic and review whether an MCP server already exposes the task you need.