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

# Lint Manifest

`POST /v1/manifest/lint`

## Request

- Base URL: `https://api.mixpeek.com`
- URL: `https://api.mixpeek.com/v1/manifest/lint`
- Auth: HTTP bearer

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

## Query parameters

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

## Request body `multipart/form-data`

- BodyLintManifestV1ManifestLintPost
  - `manifest_file` string, binary, required: YAML manifest file
  - `parameters` string, nullable: 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.

## 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_INPUT_SCHEMA')
    - `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`: Unprocessable Entity
- `429`: Too Many Requests
- `500`: Internal Server Error
- `503`: Service Unavailable

## Changes

- **2026-10-22** `790bc16455f6`: 1 info
  - added the new optional request property `parameters`
- **2026-10-09** `61a175e8eb9a`: 1 warning, 5 info
  - removed the optional property `detail` from the response with the `422` status
  - added the non-success response with the status `429`
  - added the non-success response with the status `503`
  - added the optional property `success` to the response with the `422` status
  - …2 more
- **2026-08-09** `5d4c905106b4`: 1 info
  - the endpoint scheme security `BearerAuth` was added to the API

[Operation history](https://skmtc.dev/mixpeek/apis/mixpeek-api/changes/v1/manifest/lint/post.md)

---

[API](https://skmtc.dev/mixpeek/apis/mixpeek-api.md) - [All operations](https://skmtc.dev/mixpeek/apis/mixpeek-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mixpeek/apis/mixpeek-api/revisions/790bc16455f6?raw)