Archstone Verify Openapi API

openapi: 3.2.0
info:
  title: Archstone — public API surface Verify Openapi API
  version: 2.32.1
  description: 'The public, unauthenticated surface of the Archstone console: discovering what a deployment can do, and verifying an OpenAPI document for free. Every operator-, collector-, and platform-scoped route is deliberately absent from this document — and so is the demo tourism search: its contract lives with the demo Worker in a separate repository this document does not control.'
servers:
- url: https://console.archstone.dev
  description: The hosted Archstone console and its control-plane API.
security: []
tags:
- name: Verify Openapi
paths:
  /api/v1/verify-openapi:
    post:
      operationId: verifyOpenapi
      summary: Submit an OpenAPI document address for a free, one-time verification run
      description: 'Send the request header `Prefer: outcome=in-body` (RFC 7240) to get every defined outcome as an HTTP 200 whose body carries a top-level `outcome`, for a caller that cannot read the body of a non-2xx response. A verified run then also carries `nextStep` and a `safePath` on every operation. Any other value is ignored and the response is exactly what it is without the header. The header is not allowed from a browser page (CORS), and a deployment without the feature answers 404 whether or not it is sent. It is described here rather than declared as a parameter because the verifier does not read header parameters, and this document is itself verified. Added in 1.5.0.'
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyOpenapiRequest'
            example:
              url: https://example.com/openapi.yaml
      responses:
        '200':
          description: 'The verification report — which operations are included, and the outcome of each live read attempted. With `Prefer: outcome=in-body` every other defined outcome (the 400, 422, 429 and 503 bodies below) is also served as a 200 carrying the same body plus a top-level `outcome`, and `Preference-Applied: outcome=in-body` is set; a verified report then has `outcome: "verified"`, `nextStep`, and a `safePath` per operation. A refusal served this way has the shape `OutcomeInBodyRefusal` (a composition keyword is avoided here: this document is itself verified, and the verifier does not read one).'
          headers:
            Preference-Applied:
              description: The value `outcome=in-body`, present only when that preference was honoured. Added in 1.5.0.
              schema:
                type: string
                enum:
                - outcome=in-body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicVerifyReport'
              example:
                verifiedAt: '2026-09-19T12:00:00.000Z'
                source:
                  url: https://example.com/openapi.yaml
                  sha256: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a0
                  unresolvedReferences: []
                api:
                  name: Example API
                  serverAddress: https://api.example.com
                contractFingerprint: sha256:c0ffee
                summary:
                  operations: 2
                  included: 1
                  excludedWrites: 1
                  excludedIrreversible: 0
                  excludedOther: 0
                  livePassed: 1
                  liveFailed: 0
                  liveNotAttempted: 0
                documentNotes: []
                operations:
                - key: GET /v1/things
                  method: GET
                  path: /v1/things
                  summary: List things
                  effect: read
                  decision:
                    included: true
                  authentication: none
                  requiredInputs: 0
                  requiredInputsWithExample: 0
                  live:
                    status: passed
                - key: POST /v1/things
                  method: POST
                  path: /v1/things
                  summary: Create a thing
                  effect: write
                  decision:
                    included: false
                    reason: write
                  authentication: none
                  requiredInputs: 0
                  requiredInputsWithExample: 0
                  live: null
        '400':
          description: The `url` field was missing or not a URL this route may fetch.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidUrlRefusal'
        '404':
          description: This deployment does not carry the "Verify my API" feature.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundRefusal'
        '422':
          description: '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.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyOpenapi422'
              examples:
                source_unreadable:
                  summary: The document could not be read.
                  value:
                    status: 422
                    error: source_unreadable
                    reason: host_not_allowed
                document_not_openapi:
                  summary: The address did not resolve to an OpenAPI document.
                  value:
                    status: 422
                    error: document_not_openapi
                    reason: openapi_version_unsupported
                nothing_verifiable:
                  summary: The document had no operation a public reader could verify.
                  value:
                    status: 422
                    error: nothing_verifiable
                    reason: no_read_operation
        '429':
          description: This remote address has run too many verifications in the current window.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitedRefusal'
        '503':
          description: This deployment is already running its configured maximum of concurrent verifications.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BusyRefusal'
      tags:
      - Verify Openapi
components:
  schemas:
    VerifyOpenapiRequest:
      type: object
      required:
      - url
      additionalProperties: false
      properties:
        url:
          type: string
          description: The address of the OpenAPI document to verify. Fetched server-side; never a value the visitor's browser calls directly.
    PublicVerifyReport:
      type: object
      required:
      - verifiedAt
      - source
      - api
      - contractFingerprint
      - summary
      - documentNotes
      - operations
      additionalProperties: false
      properties:
        verifiedAt:
          type: string
          format: date-time
        source:
          type: object
          required:
          - url
          - sha256
          - unresolvedReferences
          additionalProperties: false
          properties:
            url:
              type: string
            sha256:
              type: string
              pattern: ^[a-f0-9]{64}$
              maxLength: 64
            unresolvedReferences:
              type: array
              items:
                type: string
        api:
          type: object
          required:
          - name
          - serverAddress
          additionalProperties: false
          properties:
            name:
              type: string
            serverAddress:
              type:
              - string
              - 'null'
        contractFingerprint:
          type: string
          pattern: ^sha256:[a-f0-9]{1,64}$
          maxLength: 71
        summary:
          type: object
          required:
          - operations
          - included
          - excludedWrites
          - excludedIrreversible
          - excludedOther
          - livePassed
          - liveFailed
          - liveNotAttempted
          additionalProperties: false
          properties:
            operations:
              type: integer
            included:
              type: integer
            excludedWrites:
              type: integer
            excludedIrreversible:
              type: integer
            excludedOther:
              type: integer
            livePassed:
              type: integer
            liveFailed:
              type: integer
            liveNotAttempted:
              type: integer
        documentNotes:
          type: array
          items:
            type: string
        operations:
          type: array
          items:
            $ref: '#/components/schemas/VerifiedOperation'
        outcome:
          description: 'Present only with `Prefer: outcome=in-body`. Added in 1.5.0.'
          type: string
          enum:
          - verified
        nextStep:
          description: 'Present only with `Prefer: outcome=in-body`. The fixed next step after a verified run: a command and a sign-up address, the same for every caller. Added in 1.5.0.'
          type: object
          required:
          - command
          - url
          additionalProperties: false
          properties:
            command:
              type: string
              pattern: ^[A-Za-z0-9@/._ -]{1,80}$
              maxLength: 80
            url:
              type: string
              pattern: ^https://[A-Za-z0-9._~:/?#@!$&'()*+,;=%-]{1,200}$
              maxLength: 220
    RateLimitedRefusal:
      type: object
      required:
      - error
      - retryAfterMinutes
      additionalProperties: false
      properties:
        error:
          type: string
          enum:
          - rate_limited
        retryAfterMinutes:
          type: integer
    VerifyOpenapi422:
      description: 'The merged shape of all three 422 causes on this operation (see the response''s own `examples`). Not a `oneOf` of `SourceUnreadableRefusal`/`DocumentNotOpenapiRefusal`/ `NothingVerifiableRefusal` below — those three schemas exist so a consumer can validate one concrete cause precisely; this one exists so the operation''s response entry itself stays a single schema. This schema validates field types and enum membership; it does not enforce that `reason`''s closed `FetchSourceError` enum applies only when `error: "source_unreadable"` — treat `error` as authoritative.'
      type: object
      required:
      - error
      additionalProperties: false
      properties:
        status:
          type: integer
          enum:
          - 422
        error:
          type: string
          enum:
          - source_unreadable
          - document_not_openapi
          - nothing_verifiable
        reason:
          description: For "source_unreadable", one of `FetchSourceError`'s members (see `SourceUnreadableRefusal`); for the other two causes, a lower-case code naming the cause. Always a code, never text taken from the document.
          type: string
          pattern: ^[a-z0-9_]{1,64}$
          maxLength: 64
        httpStatus:
          description: Present only for "source_unreadable", when the read reached an HTTP response.
          type: integer
    BusyRefusal:
      type: object
      required:
      - error
      additionalProperties: false
      properties:
        error:
          type: string
          enum:
          - busy
    VerifiedOperation:
      type: object
      required:
      - key
      - method
      - summary
      - effect
      - decision
      - authentication
      - requiredInputs
      - requiredInputsWithExample
      - live
      additionalProperties: false
      properties:
        key:
          type: string
        method:
          type: string
          enum:
          - GET
          - PUT
          - POST
          - DELETE
          - OPTIONS
          - HEAD
          - PATCH
          - TRACE
        path:
          description: 'Absent with `Prefer: outcome=in-body`, which offers `safePath` instead.'
          type: string
        summary:
          type: string
        effect:
          type:
          - string
          - 'null'
          enum:
          - read
          - write
          - irreversible
          - null
        decision:
          $ref: '#/components/schemas/Decision'
        authentication:
          type:
          - string
          - 'null'
          enum:
          - none
          - header
          - null
        requiredInputs:
          type: integer
        requiredInputsWithExample:
          type: integer
        safePath:
          description: 'Present only with `Prefer: outcome=in-body`. `path` when it is made only of URL-safe characters and is at most 120 characters long, otherwise `null`. Added in 1.5.0.'
          type:
          - string
          - 'null'
          maxLength: 120
          pattern: ^/[A-Za-z0-9._~!$&'()*+,;=:@%/{}-]{0,119}$
        live:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/LiveOutcome'
    LiveOutcome:
      description: '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.'
      type: object
      required:
      - status
      additionalProperties: false
      properties:
        status:
          type: string
          enum:
          - passed
          - failed
          - not_attempted
        degraded:
          description: Present only when status is "passed" and at least one field path degraded.
          type: array
          items:
            type: string
        reachedServer:
          description: Present only when status is "failed".
          type: boolean
        class:
          description: Present only when status is "failed" and reachedServer is true.
          type: string
          enum:
          - contract_violation
          - server_error
        missing:
          description: Present only when class is "contract_violation" and fields were missing.
          type: array
          items:
            type: string
        reason:
          description: Present only when status is "not_attempted".
          type: string
          enum:
          - needs_credential
          - no_example_for_required_input
          - server_address_missing
          - call_budget_exhausted
    Decision:
      description: '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.'
      type: object
      required:
      - included
      additionalProperties: false
      properties:
        included:
          type: boolean
        reason:
          type: string
          enum:
          - write
          - irreversible
          - method_hint_contradiction
          - not_usable
          - unclassified
        code:
          type: string
          description: Present only for reason "not_usable" — the document-side code explaining why the operation cannot be used at all.
    NotFoundRefusal:
      type: object
      required:
      - error
      additionalProperties: false
      properties:
        error:
          type: string
          enum:
          - not_found
    InvalidUrlRefusal:
      type: object
      required:
      - error
      additionalProperties: false
      properties:
        status:
          type: integer
          enum:
          - 400
        error:
          type: string
          enum:
          - invalid_url