> ## Documentation Index
> Fetch the complete documentation index at: https://unkey.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAPI validation

> Validate incoming HTTP requests against your OpenAPI specification using the Sentinel. Reject malformed requests before they reach your app.

<Info>
  Unkey Deploy is in public beta. To try it, open the product switcher in the
  top-left of the dashboard and select **Deploy**. During beta, deployed
  resources are free. We're eager for feedback, so let us know what you think
  on [Discord](https://unkey.com/discord), [X](https://x.com/unkeydev), or
  email [support@unkey.com](mailto:support@unkey.com).
</Info>

The OpenAPI validation policy checks incoming requests against an OpenAPI 3.0 or 3.1 specification. Requests that don't conform to the spec are rejected with HTTP `400 Bad Request` before they reach your app.

## When to use it

Add an OpenAPI validation policy when you want to:

* Reject malformed requests at the gateway, so your app only handles well-formed input
* Enforce a contract between your API and its clients without writing per-route validation in your code
* Surface schema drift early — clients sending requests that don't match the spec get a clear `400` instead of an opaque server error

## What gets validated

The Sentinel validates the following parts of each request against your spec:

* Path parameters
* Query parameters
* Request headers
* Request body (content type and schema)

Requests that don't match any defined operation in the spec are rejected. Response validation is not performed by the Sentinel.

## Configuration

The OpenAPI validation policy uses your application's auto-scraped OpenAPI specification — there is no separate spec input on the policy itself.

1. Configure the **OpenAPI spec path** in your app's [networking settings](/platform/apps/settings#openapi-spec-path) (for example, `/openapi.yaml` or `/api/spec.json`). Unkey scrapes the spec from your running deployment.
2. Navigate to your project's **Sentinel Policies** page.
3. Create a new policy and select **OpenAPI Validation** as the policy type.
4. Optionally configure [match conditions](/platform/sentinel/policies/overview#match-expressions) to scope validation to specific routes.
5. Save the policy.

The Sentinel uses the deployment's most recently scraped spec, keyed by deployment ID, and refreshes its cache as your spec changes between deploys.

<Note>
  If your app doesn't expose an OpenAPI spec at the configured path, the policy has no spec to validate against. Set the **OpenAPI spec path** in your app settings before enabling the policy.
</Note>

## Error response

When a request fails validation, the Sentinel returns a structured error following [the standard error format](/platform/sentinel/policies/overview#error-response-format):

```json theme={"theme":"kanagawa-wave"}
{
  "meta": { "requestId": "req_abc123" },
  "error": {
    "title": "Bad Request",
    "detail": "request body does not match schema for /users",
    "status": 400,
    "type": "https://unkey.com/docs/errors/sentinel/openapi-validation-failed"
  }
}
```

The `detail` field includes the specific validation failure (for example, missing required field, type mismatch, or unknown operation) to help clients fix the request.