---
title: "OpenAI Base URL Integration"
canonical: "https://helm.docs.mindburn.org/integrations/openai-baseurl"
source: "helm-ai-enterprise/docs/public/product/integrations/openai-baseurl.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/product/integrations/openai-baseurl.md"
section: "reference"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-04"
checksum_sha256: "sha256:b0328901a3f738f3414f49f74b4686f7e26f4dc844d482b984969280e65f9d27"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Integration: OpenAI Base URL

## Audience

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| A link or route is missing from the docs website | Check `docs/public-docs.manifest.json`, `llms.txt`, search, and the per-page Markdown export before changing navigation. |
| A claim is not backed by code or tests | Remove the claim or add the missing code, example, schema, or validation command before publishing. |

Use this path when an app already uses an OpenAI-compatible client and you want the smallest possible HELM integration. The app keeps the same client library and changes only the base URL so requests cross HELM before the upstream provider.

## Runnable Python Example

```python
from openai import OpenAI

client = OpenAI(base_url="http://localhost:9090/v1")

response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Return the active governance status."}],
)

print(response.choices[0].message.content)
print(response.response.headers.get("X-Helm-Receipt-ID"))
```

Expected response headers on the governed path:

```text
X-Helm-Receipt-ID: rec_...
X-Helm-Output-Hash: sha256:...
X-Helm-Lamport-Clock: ...
```

The exact values are runtime-specific. The required behavior is that the response is linked to a HELM decision and evidence path.

## Runnable TypeScript Example

```ts
import OpenAI from "openai";

const openai = new OpenAI({
  baseURL: "http://localhost:9090/v1",
});

const response = await openai.chat.completions.create({
  model: "gpt-4",
  messages: [{ role: "user", content: "Summarize the active policy." }],
});

console.log(response.choices[0]?.message?.content);
```

## Deny Check

Do not finish setup until you have tested one denied action. Use an unknown tool or a tool argument that the active policy bundle does not allow. A correct setup returns a denial response with a reason code and receipt or decision reference. An allow on an unknown tool means the policy bundle or route is wrong.

## Failure Modes

| Symptom | Cause | Fix |
| --- | --- | --- |
| no `X-Helm-*` headers | request bypassed HELM | log the request host and confirm the client points at HELM |
| provider key error | upstream key is configured on the wrong side of the boundary | follow your deployment model: sidecar-held upstream key or explicit pass-through |
| deny for all calls | identity, policy bundle, or budget gate is missing | inspect denial reason code and load the intended bundle |
| streaming stalls | proxy, client, or upstream does not preserve SSE | test non-streaming first, then check gateway timeout and buffering |

## Source Truth

This guide should stay aligned with `helm-ai-kernel/docs/INTEGRATIONS/openai_baseurl.md`, retained examples under `examples/*openai*baseurl*`, and the runtime proxy implementation. Do not document a header or endpoint here unless the runtime or test suite emits it.

## Diagram

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        source["Integration: OpenAI Base URL"]
        s3["Failure Modes"]
        output["Reader outcome"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        s0["Runnable Python Example"]
        s1["Runnable TypeScript Example"]
        s2["Deny Check"]
    end

    %% Operational Flow Edges
    source --> s0
    s0 --> s1
    s1 --> s2
    s2 --> s3
    s3 --> output

    %% Premium Styling Rules
    style s0 fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style s1 fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style s2 fill:#e53e3e,stroke:#9b2c2c,stroke-width:2px,color:#fff
```


## Operational Readiness

Use this page as the public operating layer for **OpenAI Base URL Integration**. The source of truth is `helm-ai-enterprise/docs/public/product/integrations/openai-baseurl.md`; if this page and the implementation disagree, update the source-backed doc and rerun the validation command before publishing.

Before relying on this surface, confirm three things: the source path above still exists, the referenced commands or contracts are still present in the owning repo, and the docs-platform export surfaces still show this page in search, Markdown, `llms-full.txt`, and MCP without exposing protected routes.

Validation command: `corepack pnpm run docs:coverage && corepack pnpm run docs:truth`. For website parity, also run `npm run exports:boundary` and `npm run thin-pages:check` from `docs-platform`.

### Expected Output

A reader should leave with a concrete next action, the source file or contract to inspect, the command that proves the claim, and a clear boundary for what is public versus protected. For reference pages, the expected output is a correctly scoped request, schema, command, or diagnostic path. For operations pages, the expected output is a reproducible readiness or failure signal that can be attached to an evaluation or support thread.

### Failure Modes

If the validation command fails, do not patch this page in isolation. First identify whether the drift is in code, generated contracts, source-owner docs, or the docs manifest. If the public page needs a protected deep link, describe the protected document by name instead of exposing its route. Commercial operator details, tenant data, key ceremonies, and deployment-sensitive internals stay in protected customer or staff docs; this public page only exposes the safe developer contract.