The Fumadocs OpenAPI Proxy API is a server-side HTTP proxy included in the fumadocs-openapi package that enables the interactive API playground to make authenticated requests to external API servers from the browser without CORS restrictions. Documentation sites mount the proxy at a route such as /api/proxy, where it accepts any HTTP method, extracts the target URL from the url query parameter, and transparently forwards the request to the upstream server.
openapi: 3.1.0
info:
title: Fumadocs OpenAPI Proxy API
description: >-
The Fumadocs OpenAPI Proxy API is a server-side HTTP proxy built into the
fumadocs-openapi package that enables the interactive API playground to make
requests to external OpenAPI servers from the browser without encountering
CORS restrictions. The proxy accepts any HTTP method, extracts a target URL
from the url query parameter, forwards the request to the target server, and
returns the response. Allowed origins or URL prefixes can be configured to
restrict which targets may be proxied. Documentation sites using the
Fumadocs OpenAPI playground integrate this proxy at a route such as
/api/proxy to support try-it-now functionality within the rendered API
reference.
version: '10.3.18'
contact:
name: Fumadocs
url: https://fumadocs.dev
license:
name: MIT
url: https://github.com/fuma-nama/fumadocs/blob/main/LICENSE
externalDocs:
description: Fumadocs OpenAPI Documentation
url: https://fumadocs.dev/docs/ui/openapi
servers:
- url: '{baseUrl}'
description: Fumadocs documentation site
variables:
baseUrl:
default: http://localhost:3000
description: >-
Base URL of the documentation site. Each site configures its own
proxy endpoint path, typically /api/proxy.
tags:
- name: Proxy
description: >-
HTTP proxy endpoints that forward requests to external API servers on
behalf of the browser-based OpenAPI playground to avoid CORS issues.
paths:
/api/proxy:
get:
operationId: proxyGet
summary: Fumadocs Proxy a GET request to an external API
description: >-
Forwards a GET request to the external API server specified by the url
query parameter. Returns the upstream server's response including status
code, headers, and body. Used by the Fumadocs OpenAPI playground to
perform try-it-now requests from the browser. The target URL must be
allowed by the proxy's configured allowedOrigins or filterRequest rules.
tags:
- Proxy
parameters:
- $ref: '#/components/parameters/proxyUrl'
responses:
'200':
description: Response from the upstream API server.
content:
application/json:
schema:
description: Upstream API response body.
additionalProperties: true
'400':
description: >-
Bad request. The url parameter is missing or the target origin is
not allowed.
content:
application/json:
schema:
$ref: '#/components/schemas/ProxyError'
'403':
description: The proxied request is not allowed by the configured filter rules.
content:
application/json:
schema:
$ref: '#/components/schemas/ProxyError'
'500':
description: The proxy failed to connect to or receive a response from the upstream server.
content:
application/json:
schema:
$ref: '#/components/schemas/ProxyError'
post:
operationId: proxyPost
summary: Fumadocs Proxy a POST request to an external API
description: >-
Forwards a POST request with body to the external API server specified
by the url query parameter. Used by the Fumadocs OpenAPI playground
for try-it-now operations that create or submit data.
tags:
- Proxy
parameters:
- $ref: '#/components/parameters/proxyUrl'
requestBody:
description: Request body to forward to the upstream API server.
required: false
content:
application/json:
schema:
additionalProperties: true
responses:
'200':
description: Response from the upstream API server.
content:
application/json:
schema:
additionalProperties: true
'400':
description: Bad request. The url parameter is missing or the target origin is not allowed.
content:
application/json:
schema:
$ref: '#/components/schemas/ProxyError'
'403':
description: The proxied request is not allowed by the configured filter rules.
content:
application/json:
schema:
$ref: '#/components/schemas/ProxyError'
'500':
description: The proxy failed to connect to the upstream server.
content:
application/json:
schema:
$ref: '#/components/schemas/ProxyError'
put:
operationId: proxyPut
summary: Fumadocs Proxy a PUT request to an external API
description: >-
Forwards a PUT request with body to the external API server specified
by the url query parameter. Used by the Fumadocs OpenAPI playground
for try-it-now update operations.
tags:
- Proxy
parameters:
- $ref: '#/components/parameters/proxyUrl'
requestBody:
description: Request body to forward to the upstream API server.
required: false
content:
application/json:
schema:
additionalProperties: true
responses:
'200':
description: Response from the upstream API server.
content:
application/json:
schema:
additionalProperties: true
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/ProxyError'
'403':
description: Forbidden.
content:
application/json:
schema:
$ref: '#/components/schemas/ProxyError'
'500':
description: Upstream connection failure.
content:
application/json:
schema:
$ref: '#/components/schemas/ProxyError'
patch:
operationId: proxyPatch
summary: Fumadocs Proxy a PATCH request to an external API
description: >-
Forwards a PATCH request with body to the external API server specified
by the url query parameter. Used by the Fumadocs OpenAPI playground
for try-it-now partial update operations.
tags:
- Proxy
parameters:
- $ref: '#/components/parameters/proxyUrl'
requestBody:
description: Request body to forward to the upstream API server.
required: false
content:
application/json:
schema:
additionalProperties: true
responses:
'200':
description: Response from the upstream API server.
content:
application/json:
schema:
additionalProperties: true
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/ProxyError'
'403':
description: Forbidden.
content:
application/json:
schema:
$ref: '#/components/schemas/ProxyError'
'500':
description: Upstream connection failure.
content:
application/json:
schema:
$ref: '#/components/schemas/ProxyError'
delete:
operationId: proxyDelete
summary: Fumadocs Proxy a DELETE request to an external API
description: >-
Forwards a DELETE request to the external API server specified by
the url query parameter. Used by the Fumadocs OpenAPI playground
for try-it-now delete operations.
tags:
- Proxy
parameters:
- $ref: '#/components/parameters/proxyUrl'
responses:
'200':
description: Response from the upstream API server.
content:
application/json:
schema:
additionalProperties: true
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/ProxyError'
'403':
description: Forbidden.
content:
application/json:
schema:
$ref: '#/components/schemas/ProxyError'
'500':
description: Upstream connection failure.
content:
application/json:
schema:
$ref: '#/components/schemas/ProxyError'
head:
operationId: proxyHead
summary: Fumadocs Proxy a HEAD request to an external API
description: >-
Forwards a HEAD request to the external API server specified by the url
query parameter. Used to check resource availability and headers without
fetching the full response body.
tags:
- Proxy
parameters:
- $ref: '#/components/parameters/proxyUrl'
responses:
'200':
description: Response headers from the upstream API server.
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/ProxyError'
'403':
description: Forbidden.
content:
application/json:
schema:
$ref: '#/components/schemas/ProxyError'
'500':
description: Upstream connection failure.
content:
application/json:
schema:
$ref: '#/components/schemas/ProxyError'
components:
parameters:
proxyUrl:
name: url
in: query
required: true
description: >-
The fully qualified URL of the upstream API endpoint to proxy the
request to. Must be a valid absolute URL. The target origin must be
permitted by the proxy's allowedOrigins configuration, if set.
schema:
type: string
format: uri
example: 'https://api.example.com/v1/users'
schemas:
ProxyError:
type: object
description: >-
Error message returned by the Fumadocs proxy when a request cannot be
forwarded or the upstream server cannot be reached.
required:
- message
properties:
message:
type: string
description: Human-readable description of the proxy error.
example: '[Proxy] The origin "https://api.example.com" is not allowed.'