> ## Documentation Index > Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Lint Manifest > Lint a YAML manifest for best practices and potential issues. Goes beyond basic validation to provide actionable suggestions for improving your manifest configuration. This endpoint is designed for AI agents and developers who want to optimize their Mixpeek setup. **Lint Rules:** - `UNUSED_EXTRACTOR`: Feature extractor defined but not used by any collection - `UNUSED_COLLECTION`: Collection not referenced by any retriever - `MISSING_INPUT_SCHEMA`: Retriever uses templates but has no input_schema - `MISSING_CACHE_CONFIG`: Retriever without caching (especially with LLM stages) - `SUBOPTIMAL_STAGE_ORDER`: Filter stages after expensive operations - `DUPLICATE_FEATURE_URI`: Same feature searched multiple times - `MISSING_DESCRIPTION`: Resources without descriptions - `NO_SEARCH_STAGE`: Retriever with no search stages - `EXTRACTOR_NOT_IN_NAMESPACE`: Collection uses extractor not in namespace - `MISSING_SECRET`: Secret reference not configured **Severity Levels:** - `error`: Must be fixed before applying - `warning`: Best practice violation, should be fixed - `info`: Suggestion for improvement **Example:** ```bash curl -X POST /v1/manifest/lint \ -H "Authorization: Bearer $API_KEY" \ -F "manifest_file=@mixpeek.yaml" ``` **Response includes actionable suggestions:** ```json { "valid": true, "results": [ { "code": "MISSING_CACHE_CONFIG", "severity": "warning", "message": "Retriever 'product_search' has no cache configuration", "location": "retrievers[0]", "suggestion": "Add cache_config to improve performance", "fix_example": "cache_config:\n enabled: true\n ttl_seconds: 3600" } ], "summary": {"error": 0, "warning": 1, "info": 0} } ``` ## OpenAPI ````yaml post /v1/manifest/lint openapi: 3.1.0 info: title: Mixpeek API description: >- This is the Mixpeek API, providing access to various endpoints for data processing and retrieval. termsOfService: https://mixpeek.com/terms contact: name: Mixpeek Support url: https://mixpeek.com/contact email: info@mixpeek.com version: '0.82' servers: - url: https://api.mixpeek.com description: Production security: [] paths: /v1/manifest/lint: post: tags: - Manifest summary: Lint Manifest description: >- Lint a YAML manifest for best practices and potential issues. Goes beyond basic validation to provide actionable suggestions for improving your manifest configuration. This endpoint is designed for AI agents and developers who want to optimize their Mixpeek setup. **Lint Rules:** - `UNUSED_EXTRACTOR`: Feature extractor defined but not used by any collection - `UNUSED_COLLECTION`: Collection not referenced by any retriever - `MISSING_INPUT_SCHEMA`: Retriever uses templates but has no input_schema - `MISSING_CACHE_CONFIG`: Retriever without caching (especially with LLM stages) - `SUBOPTIMAL_STAGE_ORDER`: Filter stages after expensive operations - `DUPLICATE_FEATURE_URI`: Same feature searched multiple times - `MISSING_DESCRIPTION`: Resources without descriptions - `NO_SEARCH_STAGE`: Retriever with no search stages - `EXTRACTOR_NOT_IN_NAMESPACE`: Collection uses extractor not in namespace - `MISSING_SECRET`: Secret reference not configured **Severity Levels:** - `error`: Must be fixed before applying - `warning`: Best practice violation, should be fixed - `info`: Suggestion for improvement **Example:** ```bash curl -X POST /v1/manifest/lint \ -H "Authorization: Bearer $API_KEY" \ -F "manifest_file=@mixpeek.yaml" ``` **Response includes actionable suggestions:** ```json { "valid": true, "results": [ { "code": "MISSING_CACHE_CONFIG", "severity": "warning", "message": "Retriever 'product_search' has no cache configuration", "location": "retrievers[0]", "suggestion": "Add cache_config to improve performance", "fix_example": "cache_config:\n enabled: true\n ttl_seconds: 3600" } ], "summary": {"error": 0, "warning": 1, "info": 0} } ``` operationId: lint_manifest_v1_manifest_lint_post parameters: - name: skip_rules in: query required: false schema: type: array items: type: string description: Rule codes to skip (e.g., MISSING_DESCRIPTION) default: [] title: Skip Rules description: Rule codes to skip (e.g., MISSING_DESCRIPTION) requestBody: required: true content: multipart/form-data: schema: $ref: '#/components/schemas/Body_lint_manifest_v1_manifest_lint_post' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/LintResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: Body_lint_manifest_v1_manifest_lint_post: properties: manifest_file: type: string format: binary title: Manifest File description: YAML manifest file type: object required: - manifest_file title: Body_lint_manifest_v1_manifest_lint_post LintResponse: properties: valid: type: boolean title: Valid description: Whether the manifest is valid (no errors, warnings OK) results: items: $ref: '#/components/schemas/LintResult' type: array title: Results description: List of lint results summary: additionalProperties: type: integer type: object title: Summary description: Count of results by severity type: object required: - valid title: LintResponse description: |- Response from the lint endpoint. Example: { "valid": true, "results": [...], "summary": {"error": 0, "warning": 2, "info": 3} } examples: - results: - code: UNUSED_COLLECTION location: collections[2] message: Collection 'orphan_data' is not referenced by any retriever severity: warning suggestion: Add a retriever that uses this collection or remove it summary: error: 0 info: 0 warning: 1 valid: true ErrorResponse: properties: success: type: boolean title: Success description: Always false for error responses default: false status: type: integer title: Status description: HTTP status code for this error error: $ref: '#/components/schemas/ErrorDetail' description: Error details payload type: object required: - status - error title: ErrorResponse description: Error response model. examples: - error: details: id: ns_123 resource: namespace message: Namespace not found type: NotFoundError status: 404 success: false HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError LintResult: properties: code: type: string title: Code description: Lint rule code (e.g., 'UNUSED_EXTRACTOR', 'MISSING_CACHE_CONFIG') severity: $ref: '#/components/schemas/LintSeverity' description: 'Severity level: error, warning, or info' message: type: string title: Message description: Human-readable description of the issue location: type: string title: Location description: Path to the problematic element (e.g., 'retrievers[0].stages[2]') suggestion: type: string title: Suggestion description: Actionable suggestion for fixing the issue fix_example: anyOf: - type: string - type: 'null' title: Fix Example description: Optional YAML example showing the correct configuration type: object required: - code - severity - message - location - suggestion title: LintResult description: |- A single lint result with actionable suggestion. Example: { "code": "UNUSED_EXTRACTOR", "severity": "warning", "message": "Feature extractor 'text_extractor' in namespace 'my_ns' is not used by any collection", "location": "namespaces[0].feature_extractors[1]", "suggestion": "Remove the unused extractor or add a collection that uses it", "fix_example": "collections:\n - name: text_docs\n feature_extractor:\n name: text_extractor" } examples: - code: MISSING_CACHE_CONFIG fix_example: |- cache_config: enabled: true ttl_seconds: 3600 location: retrievers[0] message: Retriever 'product_search' has no cache configuration severity: info suggestion: Add cache_config to improve performance for repeated queries ErrorDetail: properties: message: type: string title: Message description: Human-readable error message type: type: string title: Type description: Stable error type identifier (machine-readable) code: anyOf: - type: string - type: 'null' title: Code description: >- Fine-grained error code for programmatic handling (e.g., namespace_name_taken, feature_extractor_not_found). Present only when consumers may need to branch on a specific error condition. details: anyOf: - additionalProperties: true type: object - type: 'null' title: Details description: >- Optional structured details to help debugging (validation errors, IDs, etc.) type: object required: - message - type title: ErrorDetail description: Error detail model. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError LintSeverity: type: string enum: - error - warning - info title: LintSeverity description: Severity level for lint results. ````