# Mixpeek API

> Multimodal AI infrastructure for processing and retrieving unstructured data.

## API Overview

Mixpeek transforms raw files (images, videos, audio, PDFs, text) into searchable, AI-ready assets with vector embeddings and structured metadata.

## Quick Links

- OpenAPI Spec: https://api.mixpeek.com/docs/openapi.json
- Interactive Docs: https://api.mixpeek.com/docs
- Full Documentation: https://mixpeek.com/docs
- Python SDK: pip install mixpeek
- JavaScript SDK: npm install mixpeek-sdk

## Authentication

All requests require Bearer token authentication:
```
Authorization: Bearer YOUR_API_KEY
X-Namespace: ns_your_namespace_id
```

## Core Endpoints

### Namespaces (Tenant Isolation)
- POST /v1/namespaces - Create namespace
- GET /v1/namespaces - List namespaces
- GET /v1/namespaces/{namespace_id} - Get namespace

### Buckets (Raw File Storage)
- POST /v1/buckets - Create bucket
- GET /v1/buckets - List buckets
- POST /v1/buckets/{bucket_id}/objects - Add object to bucket
- POST /v1/buckets/{bucket_id}/uploads - Upload file directly

### Collections (Processing Pipelines)
- POST /v1/collections - Create collection with feature extractors
- GET /v1/collections - List collections
- POST /v1/collections/{collection_id}/documents - List processed documents

### Retrievers (Search Pipelines)
- POST /v1/retrievers - Create retriever with stages
- GET /v1/retrievers - List retrievers
- POST /v1/retrievers/{retriever_id}/execute - Execute search query

### Taxonomies (Classification)
- POST /v1/taxonomies - Create taxonomy
- GET /v1/taxonomies - List taxonomies

## Common Workflow

1. Create namespace: POST /v1/namespaces
2. Create bucket: POST /v1/buckets
3. Create collection with extractors: POST /v1/collections
4. Upload files: POST /v1/buckets/{id}/uploads
5. Create retriever: POST /v1/retrievers
6. Search: POST /v1/retrievers/{id}/execute

## Feature Extractors

Available extractors for collections:
- multimodal: Dense vector embeddings (text, image, video, audio)
- image: Object detection, scene classification, OCR
- text: NER, keyword extraction, embeddings
- document: PDF parsing, table extraction
- face_identity: Facial recognition and clustering
- web_scraper: URL content extraction

## Retriever Stages

Configurable pipeline stages:
- feature_search: Vector similarity search
- attribute_filter: Metadata filtering
- rerank: Result reranking with cross-encoders
- llm_filter: LLM-based filtering
- aggregate: Grouping and aggregation
- taxonomy_enrich: Classification enrichment

## Response Format

All responses follow JSON format with:
- results: Array of items for list endpoints
- pagination: next_page_token for pagination
- error: Error details if request fails

## Rate Limits

- Free tier: 5,000 API calls/month
- Usage-based: Unlimited with per-call pricing
- Enterprise: Custom limits

## Support

- Docs: https://mixpeek.com/docs
- GitHub: https://github.com/mixpeek
- Email: support@mixpeek.com