> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Libraries & SDKs

> Integrate Gloo AI into your applications using the official OpenAI libraries.

Gloo AI is **OpenAI-compatible**, so you can use the official OpenAI SDKs for Python and Node.js without learning a new syntax. Gloo supports both the **Responses API** (recommended for new integrations) and **Chat Completions**.

The key difference is authentication. Gloo uses OAuth2 client credentials rather than a static API key. Gloo also extends the API with platform-specific capabilities not found in the OpenAI specification. The [compatibility matrix](#compatibility-matrix) below covers both.

<Note>
  **Recommended:** build new integrations on the [Responses API (v1)](/api-guides/responses-v1). With the OpenAI SDK, point the client at the `/ai/v1` base URL and call `responses.create`:

  ```python theme={null}
  client = OpenAI(
      api_key=get_access_token(),
      base_url="https://platform.ai.gloo.com/ai/v1",
  )
  resp = client.responses.create(
      model="gloo-anthropic-claude-sonnet-4.6",
      input="Hello world!",
  )
  print(resp.output_text)
  ```

  The Chat Completions examples below use the `/ai/v2` base URL and remain fully supported. (Note: `/ai/v1` routes to the Responses API — use `/ai/v2` for `chat.completions`.)
</Note>

## Prerequisites: Authentication

Before using the SDK, you need to obtain an **access token** using your Client ID and Client Secret. Gloo AI uses OAuth2 client credentials flow—there are no long-lived API keys.

<Steps>
  <Step title="Get your credentials">
    Obtain your **Client ID** and **Client Secret** from the [API Credentials page](/studio/manage-api-credentials) in Gloo AI Studio.
  </Step>

  <Step title="Exchange for access token">
    Use your credentials to get a temporary bearer token (expires in 1 hour).
  </Step>

  <Step title="Use token in SDK">
    Pass the access token as the `api_key` parameter in the OpenAI client.
  </Step>
</Steps>

<Warning>
  Access tokens expire after **1 hour**. Your application must handle token refresh. See the [Authentication Tutorial](/tutorials/authentication) for complete token management patterns.
</Warning>

## Python

The Python library is the standard for AI engineering and data science.

<Steps>
  <Step title="Install the libraries">
    Use pip to install the OpenAI package and requests for token exchange.

    ```bash theme={null}
    pip install openai requests python-dotenv
    ```
  </Step>

  <Step title="Set up environment variables">
    Create a `.env` file with your credentials:

    ```bash theme={null}
    GLOO_CLIENT_ID=your_client_id_here
    GLOO_CLIENT_SECRET=your_client_secret_here
    ```
  </Step>

  <Step title="Get access token and configure the client">
    Exchange your credentials for an access token, then initialize the OpenAI client.

    ```python theme={null}
    import os
    import requests
    from openai import OpenAI
    from dotenv import load_dotenv

    load_dotenv()

    # Step 1: Exchange credentials for access token
    def get_access_token():
        response = requests.post(
            "https://platform.ai.gloo.com/oauth2/token",
            headers={"Content-Type": "application/x-www-form-urlencoded"},
            data={"grant_type": "client_credentials", "scope": "api/access"},
            auth=(os.getenv("GLOO_CLIENT_ID"), os.getenv("GLOO_CLIENT_SECRET"))
        )
        response.raise_for_status()
        return response.json()["access_token"]

    # Step 2: Initialize OpenAI client with Gloo AI
    client = OpenAI(
        api_key=get_access_token(),  # Use access token as api_key
        base_url="https://platform.ai.gloo.com/ai/v2"
    )

    # Step 3: Make a request
    completion = client.chat.completions.create(
        model="gloo-anthropic-claude-sonnet-4.5",
        messages=[
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user", "content": "Hello world!"}
        ]
    )

    print(completion.choices[0].message.content)
    ```
  </Step>
</Steps>

<Tip>
  For production applications, implement token caching and automatic refresh. See the [Authentication Tutorial](/tutorials/authentication) for a complete `TokenManager` class.
</Tip>

## Node.js / TypeScript

Perfect for full-stack developers and web applications.

<Steps>
  <Step title="Install the libraries">
    ```bash theme={null}
    npm install openai axios dotenv
    ```
  </Step>

  <Step title="Set up environment variables">
    Create a `.env` file with your credentials:

    ```bash theme={null}
    GLOO_CLIENT_ID=your_client_id_here
    GLOO_CLIENT_SECRET=your_client_secret_here
    ```
  </Step>

  <Step title="Get access token and configure the client">
    Exchange your credentials for an access token, then initialize the OpenAI client.

    ```typescript theme={null}
    import OpenAI from "openai";
    import axios from "axios";
    import * as dotenv from "dotenv";

    dotenv.config();

    // Step 1: Exchange credentials for access token
    async function getAccessToken(): Promise<string> {
      const response = await axios.post(
        "https://platform.ai.gloo.com/oauth2/token",
        "grant_type=client_credentials&scope=api/access",
        {
          headers: { "Content-Type": "application/x-www-form-urlencoded" },
          auth: {
            username: process.env.GLOO_CLIENT_ID!,
            password: process.env.GLOO_CLIENT_SECRET!,
          },
        }
      );
      return response.data.access_token;
    }

    async function main() {
      // Step 2: Initialize OpenAI client with Gloo AI
      const client = new OpenAI({
        apiKey: await getAccessToken(), // Use access token as apiKey
        baseURL: "https://platform.ai.gloo.com/ai/v2",
      });

      // Step 3: Make a request
      const completion = await client.chat.completions.create({
        model: "gloo-anthropic-claude-sonnet-4.5",
        messages: [{ role: "user", content: "Say this is a test" }],
      });

      console.log(completion.choices[0].message.content);
    }

    main();
    ```
  </Step>
</Steps>

<Tip>
  For production applications, implement token caching and automatic refresh. See the [Authentication Tutorial](/tutorials/authentication) for complete token management patterns.
</Tip>

## OpenAI Compatibility

Gloo AI's primary completions endpoint (`/ai/v2/chat/completions`) is shaped like OpenAI Chat Completions, so any client that accepts a custom `base_url` and `api_key` works with minimal changes. The table below maps standard fields to Gloo AI equivalents and highlights differences unique to the platform.

### Compatibility Matrix

| Capability                 | OpenAI                      | Gloo AI                                                                                                                           |
| :------------------------- | :-------------------------- | :-------------------------------------------------------------------------------------------------------------------------------- |
| **Authentication**         | Static API key              | OAuth2 bearer token (1-hr TTL) — pass as `api_key`                                                                                |
| **Base URL**               | `https://api.openai.com/v1` | `https://platform.ai.gloo.com/ai/v2`                                                                                              |
| `messages`                 | Required                    | Required — same format                                                                                                            |
| `model`                    | Required                    | Required by the SDK client; omit only when using `auto_routing` or `model_family` via direct HTTP                                 |
| `stream`                   | Supported                   | Supported                                                                                                                         |
| `temperature`              | Supported                   | Supported                                                                                                                         |
| `max_tokens`               | Supported                   | Supported                                                                                                                         |
| `tools` / `tool_choice`    | Supported                   | Supported                                                                                                                         |
| `auto_routing`             | Not supported               | **Gloo-specific** — let Gloo pick the best model automatically                                                                    |
| `model_family`             | Not supported               | **Gloo-specific** — pick by provider (`openai`, `anthropic`, `google`, `open source`)                                             |
| `tradition`                | Not supported               | **Gloo-specific** — theological perspective filter (`evangelical`, `catholic`, `mainline`)                                        |
| Response routing metadata  | Not included                | **Gloo-specific** — `provider`, `model_family`, `routing_mechanism`, `routing_tier`, `routing_confidence` added to every response |
| Grounded (RAG) completions | Not supported               | **Gloo-specific** — separate path `/v2/chat/completions/grounded`; `base_url` and `model` differ                                  |

<Note>
  Exactly one routing mechanism must be specified on every V2 request: `auto_routing: true`, `model`, or `model_family`. Unlike the OpenAI API, `model` is not always required—set `auto_routing: true` to have Gloo choose the best model automatically.
</Note>

### Passing Gloo-Specific Parameters

How you pass Gloo-specific fields depends on whether you're specifying a model directly or using Gloo's routing.

**Using a model directly with optional filters (e.g. `tradition`)**

When `model` is present, the SDK is satisfied and you only need to forward the extra Gloo fields. In Python, use `extra_body`. In TypeScript, the OpenAI SDK doesn't have `extra_body`, so use the client's low-level `.post()` method instead.

<CodeGroup>
  ```python Python theme={null}
  response = client.chat.completions.create(
      model="gloo-anthropic-claude-haiku-4.5",
      messages=[{"role": "user", "content": "What does Ephesians 2:8-9 mean?"}],
      extra_body={"tradition": "evangelical"},
  )
  print(response.choices[0].message.content)
  ```

  ```typescript TypeScript theme={null}
  // TypeScript SDK has no extra_body; use the client's .post() instead
  const response = await (client as any).post("/chat/completions", {
    body: {
      model: "gloo-anthropic-claude-haiku-4.5",
      messages: [{ role: "user", content: "What does Ephesians 2:8-9 mean?" }],
      tradition: "evangelical",
    },
  });
  console.log(response.choices[0].message.content);
  ```
</CodeGroup>

**Using Gloo routing (`auto_routing` or `model_family`)**

Both SDKs enforce `model` as a required argument client-side. Since Gloo's routing modes are designed to be used without a `model` field, you need to bypass the SDK validation entirely and call the API directly.

<CodeGroup>
  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://platform.ai.gloo.com/ai/v2/chat/completions",
      headers={
          "Authorization": f"Bearer {get_access_token()}",
          "Content-Type": "application/json",
      },
      json={
          "messages": [{"role": "user", "content": "What does Ephesians 2:8-9 mean?"}],
          "auto_routing": True,
          "tradition": "evangelical",
      },
  )
  response.raise_for_status()
  print(response.json()["choices"][0]["message"]["content"])
  ```

  ```typescript TypeScript theme={null}
  const response = await (client as any).post("/chat/completions", {
    body: {
      messages: [{ role: "user", content: "What does Ephesians 2:8-9 mean?" }],
      auto_routing: true,
      tradition: "evangelical",
    },
  });
  console.log(response.choices[0].message.content);
  ```
</CodeGroup>

<Note>
  The Grounded Completions endpoint uses a different base URL (`https://platform.ai.gloo.com/ai`, without `/v2`) and requires `rag_publisher` and other Gloo-specific fields. Use the same direct HTTP approach above. See the [Grounded Completions guide](/api-guides/grounded-completions) for full details.
</Note>

## GlooCode — AI Coding Agent

If you want a fully autonomous coding agent rather than editor autocomplete, check out [GlooCode](/gloocode/overview). It uses the same Gloo AI credentials and models, but runs as a standalone terminal agent that can plan, build, test, and commit code on its own — at up to 60–70% lower cost than equivalent direct-provider pricing.

## Vibe Coding & Editor Setup

Because Gloo AI adheres to open standards, you can use it directly inside AI-native code editors (like **Cursor**, **Windsurf**, or **VS Code**) to "vibe code" with values-aligned models.

<CardGroup cols={2}>
  <Card title="Cursor / VS Code" icon="pen-nib">
    1. Go to **Settings > Models**
    2. Add a Custom Provider
    3. Set URL: `https://platform.ai.gloo.com/ai/v2`
    4. Generate an access token and paste it as the API key
  </Card>

  <Card title="Agent Frameworks" icon="robot">
    Compatible with **LangChain**, **CrewAI**, and **AutoGen** by setting the `openai_api_base` parameter and providing an access token.
  </Card>
</CardGroup>

<Warning>
  Access tokens expire after 1 hour. For editor integrations, you'll need to generate a new token periodically via the [API Credentials page](/studio/manage-api-credentials) or programmatically using the OAuth2 flow.
</Warning>

<Tip>
  **Connect our docs to your AI tools via MCP.** Get accurate API references, model IDs, and code examples directly in your editor or AI assistant. See the [MCP Integration](/api-guides/mcp-integration) guide to set up in one click.
</Tip>

## Supported Models

When using the SDK, you must use the exact Model IDs supported by Gloo AI. Here are some commonly used models:

| Provider        | Model ID                           |
| :-------------- | :--------------------------------- |
| **Anthropic**   | `gloo-anthropic-claude-sonnet-4.5` |
| **Anthropic**   | `gloo-anthropic-claude-haiku-4.5`  |
| **OpenAI**      | `gloo-openai-gpt-5-mini`           |
| **Google**      | `gloo-google-gemini-2.5-flash`     |
| **Open Source** | `gloo-meta-llama-3.1-8b-instruct`  |

<Tip>
  See the [Supported Models](/api-guides/supported-models) page for the full list of available Model IDs and their capabilities.
</Tip>