---
title: "Updates contract metadata"
method: PUT
path: "/contracts/{contract_id}/metadata"
tags: ["Contracts"]
---

# Updates contract metadata

`PUT /contracts/{contract_id}/metadata`

## Request

- Base URL: `https://api.rillet.com`
- URL: `https://api.rillet.com/contracts/{contract_id}/metadata`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/rillet/apis/rillet-accounting-api/docs/contracts/:contract_id/metadata/put.ts> (a function with typed inputs; its response is checked against the schema)

IMPORTANT: This is a full-replace operation (PUT semantics). Every active metadata key
omitted from the request body is cleared. To set or clear individual keys without
disturbing the rest, use patch-contract-metadata instead. Null, empty, and
whitespace-only values clear a single key. Archived keys may only be cleared, never changed.
Every key must name a definition assigned to contracts: an unknown key, or one assigned
only to another entity type, fails the request with a 400. Keys are never silently
ignored. The write is atomic: if any key fails validation, nothing is written.
A matching contract "Edit or amend" approval rule holds the change: the request answers 202 with the approval request, and the
contract keeps its values until the request is approved. While another change to the contract waits for approval, the request
is refused.

## Path parameters

- `contract_id` string, required

## Request body

- UpdateMetadataValuesRequest
  - `metadata` object, required: Values keyed by definition key. A full replacement: every active key omitted here is cleared, and null, empty, or whitespace-only values clear one key. Values are trimmed; TEXT values allow at most 256 characters and no line breaks.

## Response `200`

OK

- union
  - MetadataValues
    - `metadata` object, required: Values keyed by definition key. A key with no value on this record is omitted. Use list-all-metadata-definitions for definition names, types and status.
  - ContractPendingApproval: A new contract, or an update to a contract, waiting for approval instead of being applied.
    - `contract_id` string, uuid, required: The id of the contract. A new contract waits as a draft with this id and keeps it once the request is approved; an updated contract keeps its id.
    - `approval_request_id` string, uuid, required: The approval request the contract waits on.

## Other responses

- `202`: Metadata changes are held for approval; the contract keeps its values until the request is approved.
- `default`: Error

## Changes

- **2026-11-03** `c393d0102005`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/rillet/apis/rillet-accounting-api/changes/contracts/:contract_id/metadata/put.md)

---

[API](https://skmtc.dev/rillet/apis/rillet-accounting-api.md) - [All operations](https://skmtc.dev/rillet/apis/rillet-accounting-api/llms.txt) - [OpenAPI document](https://skmtc.dev/rillet/apis/rillet-accounting-api/revisions/c393d0102005?raw)