--- title: "List all extractors available to organization" method: GET path: "/v1/extractors" tags: ["Extractors"] --- # List all extractors available to organization `GET /v1/extractors` List all extractors available across the organization. Returns a unified view combining: - **Builtin extractors**: Core extractors shipped with Mixpeek - **Custom extractors**: Org-level custom extractors (uploaded via the upload workflow) Use `source` to filter by origin. ## Query parameters - `source` 'builtin' | 'custom' | 'all', nullable — Filter by extractor source - `include_disabled` boolean — Include disabled/undeployed custom extractors ## Response `200` Successful Response - UnifiedExtractorListResponse — Response for listing all extractors available to a namespace. - `success` boolean — Whether the request succeeded - `extractors` UnifiedExtractorResponse[], required — List of all available extractors - `feature_extractor_name` string, required — Name of the feature extractor - `version` string, required — Version of the feature extractor - `feature_extractor_id` string, required — Unique identifier (name_version) - `source` 'builtin' | 'custom' | 'community', required — The source/origin of a feature extractor. Values: BUILTIN: Core extractors shipped with Mixpeek (text, image, multimodal, etc.) CUSTOM: User-created extractors uploaded to their namespace (Enterprise only) COMMUNITY: Community-contributed extractors from the Mixpeek marketplace This field helps API consumers understand: - What level of support/maintenance to expect - Whether the extractor is available to all users or namespace-specific - Licensing and attribution requirements - `description` string, required — Human-readable description - `icon` string — Lucide-react icon name for frontend rendering - `input_schema` object, required — JSON schema for input data - `output_schema` object, required — JSON schema for output data - `parameter_schema` object, nullable — JSON schema for parameters - `type_mode` string, nullable — What input types this extractor can handle: 'type_specific' (only one type, e.g. video-only) or 'multimodal' (handles multiple types with conditional processing). Type-specific extractors cannot use automatic-typed bucket properties. - `expected_input_types` object, nullable — For type-specific extractors: maps input keys to required types (e.g., {'video': 'video', 'thumbnail': 'image'}). For multimodal extractors: null. - `inference_type` string, nullable — Kind of real-time inference this extractor provides: 'embedding', 'rerank', 'classify', 'generate', or 'general'. Determines which retriever stages are compatible. Null if the extractor is batch-only. - `supported_input_types` string[] — Supported input types (video, image, text, etc.) - `max_inputs` object — Maximum number of inputs per type - `default_parameters` object — Default parameter values - `costs` CostsInfo — Credit cost information for a feature extractor. Describes the pricing tier and standardized cost rates for using this extractor. Rates are defined using CostUnit types that align with extractor input types. - `tier` integer, required — Cost tier (1-4): 1=SIMPLE, 2=MODERATE, 3=COMPLEX, 4=PREMIUM - `tier_label` string, required — Human-readable tier label (SIMPLE, MODERATE, COMPLEX, PREMIUM) - `rates` CostRate[], required — List of cost rates for different input types this extractor processes - `unit` 'minute' | 'image' | '1k_tokens' | 'page' | 'face' | 'extraction', required — Standard billing units aligned with extractor input types. Each unit represents a measurable quantity that extractors process: - MINUTE: Video/audio duration in minutes - IMAGE: Per image processed - TOKENS_1K: Text tokens in thousands - PAGE: Document pages (PDF, etc.) - FACE: Detected faces in images/video - EXTRACTION: Flat per-operation cost - `credits_per_unit` integer, required — Number of credits charged per unit - `description` string, nullable — Human-readable description of what this rate covers - `required_vector_indexes` VectorIndexDefinition[], nullable — Vector indexes this extractor produces - `feature_uri` string, nullable — Full feature URI for this vector index. Format: mixpeek://{extractor}@{version}/{output_name}. Populated at collection creation time. Use this URI in retriever feature_filter stages. - `display_name` string, nullable — OPTIONAL. Human-friendly label for this feature output (e.g. 'face' for insightface__arcface, 'text embedding' for an e5 index). Presentation-layer vocabulary shared by Studio, docs and pricing — the technical `name` stays the URI-addressable identity and MUST still be shown/available wherever this label is used. - `name` string, required — REQUIRED. Short user-facing output name used in feature URIs. This is NOT the Qdrant collection name - it's the clean identifier for this output. Format: Simple snake_case name (e.g., 'embedding', 'video_embedding', 'sparse_embedding'). Used in feature URIs: mixpeek://{extractor}@{version}/{THIS_NAME}. Must be unique within this extractor's outputs. - `description` string, required — REQUIRED. Human-readable description of this vector output. Explain what content this output embeds and when to use it. Appears in API documentation and helps users choose the right feature URI. Be specific about the embedding type and use cases. - `type` 'single' | 'multi', required — REQUIRED. Index type - 'single' or 'multi'. 'single': One vector per document (most common). Use for standard embeddings. 'multi': Multiple named vectors per document (rare). Use for hybrid/ensemble. Determines whether 'index' field contains VectorIndex or MultiVectorIndex. - `index` union, required — REQUIRED. Nested index configuration. VectorIndex if type='single' (most common case). MultiVectorIndex if type='multi' (rare, for hybrid search). Contains the full storage configuration including Qdrant collection name, dimensions, distance metric, and inference service. - VectorIndex — Configuration for a single vector index in Qdrant. Defines the fully-qualified vector index including storage name, dimensions, distance metric, and inference service. This is the actual index that gets created in Qdrant and used for vector similarity search. Key Concepts: - The `name` field is the FULL qualified name used as the Qdrant collection name - Format: {extractor}_{version}_{output} (e.g., "text_extractor_v1_embedding") - This ensures namespace isolation between extractors and versions - Different from VectorIndexDefinition.name which is the short user-facing name Use Cases: - Define vector storage configuration for feature extractors - Specify inference service and model parameters - Configure distance metrics for similarity search - Set storage optimization (on-disk for large vectors) Requirements: - name: REQUIRED - Must be unique across all extractors in namespace - description: REQUIRED - Explain what this vector represents - dimensions: REQUIRED for DENSE vectors, OPTIONAL for SPARSE - type: REQUIRED - Must match VectorType enum - inference_name: REQUIRED - Must reference a valid inference service - `name` string, nullable — OPTIONAL. Qdrant named vector identifier. If not provided, auto-derived from inference_service_id using the same conversion as inference_name (org/model -> org__model with hyphens as underscores). This enables cross-extractor compatibility: extractors using the same model will share the same named vector in Qdrant, allowing direct vector search across collections without fusion logic. - `description` string, required — REQUIRED. Human-readable description of what this vector index represents. Explain the content type, use cases, and search characteristics. Shown in API documentation and collection metadata. Be specific about what embeddings are stored here. - `dimensions` integer, nullable — Number of vector dimensions. REQUIRED for DENSE vectors (e.g., 1024 for E5-Large, 1408 for multimodal). NOT REQUIRED for SPARSE vectors (dimensions determined dynamically). Must match the output dimensions of the inference service. Cannot be changed after index creation without recreating the collection. - `type` 'dense' | 'sparse' | 'multi_dense', required — Vector types supported by the Mixpeek system. Defines the storage format and structure of embeddings in Qdrant. Values: DENSE: Traditional float array embeddings (e.g., [0.1, 0.2, 0.3]). Most common format. Used by: text_extractor, multimodal_extractor, image_extractor. Storage: ~4KB per 1024-dim vector. Fast cosine/dot similarity search. SPARSE: Index-value pairs for sparse embeddings (e.g., SPLADE, BM25). Only stores non-zero dimensions. Format: {indices: [1,5,9], values: [0.8,0.6,0.4]}. Storage: ~20KB. Keyword-based semantic search. MULTI_DENSE: List of dense vectors for late interaction models (e.g., ColBERT). Each document has multiple embeddings. Format: [[0.1,0.2], [0.3,0.4], ...]. Storage: ~500KB. High-precision retrieval. Examples: - DENSE for general semantic search (text_extractor, multimodal_extractor) - SPARSE for keyword expansion and explainability - MULTI_DENSE for maximum precision retrieval - `distance` string, nullable — Distance metric for similarity search. OPTIONAL - defaults to 'cosine' (normalized dot product). Options: 'cosine' (most common, normalized), 'dot' (raw dot product), 'euclidean' (L2 distance), 'manhattan' (L1 distance). Cosine recommended for most embeddings as it's scale-invariant. Must match the metric your model was trained with. - `datatype` 'float32' | 'uint8' — Vector data type. - `on_disk` boolean, nullable — OPTIONAL. If true, vectors stored on disk instead of RAM. Defaults to true for memory efficiency. Set to false for faster search with higher memory usage. Trade-off: on_disk=true saves ~95% RAM but ~10x slower search. Recommended to keep default (true) unless RAM is abundant and low latency critical. - `supported_inputs` BucketSchemaFieldType[], nullable — OPTIONAL. List of bucket schema field types this vector can process. Validates that input fields are compatible with this index. Examples: TEXT and STRING for text embeddings, VIDEO and IMAGE for multimodal embeddings, DOCUMENT for PDF extractors. Used for validation during collection creation. - `inference_name` string, nullable — DEPRECATED: Use inference_service_id instead. Identifier of the inference service to generate embeddings. Must reference a valid inference service registered in the system. Examples: 'multilingual_e5_large_instruct_v1' for text, 'vertex_multimodal_embedding' for video, 'laion_clip_vit_l_14_v1' for images. This determines which model creates the vectors during ingestion. Cannot be changed after collection creation. - `inference_service_id` string, nullable — RECOMMENDED. Service ID in org/name format (e.g., 'intfloat/e5-large'). When set, dimensions and distance are automatically derived from the registry. This is the canonical identifier for cross-plugin compatibility. Plugins using the same service_id can search across each other's vectors. Takes precedence over inference_name when both are set. - `purpose` 'text' | 'code' | 'image' | 'multimodal' | 'video' | 'audio' | 'sparse' — Semantic purpose of a vector index. Used by pipelines to look up vector configs by purpose without needing to know the specific inference_service_id. - `vector_name_override` string, nullable — OPTIONAL. Override for Qdrant named vector identifier. When set, this value is used as the Qdrant vector name instead of auto-deriving from inference_service_id. This enables multiple vectors from the same embedding model with different storage names. The inference_service_id is still used for cross-extractor compatibility checking, but storage uses this custom name. Use case: A single extractor producing N vectors (e.g., title_embedding, body_embedding) using the same model but needing separate storage. - `supports_multi_query` boolean — Whether this vector index supports multi-content queries at retrieval time. When True, the feature_search stage accepts input_mode='multi_content' — a list of URLs and/or text strings that are embedded together in one API call to produce a single query vector. Only set for extractors whose underlying model natively supports multi-file input (e.g., gemini_multifile_extractor using Gemini Embedding 2). - MultiVectorIndex — Configuration for multi-vector indexes. Allows a single extractor to produce multiple named vector outputs in one index. Useful for hybrid search combining different embedding types or multiple models. Use Cases: - Hybrid dense + sparse embeddings in one index - Multiple models for ensemble retrieval - Different granularities (sentence + paragraph embeddings) Requirements: - name: REQUIRED - Full qualified name for the multi-vector index - description: REQUIRED - Explain what vector combinations are included - vectors: REQUIRED - Dictionary mapping output names to VectorIndex configs Note: Currently less common than single VectorIndex. Most extractors use separate VectorIndexDefinitions for each output instead. - `name` string, required — REQUIRED. Fully-qualified name for the multi-vector index. Format: {extractor}_{version}_{output} (e.g., 'hybrid_extractor_v1_multi'). Must be unique across namespace. - `description` string, required — REQUIRED. Human-readable description of the multi-vector index. Explain what vector types are included and their purposes. Describe use cases for this multi-vector configuration. - `vectors` object, required — REQUIRED. Dictionary mapping vector output names to their VectorIndex configurations. Each key is a unique identifier for that vector type within this multi-index. Each value is a complete VectorIndex with its own dimensions, type, and inference service. Example keys: 'dense', 'sparse', 'primary', 'secondary'. - `required_payload_indexes` PayloadIndexConfigOutput[], nullable — Payload indexes required by this extractor - `field_name` string, required — Name of the payload field to index. Must be unique within the namespace. Use dot notation for nested fields (e.g., 'metadata.title'). Cannot use protected system field names when is_protected=False. - `type` 'keyword' | 'integer' | 'float' | 'bool' | 'geo' | 'datetime' | 'text' | 'uuid', required — Payload schema type. - `field_schema` union — Optional schema configuration for the index. If not provided, uses default parameters for the specified type. Different types support different parameters (e.g., KeywordIndexParams.is_tenant). - TextIndexParams — Configuration for text index. - `type` string - `tokenizer` 'word' | 'whitespace' | 'prefix' | 'multilingual' — Tokenizer type. - `min_token_len` integer - `max_token_len` integer - `lowercase` boolean - IntegerIndexParams — Configuration for integer index. - `type` string - `lookup` boolean - `range` boolean - KeywordIndexParams — Configuration for keyword index. - `type` string - `is_tenant` boolean - FloatIndexParams — Configuration for float index. - `type` string - GeoIndexParams — Configuration for geo index. - `type` string - DatetimeIndexParams — Configuration for datetime index. - `type` string - UuidIndexParams — Configuration for UUID index. - `type` string - `is_tenant` boolean - BoolIndexParams — Configuration for boolean index. - `type` string - `is_protected` boolean — Whether this index is system-managed and cannot be modified by users. Protected indexes (is_protected=True) are created automatically by Mixpeek and are essential for internal operations like tenant isolation, lineage tracking, and document management. Users cannot create, modify, or delete protected indexes. User-created indexes always have is_protected=False. - `position_fields` string[] — Fields that identify unique positions within output documents. Used for deterministic document ID generation. - `feature_uri` string, nullable — Primary feature URI (e.g., mixpeek://text_extractor@v1/embedding) - `capabilities` string[] — What this extractor can do: 'batch' (feature extraction during ingestion), 'realtime' (query-time inference for retriever stages) - `example_usage` object, nullable — Minimal working configuration for namespace + collection + input_mappings + parameters - `plugin_id` string, nullable — Plugin ID (custom plugins only) - `deployed` boolean, nullable — Whether the plugin is deployed (custom plugins only) - `validation_status` 'passed' | 'failed' | 'pending', nullable — Validation status (custom plugins only) - `created_at` string, date-time, nullable — Creation timestamp (custom plugins only) - `updated_at` string, date-time, nullable — Last update timestamp (custom plugins only) - `total` integer, required — Total number of extractors - `namespace_id` string, required — Namespace ID - `builtin_count` integer, required — Number of builtin extractors - `custom_count` integer, required — Number of custom extractors (org + namespace level) ## Other responses - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `422` — Validation Error - `500` — Internal Server Error --- [API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/versions/220a3b263fda/schema)