> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Validate a resource

> Validates an entire pipeline resource file at one of four depths, against the environment named in `environmentName`. Depth 1 performs basic syntax checking only. Depth 2 additionally resolves basic parameters (using the pipeline's own variables and their default values) and carries out deeper validation not requiring invocation of the Runner. Depth 3 as Depth 2, but performs full parameter resolution, invoking the Runner to evaluate JavaScript if required. Depth 4 full validation, invoking all Runner capabilities; for transformation pipelines, also populates the SQL cache. Components are validated against the environment's data warehouse type. Results at depths 1 and 2 are returned synchronously (200 OK). Depths 3 and 4 return immediately (202 Accepted) with a PENDING `operationId`; poll `GET /v1/projects/{projectId}/resource-validations/{operationId}` for the aggregated result, or cancel via `DELETE`. The request body must contain the resource file content with `Content-Type: text/plain`, and can be at most 10 MB (10,485,760 bytes); a larger file is rejected with 413 Content Too Large. Pipeline YAML files (`.orch.yaml`, `.tran.yaml`, `.test.yaml`) are the only supported resource type today; the plain-text content type is used in anticipation of supporting other resource types (such as SQL scripts or Python source files) in future.



## OpenAPI

````yaml /openapi/public-api-endpoint-reference.yaml post /v1/projects/{projectId}/resource-validations
openapi: 3.1.0
info:
  title: Maia Public REST API
  version: '1.0'
servers:
  - description: EU1
    url: https://eu1.api.matillion.com/dpc
  - description: US1
    url: https://us1.api.matillion.com/dpc
  - description: AU1
    url: https://au1.api.matillion.com/dpc
  - description: EU2
    url: https://eu2.api.matillion.com/dpc
security:
  - bearerAuth: []
tags:
  - description: >-
      Validate Matillion resources against the Vanguard validation framework.
      Pipeline resource files (orchestration, transformation, test) are the only
      supported resource type today; support for additional resource types (e.g.
      SQL scripts or Python source files) is anticipated in future.
    name: Resource Validation
  - description: Manage Schedules
    name: Schedules
  - description: Manage Connections
    name: Connections
  - description: Operations for managing Project Variables
    name: Project Variables
  - description: Manage Pipelines
    name: Pipelines
  - description: Review pipelines against quality rules
    name: Pipeline Quality Review
  - description: >-
      Describe how to configure a connection for a given auth provider, auth
      type and platform connection type.
    name: Connection Schema
  - description: Execute tests within a project
    name: Test Execution
  - description: Manage your AI agent tasks
    name: AI Agent Tasks
  - description: SCIM endpoints for user/group permission management
    name: Directory Integration
  - description: Publish shared pipeline artifacts
    name: Shared Pipeline Artifacts
  - description: Manage Repositories
    name: Repositories
  - description: Report on Credit Consumption
    name: Consumption
  - description: >-
      Start and track the migration of a Git repository into a project's working
      tree.
    name: Repository Migration
  - description: Manage Artifacts
    name: Artifacts
  - description: Operations for data lineage and governance
    name: Data Lineage
  - description: Manage Runners
    name: Runners
  - description: Manage Streaming Pipelines
    name: Streaming Pipelines
  - description: Execute a pipeline
    name: Pipeline Execution
  - description: ''
    name: Environments
  - description: ''
    name: Projects
  - description: Operations for managing Environment-level Overrides of Project Variables
    name: Project Variable Environment Overrides
  - description: Query audit events
    name: Audit Events
  - description: Connector Profiles
    name: Connectors
paths:
  /v1/projects/{projectId}/resource-validations:
    post:
      tags:
        - Resource Validation
      summary: Validate a resource
      description: >-
        Validates an entire pipeline resource file at one of four depths,
        against the environment named in `environmentName`. Depth 1 performs
        basic syntax checking only. Depth 2 additionally resolves basic
        parameters (using the pipeline's own variables and their default values)
        and carries out deeper validation not requiring invocation of the
        Runner. Depth 3 as Depth 2, but performs full parameter resolution,
        invoking the Runner to evaluate JavaScript if required. Depth 4 full
        validation, invoking all Runner capabilities; for transformation
        pipelines, also populates the SQL cache. Components are validated
        against the environment's data warehouse type. Results at depths 1 and 2
        are returned synchronously (200 OK). Depths 3 and 4 return immediately
        (202 Accepted) with a PENDING `operationId`; poll `GET
        /v1/projects/{projectId}/resource-validations/{operationId}` for the
        aggregated result, or cancel via `DELETE`. The request body must contain
        the resource file content with `Content-Type: text/plain`, and can be at
        most 10 MB (10,485,760 bytes); a larger file is rejected with 413
        Content Too Large. Pipeline YAML files (`.orch.yaml`, `.tran.yaml`,
        `.test.yaml`) are the only supported resource type today; the plain-text
        content type is used in anticipation of supporting other resource types
        (such as SQL scripts or Python source files) in future.
      operationId: validateResource
      parameters:
        - description: The UUID of the project the resource belongs to
          in: path
          name: projectId
          required: true
          schema:
            type: string
            format: uuid
        - description: >-
            The ID of the runner to validate against. The runner version is
            derived from this ID, and it must be a runner the project and
            environment can use.
          in: query
          name: runnerId
          required: true
          schema:
            type: string
            minLength: 1
        - description: >-
            The name of the resource file being validated. The file extension
            determines validation behaviour: `.orch.yaml`, `.tran.yaml`, or
            `.test.yaml`.
          in: query
          name: fileName
          required: true
          schema:
            type: string
            minLength: 1
        - description: >-
            The validation depth, from 1 (syntax only) to 4 (full validation,
            invoking all Runner capabilities).
          in: query
          name: depth
          required: false
          schema:
            type: integer
            format: int32
            default: 1
            maximum: 4
            minimum: 1
        - description: >-
            The environment whose parameters, configuration, and data warehouse
            type the resource is validated against. Required at every depth.
          in: query
          name: environmentName
          required: true
          schema:
            type: string
            minLength: 1
      requestBody:
        content:
          text/plain:
            examples:
              Orchestration pipeline:
                description: Orchestration pipeline
                value: |
                  type: orchestration
                  version: '1.0'
                  pipeline:
                    components:
                      my-start:
                        type: start
            schema:
              type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceValidationResponse'
          description: Validation completed (synchronous, depth 1-2)
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceValidationResponse'
          description: Validation accepted for asynchronous processing (depth 3+)
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Invalid request
        '401':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Unauthorized
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Forbidden
        '413':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: The resource file is larger than 10 MB
        '501':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Validation not supported for the requested file type or depth
        '502':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Bad gateway — upstream returned an unexpected error
        '504':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Gateway timeout
components:
  schemas:
    ResourceValidationResponse:
      type: object
      description: The result of a resource validation request.
      properties:
        invalidComponentCount:
          type: integer
          format: int32
          description: >-
            The number of components within the resource that were found to be
            invalid. Present when components were validated individually.
          example: 2
        invalidComponentNames:
          type: array
          description: >-
            The names of components within the resource that were found to be
            invalid.
          example:
            - my-extract-component
            - my-load-component
          items:
            type: string
        messages:
          type: array
          description: >-
            The set of validation findings produced by this validation run.
            Empty for a fully VALID resource.
          items:
            $ref: '#/components/schemas/ResourceValidationMessage'
        operationId:
          type: string
          description: >-
            Identifier of the asynchronous validation operation. Present when
            the status is PENDING.
          example: abc123def456
        status:
          type: string
          description: >-
            Overall validation status. VALID and INVALID are terminal; PENDING
            indicates that asynchronous processing is still in progress and the
            caller should poll the operation ID.
          enum:
            - VALID
            - INVALID
            - PENDING
          example: VALID
    ProblemDetail:
      type: object
      properties:
        detail:
          type: string
        instance:
          type: string
        status:
          type: integer
          format: int32
        title:
          type: string
        type:
          type: string
          format: uri
        violations:
          type: array
          items:
            type: string
    ResourceValidationMessage:
      type: object
      description: >-
        A single validation finding from resource validation, with a severity, a
        human-readable message, and a path identifying the location of the issue
        within the file.
      properties:
        code:
          type: string
          description: >-
            Optional machine-readable code identifying the kind of issue (e.g.
            `MISSING_FIELD`, `PARSE_ERROR`).
          example: MISSING_FIELD
        message:
          type: string
          description: Human-readable description of the issue.
          example: Required field 'type' is missing
        path:
          type: array
          description: >-
            A list of segments identifying the location of the issue within the
            file, e.g. `["pipeline", "components", "<name>", "parameters",
            "<param>"]`.
          example:
            - pipeline
            - components
            - my-component
            - parameters
            - url
          items:
            type: string
        severity:
          type: string
          description: The severity of the finding (ERROR, WARNING, or INFO).
          enum:
            - ERROR
            - WARNING
            - INFO
          example: ERROR
  securitySchemes:
    bearerAuth:
      bearerFormat: JWT
      description: a valid bearer token
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.