> ## 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.

# Get agreement

> Returns a single agreement record, including agreement JSON and hosted record context.

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

Use `client.getAgreement(...)` to retrieve the hosted record and agreement JSON before operating on a deployed agreement.


## OpenAPI

````yaml /openapi.json get /v0/agreements/{id}
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/{id}:
    get:
      tags:
        - Agreement Records
      summary: Get agreement
      description: >-
        Returns a single agreement record, including agreement JSON and hosted
        record context.
      operationId: getAgreement
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Agreement ID or deployed agreement address.
      responses:
        '200':
          description: Agreement record.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    $ref: '#/components/schemas/AgreementRecord'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
              examples:
                agreement:
                  summary: Agreement record
                  value:
                    data:
                      id: agr_123
                      address: '0x3333333333333333333333333333333333333333'
                      chainId: 59141
                      displayName: Advisory Retainer
                      status: Deployed
                      json:
                        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
                      state: AWAITING_PAYMENT
                      variables:
                        serviceProviderRepresentative: '0x1111111111111111111111111111111111111111'
                        clientRepresentative: '0x2222222222222222222222222222222222222222'
                        retainerTitle: Advisory Retainer
                      owner: '0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'
                      documentId: 7b0f6c2d-3e4f-4a5b-8c9d-0e1f2a3b4c5d
                      docUri: >-
                        https://test-api.shodai.network/v0/agreements/documents/7b0f6c2d-3e4f-4a5b-8c9d-0e1f2a3b4c5d
                      contributors:
                        - '0x1111111111111111111111111111111111111111'
                        - '0x2222222222222222222222222222222222222222'
                      participants:
                        - variableKey: serviceProviderRepresentative
                          walletAddress: '0x1111111111111111111111111111111111111111'
                        - variableKey: clientRepresentative
                          walletAddress: '0x2222222222222222222222222222222222222222'
                          email: client@example.com
                      observers:
                        - legal@example.com
                      createdAt: '2026-04-27T16:00:00.000Z'
                      updatedAt: '2026-04-27T16:05:00.000Z'
                    meta:
                      apiVersion: v0
                      requestId: req_123
        '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'
        '404':
          description: Agreement not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: typescript
          label: SDK
          source: const agreement = await client.getAgreement('agr_123');
components:
  schemas:
    AgreementRecord:
      type: object
      required:
        - id
        - chainId
        - displayName
        - status
        - json
        - createdAt
        - updatedAt
      description: >-
        Hosted record for an authored or deployed agreement. Use the state and
        input-history routes when you need current execution state or submitted
        input history.
      properties:
        id:
          type: string
          description: Agreement record ID.
        address:
          type: string
          description: Deployed agreement address, when deployed.
        chainId:
          type: integer
          description: Chain ID for the deployed agreement.
        status:
          type: string
          enum:
            - Draft
            - Deployed
          description: Agreement record status.
        lastInputId:
          type: string
          description: Most recent submitted input ID, when available.
        lastInputAt:
          type: string
          format: date-time
          description: Time of the most recent submitted input, when available.
        json:
          type: object
          additionalProperties: true
          description: Authored agreement JSON.
        state:
          type: string
          description: Cached agreement state, when available.
        variables:
          type: object
          additionalProperties: true
          description: Current stored agreement values.
        updatedAt:
          type: string
          format: date-time
          description: Record update timestamp.
        createdAt:
          type: string
          format: date-time
          description: Record creation timestamp.
        displayName:
          type: string
          description: Human-readable record label.
        owner:
          type: string
          description: Wallet address associated with hosted record ownership.
        documentId:
          type: string
          description: >-
            Opaque hosted agreement document identifier used by
            /agreements/documents/{documentId}.
        docUri:
          type: string
          description: >-
            Optional document URI associated with the deployed agreement,
            typically /agreements/documents/{documentId}.
        contributors:
          type: array
          items:
            type: string
          description: Wallet addresses associated with agreement activity.
        participants:
          type: array
          items:
            $ref: '#/components/schemas/ParticipantRecord'
          description: Participants associated with agreement participant variables.
        observers:
          type: array
          items:
            type: string
            format: email
          description: Observer email addresses associated with the agreement record.
        onChain:
          type: object
          additionalProperties: true
          description: On-chain agreement data when available.
      example:
        id: agr_123
        address: '0x3333333333333333333333333333333333333333'
        chainId: 59141
        displayName: Advisory Retainer
        status: Deployed
        json:
          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
        state: AWAITING_PAYMENT
        variables:
          serviceProviderRepresentative: '0x1111111111111111111111111111111111111111'
          clientRepresentative: '0x2222222222222222222222222222222222222222'
          retainerTitle: Advisory Retainer
        owner: '0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'
        documentId: 7b0f6c2d-3e4f-4a5b-8c9d-0e1f2a3b4c5d
        docUri: >-
          https://test-api.shodai.network/v0/agreements/documents/7b0f6c2d-3e4f-4a5b-8c9d-0e1f2a3b4c5d
        contributors:
          - '0x1111111111111111111111111111111111111111'
          - '0x2222222222222222222222222222222222222222'
        participants:
          - variableKey: serviceProviderRepresentative
            walletAddress: '0x1111111111111111111111111111111111111111'
          - variableKey: clientRepresentative
            walletAddress: '0x2222222222222222222222222222222222222222'
            email: client@example.com
        observers:
          - legal@example.com
        createdAt: '2026-04-27T16:00:00.000Z'
        updatedAt: '2026-04-27T16:05:00.000Z'
    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.
    ParticipantRecord:
      type: object
      required:
        - variableKey
      properties:
        variableKey:
          type: string
          description: Participant address variable key in the agreement JSON.
        email:
          type: string
          format: email
          description: Participant email context.
        firstName:
          type: string
          description: Participant first name, when available.
        lastName:
          type: string
          description: Participant last name, when available.
        walletAddress:
          type: string
          description: Participant wallet address, when available.
        walletBinding:
          type: string
          enum:
            - verified_via_auth
            - partner_asserted
          description: Wallet provenance recorded by the API.
        status:
          type: string
          enum:
            - pending
            - invited
            - accepted
          description: Participant invitation or acceptance status when available.
      example:
        variableKey: clientRepresentative
        email: client@example.com
        walletAddress: '0x2222222222222222222222222222222222222222'
        walletBinding: partner_asserted
        status: accepted
  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

````