---
title: "API reference from a URL or GraphQL"
url: "/help/buuk/api-reference-from-a-url-or-graphql"
updated: "2026-11-15T11:35:26.764Z"
---
# API reference from a URL or GraphQL

You can publish an API reference without keeping a spec file in a repository. Buuk accepts a spec from a URL, an uploaded file or pasted text, and supports OpenAPI, Swagger, AsyncAPI and GraphQL.

## Add a reference

Open your docs project → API reference → Add reference. There are three sources:

- From a URL fetches the spec over HTTPS. Use this when your spec is published by your build or your gateway.
- Upload file takes a .json, .yaml, .yml, .graphql, .graphqls file.
- Paste takes the spec text directly.

Files up to 15 MB are accepted.

## URL sources

A URL source is re-fetched so the reference keeps up with your API. Each refresh records when it last succeeded and, if it failed, the error, so a broken URL is visible rather than silently stale.

Point the URL at something stable. A build artifact, a committed file served by your docs host, or an endpoint your gateway already publishes all work; a link that changes with every deploy does not.

## GraphQL

A GraphQL reference takes the endpoint URL, and the reader-facing pages get a playground and code samples that post the document to that endpoint. For a schema, upload the SDL file or paste it, the same way as an OpenAPI document.

## What readers get

Each reference gets a landing page, grouped navigation and a page per operation with parameters, request bodies, responses and code samples. You can reorder groups, choose icons and switch the navigation style from the reference's settings.

Related: Import an OpenAPI spec; The Try It playground; Code samples and SDKs.