docs: add Neon AI Gateway integration guide

[mezotv]

Ticket

No ticket. Opening this directly as a documentation contribution, per CONTRIBUTING_GUIDELINES.md (GitHub Flow, all changes via pull request).

Component/Service

What part of Helicone does this affect?

• Web (Frontend)
• Jawn (Backend)
• Worker (Proxy)
• Bifrost (Marketing)
• AI Gateway
• Packages
• Infrastructure/Docker
• Documentation

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Performance improvement
• Refactoring

Deployment Notes

• No special deployment steps required
• Database migrations need to run
• Environment variable changes required
• Coordination with other teams needed

Context

Neon AI Gateway is an OpenAI-compatible inference endpoint provided by Neon, currently in beta. There is no page in the docs today explaining how to get those requests into Helicone, and the obvious first guess (look for Neon in the AI Gateway model registry) does not work, because Neon is not a registered provider there.

This adds one page that answers the question directly: use the generic Helicone Gateway proxy and name the Neon branch host in Helicone-Target-Url, which is the mechanism getting-started/integration-method/gateway.mdx already documents for any OpenAI-compatible host. The page says up front that the model-registry path is not available, so a reader does not go looking for it.

Nothing in the AI Gateway model registry is touched. There are no changes under packages/cost, no new provider entry, and no claim that Neon is natively supported.

Changes

Insertion-only, two files, 131 additions and 0 deletions:

• docs/getting-started/integration-method/neon.mdx (new, 130 lines) — Steps walkthrough, cURL / Node.js / Python examples, rate-limit and cost sections.
• docs/docs.json (+1 line) — one nav entry, "getting-started/integration-method/neon", placed alphabetically between nebius and novita.

Every host, key, and token in the examples is an explicit placeholder (https://<your-neon-branch-host>, <your-helicone-api-key>). No real hostnames or credentials appear anywhere in the diff.

Limitations documented on the page

The page states the constraints of this integration rather than only the happy path:

• Unapproved-domain rate limits. Neon branch hosts are not on the approved domain list, and every Neon branch has a different hostname, so requests fall under the documented unapproved-domain limits of 10,000 requests per day and 1 request per second. The page links gateway.mdx#approved-domains and points readers at engineering@helicone.ai / Discord to get a domain approved.
• Manual logger as the higher-throughput alternative, linked, for anyone who needs more than that before a domain is approved.
• No cost figure. Cost calculation is not enabled for Neon branch hosts, so requests logged this way show token counts without a cost. The page notes the automated mapper still resolves the schema and that mapping runs on a job every 24 hours.
• The page claims only chat completions, streaming, and GET /v1/models. It makes no tool-calling, structured-output, embeddings, image, or audio claim.

Known gap a reviewer may want closed

Neon translates its gemini-* models into a Gemini request shape that has no stream_options field, so a caller who enables usage reporting in the stream against a gemini- model will get a 400 back from Neon. Helicone is a pass-through proxy here and none of the page's own examples set stream_options, so nothing on the page is wrong as written, but gemini-3-flash does appear in the model-ID list. Happy to add a one-line note about it if you would like it called out.

Separately, the page does not import /snippets/legacy-provider-warning.mdx, which 23 of the 33 pages in getting-started/integration-method/ do include. That looked deliberate rather than an oversight: the warning tells readers to switch to the AI Gateway, and the AI Gateway is exactly the path that is not available for Neon. The generic-method pages (gateway, custom, the manual loggers) also omit it. Glad to add it if you would rather every provider page carry it.

Checks run

Run locally with the repo's own pinned Mintlify CLI against docs/:

• mint validate (strict build validation). Exits 1 with 3 warnings, all Could not find file /snippets/generate-key.mdx from integrations/{llama,nvidia,xai}/javascript.mdx. Verified identical on unmodified main, so this branch introduces no new warnings. Neither log mentions the new page.
• mint broken-links cannot complete on this repo, before or after this change: it aborts with Syntax error - Unable to parse guides/cookbooks/cost-tracking.mdx - URIError: URI malformed. Reproduced on unmodified main, so it is pre-existing and unrelated. Flagging it since it may be worth a separate fix.
• Link targets checked by hand instead, given the above. All four relative targets resolve to real files (gateway.mdx, gateway/overview.mdx, manual-logger-typescript.mdx), and the #approved-domains anchor exists in gateway.mdx. All 8 external documentation links return 200.
• docs.json parses as JSON, and the new nav entry appears exactly once.
• Snippets. Both bash blocks pass bash -n, the Python block compiles, MDX frontmatter parses, code fences are even, and Note / Steps / Step / Tabs / Tab / Info all balance.
• Facts cross-checked against this repo's own docs, not assumed: the unapproved-domain limits, the absence of Neon from the approved-domain table, the Helicone-Target-Url mechanism, and the 24-hour mapper job all come from gateway.mdx. Neon's absence from the model registry was confirmed against packages/cost.

Disclosure

The examples on this page have not been executed end to end against a live Neon branch. The Helicone-side behaviour is taken from this repository's own documentation, and the Neon-side details from Neon's published documentation. Everything that could be checked statically is listed above; the request path itself is unverified, so please treat the snippets as needing a maintainer's eye.

Opening as a draft. Happy to adjust placement, wording, or the two open items above.

[vercel]

@mezotv is attempting to deploy a commit to the Helicone Team on Vercel.

A member of the Team first needs to authorize it.

[greptile-apps]

Your trial has ended. Reactivate Greptile to resume code reviews.