Mintlify support email

Mintlify Support: API Playground Proxy Rejects Valid URL

To: [e-mail] Subject: API Playground proxy returns “invalid URL” for valid AWS API Gateway URL — network evidence included

---

Hi Mintlify team,

We’ve been debugging an “invalid URL” error in the API Playground for several hours and have narrowed it down to the Mintlify proxy server itself rejecting our URL. We have network-level evidence showing the exact request/response. We’d appreciate your help diagnosing this.

The Problem

The API Playground’s “Send” button always returns: “An error occurred while making the request: invalid URL”

The generated curl command works perfectly from the terminal, returning valid JSON data. The issue is specifically in the /_mintlify/api/request proxy endpoint.

Network Evidence

We captured the exact proxy request/response using Playwright browser automation:

Request sent by the playground to the proxy:

POST https://fieldpulse.mintlify.app/_mintlify/api/request
Content-Type: application/json

{
  "method": "get",
  "url": "https://ywe3crmpll.execute-api.us-east-2.amazonaws.com/stage/users",
  "header": {
    "x-api-key": "0jblaJ3ZPP7txlfM7HMz23nx1jCYdX93afufPBUu",
    "content-type": "application/json"
  },
  "cookie": {},
  "query": {}
}

Response from the proxy:

HTTP 200
Content-Type: application/json

{"error": true, "errorMessage": "invalid URL"}

The proxy receives the fully constructed, valid URL and returns {"error": true, "errorMessage": "invalid URL"} with a 200 status code.

The same URL works via curl:

curl --request GET \
  --url https://ywe3crmpll.execute-api.us-east-2.amazonaws.com/stage/users \
  --header 'x-api-key: 0jblaJ3ZPP7txlfM7HMz23nx1jCYdX93afufPBUu'

Response (success):

{
    "error": false,
    "total_count": "",
    "response": [...]
}

Live Reproduction

• Page: https://fieldpulse.mintlify.app/api-reference/users/retrieve-users-list?playground=open
• Steps: Enter any valid API key in the x-api-key field, click “Send”
• Result: “An error occurred while making the request: invalid URL”
• Expected: Live JSON response from the API

This reproduces on every endpoint in the API Reference tab, not just /users.

Our Configuration

docs.json api block (minimal — we stripped everything per your help center’s guidance):

{
  "api": {
    "playground": {
      "display": "interactive",
      "proxy": true
    },
    "examples": {
      "languages": ["curl", "python", "javascript"],
      "defaults": "required",
      "prefill": true
    },
    "params": {
      "expanded": "all"
    }
  }
}

OpenAPI spec servers field:

{
  "openapi": "3.0.0",
  "servers": [
    {
      "url": "https://ywe3crmpll.execute-api.us-east-2.amazonaws.com/stage",
      "description": "Production"
    }
  ]
}

OpenAPI spec securitySchemes:

{
  "components": {
    "securitySchemes": {
      "apiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "x-default": "your-api-key-here"
      }
    }
  },
  "security": [{ "apiKeyAuth": [] }]
}

MDX endpoint pages (generated by @mintlify/scraping):

---
openapi: get /users
---

Validation:

• mintlify validate passes (“success build validation passed”)
• mint openapi-check openapi/fieldpulse-api.json passes (“success OpenAPI definition is valid”)

What We’ve Already Tried

Attempt	Result
Tab-level openapi auto-generation	”invalid URL”
MDX stubs from @mintlify/scraping (current)	“invalid URL”
MDX stubs with spec path: openapi: "openapi/fieldpulse-api.json GET /users"	”invalid URL”
Added api.openapi: "openapi/fieldpulse-api.json"	”invalid URL”
Added api.mdx.server + api.mdx.auth	”invalid URL”
Removed api.mdx.server + api.mdx.auth (per your help center)	“invalid URL”
Set proxy: false	Error changed to “unable to complete request” (CORS — expected, confirms URL is valid)

Every configuration produces the same proxy-side “invalid URL” rejection. The proxy: false test is particularly telling — it proves the URL construction is correct (the browser tried to reach the API directly and hit CORS, not an invalid URL).

Our API URL

Our API is hosted on AWS API Gateway:

https://ywe3crmpll.execute-api.us-east-2.amazonaws.com/stage

This is a standard AWS API Gateway URL in us-east-2. The /stage path segment is the API Gateway stage name.

Questions for Your Engineering Team

1. Does the Mintlify proxy have URL validation rules that reject certain URL patterns? Specifically, does it reject AWS API Gateway URLs (*.execute-api.*.amazonaws.com)?

2. Can you check the proxy-side logs for our subdomain (fieldpulse)? The request to /_mintlify/api/request returned {"error":true,"errorMessage":"invalid URL"} — what validation step produced this error?

3. Is there a known issue with the proxy and certain URL formats? The URL passes JavaScript’s new URL() validation and works via curl.

Repository & Resources

• Repo: https://github.com/fp-evan/fieldpulse-docs
• OpenAPI spec: https://github.com/fp-evan/fieldpulse-docs/blob/main/openapi/fieldpulse-api.json
• Live site: https://fieldpulse.mintlify.app
• Test page: https://fieldpulse.mintlify.app/api-reference/users/retrieve-users-list?playground=open

We’re happy to provide any additional information or make configuration changes if you identify something on your end.

Thank you, Evan Rallis [e-mail]