> ## 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 - `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 - `UNUSED_BUCKET`: Bucket that no collection reads - `TAXONOMY_INPUT_NOT_WRITTEN`: Taxonomy reads a feature its collection does not write - `RETRIEVER_FEATURE_NOT_IN_COLLECTIONS`: Retriever searches a feature none of its collections write **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_INPUT_SCHEMA", "severity": "warning", "message": "Retriever 'product_search' uses template variables but has no input_schema defined", "location": "retrievers[0]", "suggestion": "Define input_schema to document and validate retriever inputs", "fix_example": "input_schema:\n type: object\n properties:\n query:\n type: string" } ], "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: - BearerAuth: [] 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 - `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 - `UNUSED_BUCKET`: Bucket that no collection reads - `TAXONOMY_INPUT_NOT_WRITTEN`: Taxonomy reads a feature its collection does not write - `RETRIEVER_FEATURE_NOT_IN_COLLECTIONS`: Retriever searches a feature none of its collections write **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_INPUT_SCHEMA", "severity": "warning", "message": "Retriever 'product_search' uses template variables but has no input_schema defined", "location": "retrievers[0]", "suggestion": "Define input_schema to document and validate retriever inputs", "fix_example": "input_schema:\n type: object\n properties:\n query:\n type: string" } ], "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: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Too Many Requests content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Service Unavailable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] components: schemas: Body_lint_manifest_v1_manifest_lint_post: properties: manifest_file: type: string contentMediaType: application/octet-stream title: Manifest File description: YAML manifest file parameters: anyOf: - type: string - type: 'null' title: Parameters description: >- JSON object of values for the manifest's declared parameters, e.g. {"camera_url": "rtsp://host/stream", "polling_seconds": 300}. Each value must match its declared type. Omit when the manifest declares none. 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 LintResult: properties: code: type: string title: Code description: Lint rule code (e.g., 'UNUSED_EXTRACTOR', 'MISSING_INPUT_SCHEMA') 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_INPUT_SCHEMA fix_example: |- input_schema: type: object properties: query: type: string location: retrievers[0] message: >- Retriever 'product_search' uses template variables but has no input_schema defined severity: warning suggestion: Define input_schema to document and validate retriever inputs 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. LintSeverity: type: string enum: - error - warning - info title: LintSeverity description: Severity level for lint results. securitySchemes: BearerAuth: type: http scheme: bearer description: >- Mixpeek API key, sent as `Authorization: Bearer mxp_sk_...`. Create one in Studio under Settings → API Keys, or with an admin key via `POST /v1/organizations/users/{user_email}/api-keys`. A missing, malformed, unknown, revoked, inactive or expired key returns 401; a key without the permission, scope or plan an operation needs returns 403. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.