---
title: "Validate an OpenAPI specification"
method: POST
path: "/api/v2/openapi/validate/"
tags: ["Sources"]
---

# Validate an OpenAPI specification

`POST /api/v2/openapi/validate/`

## Request

- Base URL: `https://app.biel.ai`
- URL: `https://app.biel.ai/api/v2/openapi/validate/`
- Auth: API key in header `Authorization`

Validate an OpenAPI specification against the same checks Biel runs when it indexes your spec, including `$ref` resolution. A `200` means the next sync will parse the spec; a `422` returns the validation errors it would fail with.

Designed for CI/CD: publish your spec, call this endpoint, and fail the pipeline on a non-2xx status. This catches changes that would break API indexing before Biel's next sync does.

Submit the spec either by `url` (Biel fetches it and resolves relative `$ref`s against it) or inline as `content` (JSON or YAML).

**Required permission:** none. Any valid API key works.

## Request body

- union: The OpenAPI specification to validate. Provide exactly one of `url` or `content`.
  - object
    - `url` string, uri, required: URL of the specification (JSON or YAML). Biel fetches it and resolves relative `$ref`s against it, exactly as a sync would.
    - `content` string: Raw specification content (JSON or YAML) submitted inline.
  - object
    - `url` string, uri: URL of the specification (JSON or YAML). Biel fetches it and resolves relative `$ref`s against it, exactly as a sync would.
    - `content` string, required: Raw specification content (JSON or YAML) submitted inline.

## Response `200`

The specification is valid. A sync will parse it.

- OpenApiValidationSuccess: The specification parsed and validated successfully.
  - `valid` true, required
  - `openapi_version` string: Value of the spec's `openapi` (or legacy `swagger`) field.
  - `title` string: The API title declared in `info.title`.
  - `version` string: The API version declared in `info.version`.
  - `paths` integer: Number of paths in the specification.
  - `operations` integer: Number of operations across all paths.

## Other responses

- `400`: Validation error. Field-level errors keyed by field name.
- `403`: Forbidden. Missing permissions.
- `422`: The specification failed to fetch, parse, or validate.

---

[API](https://skmtc.dev/biel/apis/biel-ai-api.md) · [All operations](https://skmtc.dev/biel/apis/biel-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/biel/apis/biel-ai-api/revisions/ac7034d82696?raw)