---
title: "Propose a new term, flag a term as redundant or in need of a split, or suggest a change to a term's English metadata"
method: POST
path: "/api/v1/feedback/proposals"
tags: ["Feedback"]
---

# Propose a new term, flag a term as redundant or in need of a split, or suggest a change to a term's English metadata

`POST /api/v1/feedback/proposals`

## Request

- Base URL: `https://glossary.ethereum.org`
- URL: `https://glossary.ethereum.org/api/v1/feedback/proposals`
- Auth: API key in cookie `ethglossary-session`
- TypeScript: <https://skmtc.dev/ethereum/apis/ethglossary-api/docs/api/v1/feedback/proposals/post.ts> (a function with typed inputs; its response is checked against the schema)

One endpoint, one payload shape per `kind`. Metadata kinds carry the hash of the English entry as rendered and are refused with 409 when it has changed. Requires a session cookie.

## Request body

- union
  - object
    - `kind` 'new_term', required
    - `lang` string: Language being reviewed, if a translation is seeded
    - `payload` object, required
      - `term` string, required
      - `definition` string
      - `translation` object
        - `lang` string, required
        - `prose` string, required
    - `reason` string
  - object
    - `kind` 'redundant', required
    - `termId` string, required: A term id, name, alias or variant
    - `hash` string: Content hash of the value as rendered; the server refuses with 409 if it no longer matches
    - `payload` object, required
      - `with` string[], required
    - `reason` string
  - object
    - `kind` 'split', required
    - `termId` string, required: A term id, name, alias or variant
    - `hash` string: Content hash of the value as rendered; the server refuses with 409 if it no longer matches
    - `payload` object, required
      - `into` object[], required
        - `term` string, required
        - `definition` string
    - `reason` string
  - object
    - `kind` 'definition', required
    - `termId` string, required: A term id, name, alias or variant
    - `hash` string, required: Content hash of the value as rendered; the server refuses with 409 if it no longer matches
    - `payload` object, required
      - `definition` string, required
    - `reason` string
  - object
    - `kind` 'note', required
    - `termId` string, required: A term id, name, alias or variant
    - `hash` string, required: Content hash of the value as rendered; the server refuses with 409 if it no longer matches
    - `payload` object, required
      - `note` string, nullable, required: `null` proposes removing the note
    - `reason` string
  - object
    - `kind` 'references', required
    - `termId` string, required: A term id, name, alias or variant
    - `hash` string, required: Content hash of the value as rendered; the server refuses with 409 if it no longer matches
    - `payload` object, required
      - `add` object[]
        - `label` string, required
        - `url` string, uri, required
      - `remove` string[]
    - `reason` string
  - object
    - `kind` 'avoid', required
    - `termId` string, required: A term id, name, alias or variant
    - `hash` string, required: Content hash of the value as rendered; the server refuses with 409 if it no longer matches
    - `payload` object, required
      - `add` string[]
      - `remove` string[]
    - `reason` string
  - object
    - `kind` 'alias', required
    - `termId` string, required: A term id, name, alias or variant
    - `hash` string, required: Content hash of the value as rendered; the server refuses with 409 if it no longer matches
    - `payload` object, required
      - `add` object[]
        - `term` string, required
        - `status` 'preferred' | 'accepted' | 'deprecated'
      - `remove` string[]
    - `reason` string
  - object
    - `kind` 'casing', required
    - `termId` string, required: A term id, name, alias or variant
    - `hash` string, required: Content hash of the value as rendered; the server refuses with 409 if it no longer matches
    - `payload` object, required
      - `casing` 'standard' | 'proper' | 'uppercase' | 'fixed', required
    - `reason` string
  - object
    - `kind` 'category', required
    - `termId` string, required: A term id, name, alias or variant
    - `hash` string, required: Content hash of the value as rendered; the server refuses with 409 if it no longer matches
    - `payload` object, required
      - `category` string, required
    - `reason` string
  - object
    - `kind` 'script_rule', required
    - `termId` string, required: A term id, name, alias or variant
    - `hash` string, required: Content hash of the value as rendered; the server refuses with 409 if it no longer matches
    - `payload` object, required
      - `script_rule` 'translate' | 'calque' | 'transliterate' | 'keep_latin' | 'always_latin' | 'transliterate_with_translation', required
    - `reason` string

## Response `201`

Recorded

- FeedbackProposalResponse
  - `id` string, uuid, required

## Other responses

- `400`: A referenced term does not exist
- `401`: Not signed in
- `403`: Cross-origin request
- `404`: Unknown term or language
- `409`: The value changed since the page loaded; reload
- `415`: Body is not application/json
- `429`: Too many writes; wait
- `503`: Database unavailable

---

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