Generating the SDK

The Sensay API provides an OpenAPI specification that allows you to automatically generate client SDKs for your preferred programming language and framework. Now that you familiarised with the API and its capabilities in the Getting started chapter, we will walk you through generating a TypeScript SDK using HeyAPI, though many other tools and languages are supported. See https://tools.openapis.org for a comprehensive list of the available tools.

1. Install HeyAPI or your preferred SDK generator

For this guide, we'll use HeyAPI, but many other generators are available depending on your needs.

From your project directory:

# Install HeyAPI
npm install @heyapi/cli

2. Generate a TypeScript SDK 

# Generate a TypeScript SDK
npx heyapi generate-sdk \
  --input="https://api.sensay.io/schema" \
  --output-dir="./sensay-sdk" \
  --language="typescript" \
  --client="fetch"


The above command generates a TypeScript SDK with the fetch client. HeyAPI supports multiple client options including axios, angular, and more.

3. Install and configure the generated SDK 

# Install the generated SDK dependencies
cd sensay-sdk
npm install

# Build the SDK
npm run build

4. Use the generated SDK in your application 

import { Configuration, DefaultApi } from './sensay-sdk';

// Configure the SDK with your organization secret and API version
const config = new Configuration({
  basePath: 'https://api.sensay.io',
  headers: {
    'X-ORGANIZATION-SECRET': 'your_secret_token',
    'X-API-Version': '2025-05-01',
    'Content-Type': 'application/json'
  }
});

// Initialize the API client
const api = new DefaultApi(config);

// Create a user
const createUser = async () => {
  try {
    const response = await api.createUser({
      id: 'test_user_id'
    });
    console.log('User created:', response);
    return response;
  } catch (error) {
    console.error('Error creating user:', error);
  }
};

// Create a replica for the user
const createReplica = async (userId: string) => {
  try {
    const response = await api.createReplica({
      name: 'My SDK Replica',
      shortDescription: 'Created with the generated SDK',
      greeting: 'Hello! I was created using a generated SDK.',
      ownerID: userId,
      private: false,
      slug: 'sdk-replica',
      llm: {
        provider: 'openai',
        model: 'gpt-4o'
      }
    });
    console.log('Replica created:', response);
    return response;
  } catch (error) {
    console.error('Error creating replica:', error);
  }
};

// Chat with a replica
const chatWithReplica = async (replicaUuid: string, userId: string) => {
  try {
    // Note: Headers are configured at the client level, but can be overridden per request
    const response = await api.chatCompletions(replicaUuid, {
      content: 'Hello, I'm using the generated SDK!'
    }, {
      headers: {
        'X-USER-ID': userId,
        'X-ORGANIZATION-SECRET': 'your_secret_token', 
        'X-API-Version': '2025-03-25',
        'Content-Type': 'application/json'
      }
    });
    console.log('Chat response:', response);
    return response;
  } catch (error) {
    console.error('Error chatting with replica:', error);
  }
};

// Example usage
const main = async () => {
  const user = await createUser();
  if (user && user.id) {
    const replica = await createReplica(user.id);
    if (replica && replica.uuid) {
      await chatWithReplica(replica.uuid, user.id);
    }
  }
};

main();

Authentication in the SDK

For all API requests, you must include the proper authentication headers as described in the Authentication documentation:

// Configure global headers for all requests
const config = new Configuration({
  basePath: 'https://api.sensay.io/v1',
  headers: {
    // Required for all requests
    'X-ORGANIZATION-SECRET': 'your_secret_token',
    'X-API-Version': '2025-03-25',
    'Content-Type': 'application/json'
  }
});

// For user-specific operations, add the X-USER-ID header to individual requests
const response = await api.someUserSpecificOperation(params, {
  headers: {
    'X-USER-ID': 'user_id'
  }
});


The X-ORGANIZATION-SECRET header is required for all API requests. For operations that involve a specific user, you must also include the X-USER-ID header.

Alternative SDK Generation Tools

While HeyAPI is a great option, there are several other tools you can use to generate SDKs:

Supported Languages and Frameworks

The OpenAPI ecosystem supports SDK generation for numerous languages and frameworks, including but not limited to:

  • TypeScript/JavaScript (Node.js, Browser, React, Angular, Vue)
  • Python
  • Java
  • C#/.NET
  • Go
  • Ruby
  • PHP
  • Swift
  • Kotlin
  • Rust
  • Dart/Flutter


For specific instructions on generating SDKs for other languages, please refer to the documentation of your chosen SDK generator.

Best Practices

  1. Version your SDK: Always specify the API version in your SDK configuration to ensure compatibility.
  2. Error handling: Implement proper error handling in your client code to catch and process API errors.
  3. Authentication: Securely store and provide your organization's secret token.
  4. Rate limiting: Implement retry mechanisms and respect API rate limits.
  5. Keep up to date: Regularly update your SDK when new API versions are released.


Never hardcode your organization's secret token in client-side code. Always use environment variables or a secure configuration management system.

Further Resources