---
title: "Lists all metadata definitions"
method: GET
path: "/metadata-definitions"
tags: ["Metadata"]
---

# Lists all metadata definitions

`GET /metadata-definitions`

## Request

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

Returns the organization's metadata definitions: the custom fields that can hold values on
accounts, bills, contracts, customers, and invoices. Keys are permanent identifiers derived from the name at creation;
API consumers bind to keys, which never change on rename. At most 50 active definitions can
be assigned to one entity type. Definitions are managed in Settings, not through this API.

## Query parameters

- `entity_type` 'ACCOUNT' | 'BILL' | 'CONTRACT' | 'CUSTOMER' | 'INVOICE'
- `status` 'ACTIVE' | 'ARCHIVED': ARCHIVED definitions stop accepting new values but stay readable wherever a value exists.

## Response `200`

OK

- object
  - `metadata_definitions` MetadataDefinition[], required
    - `id` string, uuid, required
    - `key` string, required: Permanent identifier derived from the name at creation, e.g. metadata.source_invoice_id. Never changes on rename; API consumers bind to it.
    - `name` string, required: Display label shown wherever the field is populated.
    - `description` string: Help text shown alongside the input. Omitted when not set.
    - `value_type` 'TEXT', required: TEXT values hold at most 256 characters and no line breaks.
    - `max_length` integer, required: Maximum value length in characters for this definition, owned by the server. Read it from the response rather than hardcoding limits.
    - `entity_types` MetadataEntityType[], required
    - `status` 'ACTIVE' | 'ARCHIVED', required: ARCHIVED definitions stop accepting new values but stay readable wherever a value exists.

## Other responses

- `default`: Error

## Changes

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

[Operation history](https://skmtc.dev/rillet/apis/rillet-accounting-api/changes/metadata-definitions/get.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)