> ## 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. # List agreements > Lists agreement summaries visible to the current API key. Supports pagination, filtering, and sorting. For the complete documentation index, see [llms.txt](https://docs.shodai.network/llms.txt). Use `client.listAgreements(...)` when integrating with the TypeScript SDK. ## OpenAPI ````yaml /openapi.json get /v0/agreements 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: get: tags: - Agreement Records summary: List agreements description: >- Lists agreement summaries visible to the current API key. Supports pagination, filtering, and sorting. operationId: listAgreements parameters: - name: state in: query required: false schema: type: string description: Optional current agreement state filter. - name: chainId in: query required: false schema: type: integer description: >- Optional deployed agreement chain filter. Use when the environment contains agreements across more than one supported chain. - name: createdAt[gt] in: query required: false schema: type: string format: date-time description: Include records with createdAt greater than this timestamp. - name: createdAt[gte] in: query required: false schema: type: string format: date-time description: >- Include records with createdAt greater than or equal to this timestamp. - name: createdAt[lt] in: query required: false schema: type: string format: date-time description: Include records with createdAt less than this timestamp. - name: createdAt[lte] in: query required: false schema: type: string format: date-time description: Include records with createdAt less than or equal to this timestamp. - name: updatedAt[gt] in: query required: false schema: type: string format: date-time description: Include records with updatedAt greater than this timestamp. - name: updatedAt[gte] in: query required: false schema: type: string format: date-time description: >- Include records with updatedAt greater than or equal to this timestamp. - name: updatedAt[lt] in: query required: false schema: type: string format: date-time description: Include records with updatedAt less than this timestamp. - name: updatedAt[lte] in: query required: false schema: type: string format: date-time description: Include records with updatedAt less than or equal to this timestamp. - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 25 description: Maximum number of records to return. - name: cursor in: query required: false schema: type: string description: Opaque cursor returned by a previous list response. - name: sort[createdAt] in: query required: false schema: type: string enum: - asc - desc default: desc description: Sort by createdAt. Only one sort field may be supplied. - name: sort[updatedAt] in: query required: false schema: type: string enum: - asc - desc description: Sort by updatedAt. Only one sort field may be supplied. - name: sort[displayName] in: query required: false schema: type: string enum: - asc - desc description: Sort by displayName. Only one sort field may be supplied. responses: '200': description: Paged agreement summaries visible to the current API key. content: application/json: schema: type: object required: - data - pageInfo - meta properties: data: type: array items: $ref: '#/components/schemas/AgreementSummary' pageInfo: $ref: '#/components/schemas/PageInfo' meta: $ref: '#/components/schemas/ResponseMeta' examples: agreements: summary: Agreement records visible to the API key value: data: - id: agr_123 address: '0x3333333333333333333333333333333333333333' chainId: 59141 displayName: Advisory Retainer status: Deployed state: AWAITING_PAYMENT templateId: did:template:service-retainer-v0-1 lastInputId: submitInitialPaymentProof lastInputAt: '2026-04-27T16:10:00.000Z' owner: '0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa' documentId: 7b0f6c2d-3e4f-4a5b-8c9d-0e1f2a3b4c5d docUri: >- https://test-api.shodai.network/v0/agreements/documents/7b0f6c2d-3e4f-4a5b-8c9d-0e1f2a3b4c5d createdAt: '2026-04-27T16:00:00.000Z' updatedAt: '2026-04-27T16:05:00.000Z' pageInfo: limit: 25 nextCursor: null totalCount: 1 meta: apiVersion: v0 requestId: req_123 '400': description: Invalid list query. 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: |- import { ApiClient } from '@cns-labs/agreements-api-client'; const client = new ApiClient({ baseUrl: process.env.BASE_URL!, apiKey: process.env.API_KEY, }); const page = await client.listAgreements({ chainId: 59141, state: 'AWAITING_PAYMENT', createdAt: { gte: '2026-05-01T00:00:00.000Z' }, sort: { createdAt: 'desc' }, limit: 25, }); console.log(page.data, page.pageInfo.nextCursor); components: schemas: AgreementSummary: type: object required: - id - chainId - displayName - status - createdAt - updatedAt description: >- Compact agreement record returned by list endpoints. Read a single agreement to retrieve full agreement JSON, participants, observers, and on-chain detail. 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. state: type: string description: Cached agreement state, when available. templateId: type: string description: Agreement metadata templateId or id value, when present. 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. 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}. example: id: agr_123 address: '0x3333333333333333333333333333333333333333' chainId: 59141 displayName: Advisory Retainer status: Deployed state: AWAITING_PAYMENT templateId: did:template:service-retainer-v0-1 lastInputId: submitInitialPaymentProof lastInputAt: '2026-04-27T16:10:00.000Z' owner: '0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa' documentId: 7b0f6c2d-3e4f-4a5b-8c9d-0e1f2a3b4c5d docUri: >- https://test-api.shodai.network/v0/agreements/documents/7b0f6c2d-3e4f-4a5b-8c9d-0e1f2a3b4c5d createdAt: '2026-04-27T16:00:00.000Z' updatedAt: '2026-04-27T16:05:00.000Z' PageInfo: type: object required: - limit - nextCursor properties: limit: type: integer example: 25 nextCursor: oneOf: - type: string - type: 'null' totalCount: type: integer description: Total number of matching records when available. 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 ````