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

# Validate agreement structure

> Checks only the authored agreement JSON and returns participant variable keys, input IDs, state IDs, and warnings. This does not validate deployment values, participant wallet addresses, signer, or permit data.

For the complete documentation index, see [llms.txt](https://docs.shodai.network/llms.txt).

This endpoint checks authored agreement JSON only. It does not validate deployment values, participant wallet mappings, signer, or permit data. Generated API examples document request and response shape; complete deployable agreement JSON lives in /examples/simple and /examples/complex.


## OpenAPI

````yaml /openapi.json post /v0/agreements/validate-template
openapi: 3.1.0
info:
  title: Agreements API
  version: v0
  description: Author, deploy, read, and advance agreements through the Agreements API.
servers:
  - url: https://test-api.shodai.network
    description: Public base URL for the Agreements API testnet environment.
  - url: https://api.shodai.network
    description: Public base URL for the Agreements API production environment.
security: []
tags:
  - name: Agreement Records
    description: List and read agreement records.
  - name: Agreement Documents
    description: Resolve hosted agreement prose documents.
  - name: Authoring
    description: Check authored agreement JSON before deployment.
  - name: Deployment
    description: Preflight and deploy agreements.
  - name: Using Agreements
    description: Read state, inspect input history, and submit signed inputs.
  - name: System
    description: Health and OpenAPI discovery endpoints.
paths:
  /v0/agreements/validate-template:
    post:
      tags:
        - Authoring
      summary: Validate agreement structure
      description: >-
        Checks only the authored agreement JSON and returns participant variable
        keys, input IDs, state IDs, and warnings. This does not validate
        deployment values, participant wallet addresses, signer, or permit data.
      operationId: validateAgreementTemplate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              description: Authored agreement JSON to validate before deployment preflight.
            examples:
              agreement:
                summary: Authored agreement JSON
                value:
                  metadata:
                    templateId: did:template:service-retainer-v0-1
                    name: Service Retainer
                  variables:
                    serviceProviderRepresentative:
                      type: address
                      subtype: participant
                      validation:
                        required: true
                    clientRepresentative:
                      type: address
                      subtype: participant
                      validation:
                        required: true
                    retainerTitle:
                      type: string
                      validation:
                        required: true
                  content:
                    type: md
                    data: |-
                      # ${variables.retainerTitle}

                      Service agreement between provider and client.
                  execution:
                    initialize:
                      initialState: AWAITING_PAYMENT
                      data: {}
                    states:
                      AWAITING_PAYMENT:
                        description: Waiting for initial payment proof.
                      WORK_IN_PROGRESS:
                        description: Provider is performing the service.
                    inputs:
                      submitInitialPaymentProof:
                        issuer:
                          type: participant
                          variable: clientRepresentative
                        schema:
                          paymentReference:
                            type: string
                            validation:
                              required: true
                    transitions:
                      - from: AWAITING_PAYMENT
                        to: WORK_IN_PROGRESS
                        conditions:
                          - input: submitInitialPaymentProof
      responses:
        '201':
          description: Agreement structure validation summary.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    $ref: >-
                      #/components/schemas/ValidateDirectAgreementTemplateResponse
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              examples:
                validAgreement:
                  summary: Structure validation result
                  value:
                    data:
                      templateId: did:template:service-retainer-v0-1
                      participantVariableKeys:
                        - serviceProviderRepresentative
                        - clientRepresentative
                      inputIds:
                        - submitInitialPaymentProof
                      stateIds:
                        - AWAITING_PAYMENT
                        - WORK_IN_PROGRESS
                      warnings: []
                    meta:
                      apiVersion: v0
                      requestId: req_123
        '400':
          description: Invalid agreement JSON.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: >-
            The authenticated API principal has paid_required entitlement mode
            for the requested scope. Per-call x402 settlement is not
            implemented. Treat this as an entitlement/operator issue.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The API key is not allowed to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: typescript
          label: SDK
          source: |-
            const result = await client.validateTemplate(agreement);

            console.log(result.participantVariableKeys);
            console.log(result.inputIds);
components:
  schemas:
    ValidateDirectAgreementTemplateResponse:
      type: object
      required:
        - templateId
        - participantVariableKeys
        - inputIds
        - stateIds
        - warnings
      properties:
        templateId:
          oneOf:
            - type: string
            - type: 'null'
          description: Agreement metadata templateId or id value, when present.
        participantVariableKeys:
          type: array
          items:
            type: string
          description: Participant address variable keys found in the agreement JSON.
        inputIds:
          type: array
          items:
            type: string
          description: Input IDs defined in the agreement JSON.
        stateIds:
          type: array
          items:
            type: string
          description: State IDs defined in the agreement JSON.
        warnings:
          type: array
          items:
            type: string
          description: Warnings to review before preparing deployment.
      example:
        templateId: did:template:service-retainer-v0-1
        participantVariableKeys:
          - serviceProviderRepresentative
          - clientRepresentative
        inputIds:
          - submitInitialPaymentProof
        stateIds:
          - AWAITING_PAYMENT
          - WORK_IN_PROGRESS
        warnings: []
    ResponseMeta:
      type: object
      required:
        - apiVersion
        - requestId
      properties:
        apiVersion:
          type: string
          example: v0
        requestId:
          type: string
          description: Correlation ID for support and debugging.
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - requestId
          properties:
            code:
              type: string
              example: unauthorized
              description: Stable machine-readable error code.
            message:
              type: string
              example: Missing API key
              description: Safe human-readable error summary.
            details:
              description: Optional field errors or upstream-safe context.
            requestId:
              type: string
              description: Correlation ID for support and debugging.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Canonical API-key credential. Send X-API-Key: cns_pk_..., or
        Authorization: Bearer cns_pk_... only as an API-key compatibility alias.
        OAuth and JWT bearer tokens are not supported.
      x-default: YOUR_API_KEY

````