Mixpeek TypeScript/JavaScript SDK

Official TypeScript/JavaScript SDK for the Mixpeek multimodal data processing and retrieval platform.

Features

• ✅ 100% Type-Safe - Built with TypeScript for complete type safety
• ✅ Auto-Generated - Always up-to-date with the latest Mixpeek API
• ✅ Runtime Validation - Zod schemas for request/response validation
• ✅ Modern - Supports both CommonJS and ESM
• ✅ Promise-Based - Clean async/await API
• ✅ Comprehensive - Covers all Mixpeek API endpoints
• ✅ Developer-Friendly - Intuitive method names and excellent autocomplete

Installation

# npm
npm install mixpeek

# yarn
yarn add mixpeek

# pnpm
pnpm add mixpeek

Quick Start

import { Mixpeek } from 'mixpeek';

// Initialize the client
const client = new Mixpeek({
  apiKey: process.env.MIXPEEK_API_KEY, // Get your API key at https://dash.mixpeek.com
  namespace: 'my-namespace' // Optional: for multi-tenant isolation
});

// List collections
const collections = await client.collections.listCollections();
console.log('Collections:', collections);

// Create a collection
const newCollection = await client.collections.createCollection({
  alias: 'my-collection',
  description: 'My first collection'
});

// Execute a retriever
const results = await client.retrievers.executeRetriever({
  retrieverId: 'ret_abc123',
  query: 'find relevant documents'
});

Configuration

Environment Variables

The SDK can be configured using environment variables:

# Required
MIXPEEK_API_KEY=sk_your_api_key_here

# Optional
MIXPEEK_BASE_URL=https://api.mixpeek.com  # Default
MIXPEEK_NAMESPACE=default                 # Default

Constructor Options

const client = new Mixpeek({
  apiKey: 'sk_...',              // Required (or set MIXPEEK_API_KEY)
  baseUrl: 'https://...',        // Optional: custom API endpoint
  namespace: 'my-namespace',     // Optional: namespace for isolation
  timeout: 30000,                // Optional: request timeout in ms
  axiosConfig: {                 // Optional: additional axios config
    // Any axios configuration options
  }
});

Usage Examples

Collections

// Create a collection
const collection = await client.collections.createCollection({
  alias: 'my-collection',
  description: 'Store multimodal documents',
  metadata: { project: 'demo' }
});

// Get a collection
const retrieved = await client.collections.getCollection({
  collectionIdentifier: 'my-collection'
});

// List all collections
const allCollections = await client.collections.listCollections();

// Delete a collection
await client.collections.deleteCollection({
  collectionIdentifier: 'my-collection'
});

Retrievers

// Create a retriever
const retriever = await client.retrievers.createRetriever({
  retrieverName: 'semantic-search',
  description: 'Search across all documents',
  collectionIdentifiers: ['my-collection'],
  stages: [
    {
      type: 'embed',
      model: 'openai-text-embedding-3-small'
    },
    {
      type: 'vector_search',
      top_k: 10
    }
  ]
});

// Execute a retriever
const results = await client.retrievers.executeRetriever({
  retrieverId: retriever.retrieverId,
  query: 'find relevant documents about AI'
});

// List retrievers
const retrievers = await client.retrievers.listRetrievers();

Documents

// Upload documents to a collection
const documents = await client.documents.uploadDocuments({
  collectionId: 'col_abc123',
  documents: [
    {
      url: 's3://bucket/video.mp4',
      metadata: { title: 'Demo Video' }
    },
    {
      url: 's3://bucket/image.jpg',
      metadata: { title: 'Demo Image' }
    }
  ]
});

// Search documents
const searchResults = await client.documents.searchDocuments({
  collectionId: 'col_abc123',
  query: 'search query',
  limit: 20
});

Buckets (Object Storage)

// Create a bucket
const bucket = await client.buckets.createBucket({
  alias: 'my-bucket',
  provider: 's3',
  credentials: {
    accessKeyId: 'YOUR_ACCESS_KEY',
    secretAccessKey: 'YOUR_SECRET_KEY',
    region: 'us-east-1'
  }
});

// List buckets
const buckets = await client.buckets.listBuckets();

Error Handling

The SDK provides comprehensive error handling:

try {
  const collection = await client.collections.getCollection({
    collectionIdentifier: 'non-existent'
  });
} catch (error) {
  if (error.response) {
    // API error
    console.error('Status:', error.response.status);
    console.error('Message:', error.response.data?.error?.message);
  } else if (error.request) {
    // Network error
    console.error('Network error:', error.message);
  } else {
    // Other error
    console.error('Error:', error.message);
  }
}

TypeScript Support

The SDK is built with TypeScript and provides full type definitions:

import { Mixpeek, MixpeekOptions } from 'mixpeek';
import type {
  Collection,
  Retriever,
  CreateCollectionRequest,
  CreateRetrieverRequest
} from 'mixpeek';

// All types are fully typed
const options: MixpeekOptions = {
  apiKey: 'sk_...',
  namespace: 'default'
};

const client = new Mixpeek(options);

// TypeScript will autocomplete and type-check all methods
const collection: Collection = await client.collections.createCollection({
  alias: 'typed-collection'
  // TypeScript will suggest all available fields
});

Advanced Usage

Custom Axios Configuration

const client = new Mixpeek({
  apiKey: 'sk_...',
  axiosConfig: {
    timeout: 60000,
    headers: {
      'X-Custom-Header': 'value'
    },
    proxy: {
      host: 'proxy.example.com',
      port: 8080
    }
  }
});

Updating Configuration

const client = new Mixpeek({ apiKey: 'sk_old' });

// Update API key
client.setApiKey('sk_new');

// Update namespace
client.setNamespace('new-namespace');

// Get current configuration
const config = client.getConfig();
console.log(config);
// { apiKey: 'sk_new...', baseUrl: '...', namespace: 'new-namespace' }

Raw HTTP Requests

For endpoints not yet covered by the SDK:

const client = new Mixpeek({ apiKey: 'sk_...' });

// Make a raw request
const response = await client.request({
  method: 'GET',
  url: '/v1/custom-endpoint',
  params: { limit: 10 }
});

Examples

See the examples/ directory for complete working examples:

• Quickstart - Basic usage
• Collections - Working with collections
• Retrievers - Creating and executing retrievers
• Error Handling - Comprehensive error handling

API Documentation

For complete API documentation, visit:

• API Reference: https://docs.mixpeek.com/api-reference
• Guides: https://docs.mixpeek.com/guides
• Examples: https://docs.mixpeek.com/examples

Development

Building from Source

# Clone the repository
git clone https://github.com/mixpeek/javascript-sdk.git
cd javascript-sdk

# Install dependencies
npm install

# Generate SDK from OpenAPI spec
npm run generate

# Build
npm run build

# Run tests
npm test

Regenerating the SDK

The SDK is auto-generated from the Mixpeek OpenAPI specification:

# Download latest OpenAPI spec
curl -s https://api.mixpeek.com/docs/openapi.json -o openapi.json

# Generate SDK
npm run generate

# Build
npm run build

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Support

• Documentation: https://docs.mixpeek.com
• Discord: https://discord.gg/mixpeek
• Email: [email protected]
• GitHub Issues: https://github.com/mixpeek/javascript-sdk/issues

License

MIT License - see LICENSE for details.

Changelog

See CHANGELOG.md for version history.

Built with ❤️ by the Mixpeek team

Auto-generated from OpenAPI spec using OpenAPI Generator