---
title: "Submit an OpenAPI document address for a free, one-time verification run"
method: POST
path: "/api/v1/verify-openapi"
---

# Submit an OpenAPI document address for a free, one-time verification run

`POST /api/v1/verify-openapi`

## Request

- Base URL: `https://console.archstone.dev`
- URL: `https://console.archstone.dev/api/v1/verify-openapi`
- Auth: none required

## Request body

- VerifyOpenapiRequest
  - `url` string, required: The address of the OpenAPI document to verify. Fetched server-side; never a value the visitor's browser calls directly.

## Response `200`

The verification report — which operations are included, and the outcome of each live read attempted.

- PublicVerifyReport
  - `verifiedAt` string, date-time, required
  - `source` object, required
    - `url` string, required
    - `sha256` string, required
    - `unresolvedReferences` string[], required
  - `api` object, required
    - `name` string, required
    - `serverAddress` string, nullable, required
  - `contractFingerprint` string, required
  - `summary` object, required
    - `operations` integer, required
    - `included` integer, required
    - `excludedWrites` integer, required
    - `excludedIrreversible` integer, required
    - `excludedOther` integer, required
    - `livePassed` integer, required
    - `liveFailed` integer, required
    - `liveNotAttempted` integer, required
  - `documentNotes` string[], required
  - `operations` VerifiedOperation[], required
    - `key` string, required
    - `method` string, required
    - `path` string, required
    - `summary` string, required
    - `effect` 'read' | 'write' | 'irreversible' | 'null', nullable, required
    - `decision` Decision, required: Whether an operation is included in a run, and why not when it isn't. `reason` and `code` are present only when `included` is `false`; `code` only for `reason: "not_usable"`. Not expressed as a `oneOf` — two disjoint shapes picked apart only by a boolean would be polymorphism for its own sake, and every field below is already closed by its own enum. This schema validates field types and enum membership; it does not enforce that `reason` (or `code`) is present only when `included: false` — treat `included` as authoritative.
      - `included` boolean, required
      - `reason` 'write' | 'irreversible' | 'method_hint_contradiction' | 'not_usable' | 'unclassified'
      - `code` string: Present only for reason "not_usable" — the document-side code explaining why the operation cannot be used at all.
    - `authentication` 'none' | 'header' | 'null', nullable, required
    - `requiredInputs` integer, required
    - `requiredInputsWithExample` integer, required
    - `live` LiveOutcome, required: The outcome of the one live call attempted for an included, read-shaped operation. Which of `degraded`/`reachedServer`/`class`/`missing`/`reason` are present depends on `status` (and, when `status` is "failed", on `class`) — see each field's own description. This schema validates field types and enum membership; it does not enforce that `class` is present only when `status: "failed"` (or the equivalent dependency for the other fields) — treat `status` (and, for a "failed" outcome, `class`) as authoritative.
      - `status` 'passed' | 'failed' | 'not_attempted', required
      - `degraded` string[]: Present only when status is "passed" and at least one field path degraded.
      - `reachedServer` boolean: Present only when status is "failed".
      - `class` 'contract_violation' | 'server_error': Present only when status is "failed" and reachedServer is true.
      - `missing` string[]: Present only when class is "contract_violation" and fields were missing.
      - `reason` 'needs_credential' | 'no_example_for_required_input' | 'server_address_missing' | 'call_budget_exhausted': Present only when status is "not_attempted".

## Other responses

- `400`: The `url` field was missing or not a URL this route may fetch.
- `404`: This deployment does not carry the "Verify my API" feature.
- `422`: The document could not be read (`error: "source_unreadable"`, `reason` one of `FetchSourceError`'s members), was not an OpenAPI document (`error: "document_not_openapi"`), or had nothing a public reader could verify (`error: "nothing_verifiable"`) — three distinct causes sharing this status code, each with its own example below.
- `429`: This remote address has run too many verifications in the current window.
- `503`: This deployment is already running its configured maximum of concurrent verifications.

---

[API](https://skmtc.dev/archstone/apis/archstone-public-api-surface.md) · [All operations](https://skmtc.dev/archstone/apis/archstone-public-api-surface/llms.txt) · [OpenAPI document](https://skmtc.dev/archstone/apis/archstone-public-api-surface/revisions/e485540668e6?raw)