---
title: "Lint Manifest"
method: POST
path: "/v1/manifest/lint"
tags: ["Manifest"]
---

# Lint Manifest

`POST /v1/manifest/lint`

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

## Query parameters

- `skip_rules` string[] — Rule codes to skip (e.g., MISSING_DESCRIPTION)

## Response `200`

Successful Response

- LintResponse — Response from the lint endpoint. Example: { "valid": true, "results": [...], "summary": {"error": 0, "warning": 2, "info": 3} }
  - `valid` boolean, required — Whether the manifest is valid (no errors, warnings OK)
  - `results` LintResult[] — List of lint results
    - `code` string, required — Lint rule code (e.g., 'UNUSED_EXTRACTOR', 'MISSING_CACHE_CONFIG')
    - `severity` 'error' | 'warning' | 'info', required — Severity level for lint results.
    - `message` string, required — Human-readable description of the issue
    - `location` string, required — Path to the problematic element (e.g., 'retrievers[0].stages[2]')
    - `suggestion` string, required — Actionable suggestion for fixing the issue
    - `fix_example` string, nullable — Optional YAML example showing the correct configuration
  - `summary` object — Count of results by severity

## 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/revisions/c768d4d28e4c/schema)