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

# Setup

> Install and configure the Freeplay SDK for Python, Node.js, or Java/Kotlin.

<Tip>
  **Using a coding agent?** Point it to [docs.freeplay.ai/llms.txt](https://docs.freeplay.ai/llms.txt) for LLM-optimized documentation.
</Tip>

# Installation

We offer the SDK in several popular programming languages.

<CodeGroup>
  ```python python theme={null}
  pip install freeplay
  ```

  ```node node theme={null}
  npm install freeplay
  ```

  ```xml java theme={null}
  <!-- Add the Freeplay SDK to your pom.xml -->
  <dependency>
      <groupId>ai.freeplay</groupId>
      <artifactId>client</artifactId>
      <version>x.x.xx</version>
  </dependency>
  <!-- If you are using Vertex/Gemini, add the following dependency as well. -->
  <!-- If you are not using Gemini models, you do NOT need this dependency. -->
  <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>google-cloud-vertexai</artifactId>
      <!-- This is the current version Freeplay supports at the time of this writing. -->
      <!-- It may need to be updated to a newer version. -->
      <version>1.5.0</version>
  </dependency>
  ```

  ```kotlin kotlin theme={null}
  // Add the Freeplay SDK to your build.gradle.kts
  dependencies {
     implementation("ai.freeplay:client:x.x.xx")
  }
  ```
</CodeGroup>

<Note>
  The Python and TypeScript SDKs are open source. View the source, report issues, or contribute on GitHub:
  [freeplay-python](https://github.com/freeplayai/freeplay-python) ·
  [freeplay-node](https://github.com/freeplayai/freeplay-node)
</Note>

# Freeplay Client

The Freeplay client object will be your point of entry for all SDK usage. For most users, the base freeplay domain will be `https://app.freeplay.ai` with api exposed at `https://app.freeplay.ai/api`.

## Custom Domain

If your organization has been assigned a custom Freeplay domain it will look like this: `https://acme.freeplay.ai` and your SDK connection URL will have an additional `/api` appended to it (e.g., `https://acme.freeplay.ai/api` or `https://app.freeplay.ai/api`).

<Note>
  The `api_base` (Python) or `baseUrl` (Node.js) parameter is **required** and must match your Freeplay instance URL. Make sure to include the `/api` suffix for all domains.
</Note>

Note the rest of the documentation will use `https://app.freeplay.ai`.

## Authentication

Freeplay authenticates your API request using your API Key which can be managed through the Freeplay application at `https://app.freeplay.ai/settings/api-access`

## Client Instantiation

The first step to using Freeplay is to create a client

<CodeGroup>
  ```python python theme={null}
  from freeplay import Freeplay
  import os

  # create a freeplay client object
  fp_client = Freeplay(
      freeplay_api_key=os.getenv("FREEPLAY_API_KEY"),
      api_base="https://app.freeplay.ai/api"
  )
  ```

  ```node node theme={null}
  import Freeplay from "freeplay";

  // create your freeplay client
  const fpClient = new Freeplay({
      freeplayApiKey: process.env["FREEPLAY_API_KEY"],
      baseUrl: "https://app.freeplay.ai/api",
  });
  ```

  ```java java theme={null}
  import ai.freeplay.client.thin.Freeplay;

  String projectId = System.getenv("FREEPLAY_PROJECT_ID");
  String customerDomain = System.getenv("FREEPLAY_CUSTOMER_NAME");

  Freeplay fpClient = new Freeplay(Config()
                                   .freeplayAPIKey(freeplayApiKey)
                                   .customerDomain(customerDomain)
                                  );
  ```

  ```kotlin kotlin theme={null}
  // create the freeplay client
  val fpClient = Freeplay(
    Freeplay.Config()
      .freeplayAPIKey(freeplayApiKey)
      .customerDomain(customerDomain)
  )
  ```
</CodeGroup>

<Tip>
  **Production Setup**: For production deployments, consider using [Prompt Bundling](/core-concepts/prompt-management/prompt-bundling) to fetch prompts from local files instead of the server. Many teams configure separate clients for different environments—server-based fetching for dev/staging, and bundled prompts for production.
</Tip>

<Note>
  For API rate limits and payload constraints, see [Platform Limits](/openapi/limits).
</Note>