Validate a documentation definition

POST /validations

Validate a definition against its schema (OpenAPI or AsyncAPI) and return errors without creating a new version. This is useful in a CI process, to validate that a changed definition file is valid and won't fail when being deployed on



The version validation request object

  • documentation string Required

    UUID or slug of the documentation.

  • hub string

    UUID or slug of the hub if the documentation is part of a hub.

  • Name of the documentation to create. Used only if auto_create_documentation is set.

  • Create the documentation if it does not exist yet. Must be used with a hub and a documentation.

    Default value is false.

  • REQUIRED if url is not present.

    Serialized definition. This should be an OpenAPI 2.x, 3.x or AsyncAPI 2.x file serialized as a string, in YAML or JSON.

  • references array[object]

    Import external references used by definition. It's usually resources not accessible by servers, like local files or internal URLs.

    Hide references attributes Show references attributes object
    • location string

      Location of the external reference as it's called from definition, without the relative path (the part after #/). Can be an URL of a file system path.

    • content string

      Content of the external reference, as a string.

  • url string(uri)

    REQUIRED if definition is not present.

    Target definition URL. It should be accessible through HTTP by servers.


  • 200 application/json


    Hide response attribute Show response attribute object
    • Specification of the given definition as a path: speficiation_name/specification_version/format.

      Values are openapi/v2/yaml, openapi/v2/json, openapi/v3/yaml, openapi/v3/json, asyncapi/v2/yaml, or asyncapi/v2/json.

  • 400 application/json

    Bad request

    Hide response attribute Show response attribute object
    • message string

      Human readable error message for status 400.

  • 422 application/json

    Definition is not valid.

    Hide response attributes Show response attributes object
    • message string

      Human readable error message.

    • errors object

      Hash of invalid attributes with their error messages.

POST /validations
curl \
 -X POST \
 -H "Authorization: Token $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"documentation":"0776d85d-e097-47c1-8c60-cb1190d11945","hub":"my_hub_slug","documentation_name":"string","auto_create_documentation":false,"definition":"{\"openapi\": \"3.0\", \"info\": { \"title\": … }}\n","references":[{"location":"","content":"string"}],"url":""}'
Request examples
  "documentation": "0776d85d-e097-47c1-8c60-cb1190d11945",
  "hub": "my_hub_slug",
  "documentation_name": "string",
  "auto_create_documentation": false,
  "definition": "{\"openapi\": \"3.0\", \"info\": { \"title\": … }}\n",
  "references": [
      "location": "",
      "content": "string"
  "url": ""
Response examples (200)
  "specification": "openapi/v3/json"
Response examples (400)
  "message": "You need to upgrade to a paid plan to perform this request. Please go to"
Response examples (422)
  "message": "Invalid definition file",
  "errors": {
    "raw_definition": [
      "The property '#/paths//docs/{:id}/validations/post' contains additional properties [\"yolo\"] outside of the schema when none are allowed"