---
title: "Einen Text überall dort ändern, wo er vorkommt"
description: "Ersetzt eine Textpassage in den Inhalten oder im Code einer Website als einen Verlaufseintrag und startet den Build."
canonical: "https://atelier201.com/docs/de/api/content/replace-text"
updated: "2026-11-06"
---

# Einen Text überall dort ändern, wo er vorkommt

Erfordert `sites:write`. Kostet keine Credits. Der Pfad endet mit `/text:replace`. Änderungen betreffen nur den Entwurf. Besucher sehen sie erst, wenn Sie [veröffentlichen](/docs/api/publishing/publish).

Der schnellste Weg, sichtbaren Text zu ändern, wenn Sie nicht wissen, wo er geschrieben steht. Senden Sie `find` mit dem Text, wie er auf der Seite erscheint, und `replace` mit dem neuen Text. Atelier201 durchsucht die Quellen der Website unter `src/` (Inhaltsdateien und Seitencode), ersetzt die Passage, speichert einen Verlaufseintrag und startet den Build. Die Antwort enthält `build` mit dessen ID.

- **Nicht gefunden (`404`).** Der Text steht nicht genau so dort. Eine durch Markup unterbrochene Passage, etwa durch einen Link oder ein hervorgehobenes Wort in der Mitte, ist kein zusammenhängender Text. Senden Sie eine kürzere Passage.
- **Mehrfach gefunden (`409`).** Grenzen Sie die Suche mit `path` ein (Datei oder Glob), senden Sie eine längere Passage oder setzen Sie `all: true`, um alle Vorkommen zu ändern, zum Beispiel eine neue Telefonnummer, die auf mehreren Seiten steht.
- **Inhalte bleiben gültig.** In einer JSON-Inhaltsdatei wird der Text mit JSON-Escaping gesucht und geschrieben. Vor dem Speichern wird die Datei erneut geparst.

Wenn Sie die Adresse eines Felds kennen, etwa `business:/tagline`, verwenden Sie [Ein Feld ändern](/docs/api/content/set-field). Dabei wird der Wert anhand des Inhaltsmodells validiert.

```http
POST https://api.atelier201.com/v1/sites/{site_id}/text:replace
```

## Authorizations

- `Authorization` (bearer, in header, required)

## Path parameters

- `site_id` (`string`, required): ID der Website oder ihr Slug (die Adresse vor .atelier201.page).

## Body

`application/json`, required

- `find` (`string`, required, length: `1–2000 chars`): Der zu ändernde Text, genau so, wie er auf der Seite oder in der Datei steht (einschließlich Groß- und Kleinschreibung sowie Satzzeichen).
- `replace` (`string`, required, length: `≤ 5000 chars`): Der neue Text. Ein leerer Wert entfernt die Passage.
- `path` (`string`, length: `≤ 300 chars`): Nur in dieser Datei (oder diesem Glob, z. B. src/pages/*.astro), wenn der Text mehrfach vorkommt.
- `all` (`boolean`): Alle Vorkommen ändern (etwa bei einem umbenannten Produkt oder einer neuen Telefonnummer). Standard: Ablehnen, wenn der Text mehrmals vorkommt.
- `summary` (`string`, length: `≤ 200 chars`): Ein Satz für den Verlauf. Standard: Change "<text>".

## Response

**200**: Einen Text überall ändern, wo er vorkommt

- `data` (`object`, required)
- `data.replaced` (`integer`, required, range: `-9007199254740991–9007199254740991`): Anzahl der geänderten Vorkommen.
- `data.files` (`object[]`, required)
- `data.files.path` (`string`, required)
- `data.files.occurrences` (`integer`, required, range: `-9007199254740991–9007199254740991`)
- `data.revision` (`string`, required, length: `40–40 chars`): Eine Git-Commit-ID (40 hexadezimale Zeichen) des Repositorys der Website.
- `data.parent` (`string | null`, required)
- `data.changed` (`boolean`, required)
- `data.changes` (`object[]`, required)
- `data.changes.path` (`string`, required)
- `data.changes.action` (`string`, required)
- `data.build` (`object | null`, required): Der Build, den diese Änderung gestartet oder übernommen hat: Die Vorschau folgt diesem Build. Kein Aufruf von build_site erforderlich.
- `data.build.id` (`string`, required)
- `data.build.state` (`string`, required)
- `data.build.next_action` (`string`, required)
- `data.next_action` (`string`, required)
- `request_id` (`string`, required)

```json
{
  "data": {
    "replaced": 123,
    "files": [
      {
        "path": "<string>",
        "occurrences": 123
      }
    ],
    "revision": "<string>",
    "parent": "<string>",
    "changed": true,
    "changes": [
      {
        "path": "<string>",
        "action": "<string>"
      }
    ],
    "build": {
      "id": "<string>",
      "state": "<string>",
      "next_action": "<string>"
    },
    "next_action": "<string>"
  },
  "request_id": "<string>"
}
```

**400**: Mögliche Codes: invalid_request, unknown_field, invalid_parameter, invalid_cursor

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `error.details` (`Record<string, object>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}
```

**401**: Mögliche Codes: authentication_required, invalid_api_key, api_key_expired, api_key_revoked

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `error.details` (`Record<string, object>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}
```

**402**: Mögliche Codes: insufficient_credits

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `error.details` (`Record<string, object>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}
```

**403**: Mögliche Codes: insufficient_scope, feature_not_available, admin_required

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `error.details` (`Record<string, object>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}
```

**404**: Mögliche Codes: resource_not_found

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `error.details` (`Record<string, object>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}
```

**409**: Mögliche Codes: conflict, result_not_ready, idempotency_key_reused

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `error.details` (`Record<string, object>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}
```

**410**: Mögliche Codes: result_expired

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `error.details` (`Record<string, object>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}
```

**413**: Mögliche Codes: request_too_large

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `error.details` (`Record<string, object>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}
```

**422**: Mögliche Codes: request_too_large_for_plan

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `error.details` (`Record<string, object>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}
```

**429**: Mögliche Codes: rate_limited

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `error.details` (`Record<string, object>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}
```

**500**: Mögliche Codes: internal_error

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `error.details` (`Record<string, object>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}
```

**503**: Mögliche Codes: service_unavailable

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `error.details` (`Record<string, object>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}
```

**Example request**

```bash
curl --request POST \
  --url 'https://api.atelier201.com/v1/sites/<site_id>/text:replace' \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "find": "<string>",
  "replace": "<string>"
}'
```