Mixedbread

TypeScript SDK

Introduction

The Mixedbread TypeScript SDK provides type-safe access to our API with full IntelliSense support, built-in error handling, and modern JavaScript features.

Installation

Installation
npm install @mixedbread/sdk

Quick Start

Get started with a simple example:

Basic Usage
import { Mixedbread } from "@mixedbread/sdk";
 
// Initialize client with API key
const mxbai = new Mixedbread({
    apiKey: process.env.MIXEDBREAD_API_KEY!,
});
 
// Generate embeddings
const embeddings = await mxbai.embed({
    model: "mixedbread-ai/mxbai-embed-large-v1",
    input: ["Hello, world!", "How are you?"]
});
 
console.log(`Generated ${embeddings.data.length} embeddings`);

Configuration

The Mixedbread constructor accepts the following options:

interface MixedbreadOptions {
    apiKey: string;
    maxRetries?: number;
    timeout?: number;
    baseURL?: string;
}
  • apiKey: Your Mixedbread API key (required)
  • maxRetries: Maximum number of retries for failed requests (default: 3)
  • timeout: Request timeout in milliseconds (default: 30000)
  • baseURL: Custom base URL for API requests (default: )

Error Handling

Use try/catch blocks to handle errors:

import { MixedbreadError, RateLimitError } from "@mixedbread/sdk";
 
try {
    const embeddings = await mxbai.embed({
        model: "mixedbread-ai/mxbai-embed-large-v1",
        input: ["Example text"],
    });
} catch (err) {
    if (err instanceof RateLimitError) {
        console.error(`Rate limit exceeded. Retry after ${err.retryAfter} seconds`);
    } else if (err instanceof MixedbreadError) {
        console.error(`API Error: ${err.message}`);
        console.error(`Status Code: ${err.statusCode}`);
    } else {
        console.error(`Unexpected error: ${err}`);
    }
}

Available Services

The SDK provides type-safe access to all Mixedbread API endpoints:

ServiceDescriptionExample Usage
mxbai.embed()Generate text embeddingsawait mxbai.embed({ model: "...", input: ["text"] })
mxbai.rerank()Rerank document listsawait mxbai.rerank({ query: "...", documents: [...] })
mxbai.vectorStoresManage vector storesawait mxbai.vectorStores.create({ name: "..." })
mxbai.vectorStores.filesManage store filesawait mxbai.vectorStores.files.create(id, { ... })
mxbai.filesUpload and manage filesawait mxbai.files.create({ file: stream })
mxbai.parsing.jobsParse documentsawait mxbai.parsing.jobs.create({ file_id: "..." })

Environment Setup

Using Environment Variables

Environment Configuration
# Set your API key
export MIXEDBREAD_API_KEY="your_api_key_here"
 
# Optional: Custom base URL
export MIXEDBREAD_BASE_URL="https://api.mixedbread.com"
Environment-based Configuration
import { Mixedbread } from "@mixedbread/sdk";
 
// Using environment variables
const mxbai = new Mixedbread({
    apiKey: process.env.MIXEDBREAD_API_KEY!,
    baseURL: process.env.MIXEDBREAD_BASE_URL,
});
 
// With validation
if (!process.env.MIXEDBREAD_API_KEY) {
    throw new Error("MIXEDBREAD_API_KEY environment variable is required");
}

Framework Integration

Next.js API Route
// pages/api/embeddings.ts
import { Mixedbread } from "@mixedbread/sdk";
import type { NextApiRequest, NextApiResponse } from "next";
 
const mxbai = new Mixedbread({
    apiKey: process.env.MIXEDBREAD_API_KEY!,
});
 
export default async function handler(req: NextApiRequest, res: NextApiResponse) {
    try {
        const { input } = req.body;
        const embeddings = await mxbai.embed({
            model: "mixedbread-ai/mxbai-embed-large-v1",
            input
        });
        res.status(200).json(embeddings);
    } catch (error) {
        res.status(500).json({ error: "Failed to generate embeddings" });
    }
}

Resources

Documentation

Support

Happy building with TypeScript! 🔷🍞

Python SDK
Learn how to install and configure Mixedbread's Python SDK for interacting with our API services.

Last updated: June 11, 2025