---
title: "Create or update phrases"
method: POST
path: "/api/v1/phrases"
tags: ["Phrases"]
---

# Create or update phrases

`POST /api/v1/phrases`

## Request

- Base URL: `https://api.multilocale.com`
- URL: `https://api.multilocale.com/api/v1/phrases`
- Auth: one of:
  - HTTP basic
  - API key in header `Authorization`
  - OAuth 2 (authorization code, authorization URL `https://app.multilocale.com/oauth/authorize`, token URL `https://api.authrice.com/api/oauth/token`, scopes: `phrases:write`)

Upserts one phrase or an array of phrases. Emits `phrase.created` for rows that did not exist and `phrase.updated` for rows that did — one event per row, not per request. Requires the `phrases:write` scope. Send `Idempotency-Key` to make retries safe for 24 hours.

## Headers

- `Idempotency-Key` string

## Request body

- union
  - Phrase
    - `key` string
    - `value` string
    - `language` string
    - `projects` string[]: Project names this phrase belongs to
  - Phrase[]
    - `key` string
    - `value` string
    - `language` string
    - `projects` string[]: Project names this phrase belongs to

## Response `200`

The upserted phrase, or the array of upserted phrases

- union
  - Phrase
    - `key` string
    - `value` string
    - `language` string
    - `projects` string[]: Project names this phrase belongs to
  - Phrase[]
    - `key` string
    - `value` string
    - `language` string
    - `projects` string[]: Project names this phrase belongs to

## Other responses

- `401`: Missing or invalid credentials
- `403`: API key is missing the `phrases:write` scope
- `409`: Idempotency key is in flight or was reused with different input
- `429`: API key rate limit exceeded

---

[API](https://skmtc.dev/multilocale/apis/multilocale-api.md) · [All operations](https://skmtc.dev/multilocale/apis/multilocale-api/llms.txt) · [OpenAPI document](https://skmtc.dev/multilocale/apis/multilocale-api/revisions/9701f774e6c9?raw)