openapi: 3.2.0
info:
  title: Blueprint Validate API
  version: 1A
  summary: API Blueprint parsing service
  description: The API Blueprint parsing service provides parsing of API Blueprint "as a service".
  license:
    name: MIT
    identifier: MIT
  contact:
    name: API Blueprint
    url: https://apiblueprint.org
servers:
- url: https://api.apiblueprint.org
  description: Production parsing service (declared as HOST in the provider's apiary.apib)
tags:
- name: Validate
  description: Validate an API description and return its annotations. Advertised by the live service root; absent from the provider's published contract.
paths:
  /validate:
    post:
      tags:
      - Validate
      operationId: validateApiDescription
      summary: Validate
      description: 'Validate an API description and return only the annotations. Returns an API Elements parse result whose content carries the warnings and errors; an empty content array means the document is valid.


        UNDOCUMENTED SURFACE, ESTABLISHED BY PROBE. This operation is advertised by the live service root as the `validate` affordance but it does NOT appear in the provider''s published API Blueprint contract. Everything below was established by unauthenticated probes on 2026-09-02 and by reading the service''s own error messages; no behaviour is assumed.'
      x-probed:
        checked: '2026-09-02'
        evidence:
        - POST /validate with no body -> 400 {"message":"Body is not valid JSON"}
        - POST /validate {} -> 400 {"message":"Missing input document (`input_document`)"}
        - POST /validate {input_document, input_type:"text/vnd.apiblueprint"} -> 200 {"element":"parseResult","content":[]}
        - POST /validate with a document missing a status code -> 200 with one annotation, class "warning", code 6
        - 'GET /validate -> 405; OPTIONS /validate -> 204 Access-Control-Allow-Methods: POST'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransformRequest'
      responses:
        '200':
          description: An API Elements parse result carrying only annotations. Empty content means the document validated cleanly.
          content:
            application/vnd.refract.parse-result+json:
              schema:
                $ref: '#/components/schemas/ParseResult'
        '400':
          description: Body is not valid JSON, or `input_document` is missing.
          content:
            application/vnd.error+json:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method not allowed. Only POST is accepted.
        '415':
          description: '`input_type` is missing or names an unsupported input media type.'
          content:
            application/vnd.error+json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: 'Content-Type "undefined" is not supported. Supported MIME types: text/vnd.apiblueprint, text/vnd.legacyblueprint, application/swagger, application/vnd.oai.openapi'
components:
  schemas:
    ParseResult:
      allOf:
      - $ref: '#/components/schemas/ApiElement'
      description: 'A Refract Parse Result element (`element: parseResult`) whose content carries the parsed API category plus any annotations.'
    ApiElement:
      type: object
      description: A Refract / API Elements element. Structure is defined by the API Elements element schema, saved in this repository at json-schema/api-blueprint-api-elements-element-schema.json.
      properties:
        element:
          type: string
        meta:
          type: object
        attributes:
          type: object
        content: {}
      required:
      - element
    Error:
      type: object
      description: The vnd.error media type as used by this API. Carries a single human readable message.
      properties:
        message:
          type: string
      required:
      - message
    TransformRequest:
      type: object
      description: JSON envelope used by /validate and /transform. Field names were established by probe, from the service's own 400/415/406 error messages.
      properties:
        input_document:
          type: string
          description: The API description document to process.
        input_type:
          type: string
          description: Media type of input_document.
          enum:
          - text/vnd.apiblueprint
          - text/vnd.legacyblueprint
          - application/swagger
          - application/vnd.oai.openapi
        output_type:
          type: string
          description: Desired output media type. Required by /transform, ignored by /validate.
          enum:
          - application/vnd.refract.parse-result
          - application/vnd.refract.parse-result+json
          - application/vnd.refract.parse-result+yaml
          - application/vnd.refract.parse-result; version=0.6
          - application/vnd.refract.parse-result; version=1.0
          - application/vnd.refract.parse-result+json; version=0.6
          - application/vnd.refract.parse-result+json; version=1.0
          - application/vnd.refract.parse-result+yaml; version=0.6
          - application/vnd.refract.parse-result+yaml; version=1.0
      required:
      - input_document
      - input_type
externalDocs:
  description: API Blueprint API documentation on Apiary
  url: https://apiblueprintapi.docs.apiary.io/