Skip to main content
Using a coding agent? Point it to docs.freeplay.ai/llms.txt for LLM-optimized documentation.

​
Installation

We offer the SDK in several popular programming languages. 
pip install freeplay

npm install freeplay

<!-- 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>

// Add the Freeplay SDK to your build.gradle.kts
dependencies {
   implementation("ai.freeplay:client:x.x.xx")
}
The Python and TypeScript SDKs are open source. View the source, report issues, or contribute on GitHub: freeplay-python · freeplay-node

​
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).
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 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 
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"
)

import Freeplay from "freeplay";

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

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)
                                );

// create the freeplay client
val fpClient = Freeplay(
  Freeplay.Config()
    .freeplayAPIKey(freeplayApiKey)
    .customerDomain(customerDomain)
)
Production Setup: For production deployments, consider using 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.
For API rate limits and payload constraints, see Platform Limits.