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

``bash


npm

npm install mixpeek

yarn

yarn add mixpeek

pnpm

pnpm add mixpeek
`

Quick Start

`typescript
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

$3

The SDK can be configured using environment variables:

`bash


Required

MIXPEEK_API_KEY=sk_your_api_key_here

Optional

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

$3

`typescript
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

$3

`typescript
// 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'
});
`

$3

`typescript
// 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();
`

$3

`typescript
// 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
});
`

$3

`typescript
// 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:

`typescript
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:

`typescript
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

$3

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

$3

`typescript
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' }
`

$3

For endpoints not yet covered by the SDK:

`typescript
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

$3

`bash


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
`

$3

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

`bash


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: support@mixpeek.com
- 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