# Automatisierung anlegen (https://developer.bimetrics.de/reference/automations/create-automation)

`POST https://app.bimetrics.de/api/agent-rule-group/`

operationId: `createAutomation` · Berechtigung (Scope): `automations:write` · Bereich: Automatisierungen

Legt eine Automatisierung mit ihren Regeln an, wie das Formular der App. Feste Regeln greifen ab jetzt beim Upload und nach Korrekturen; vorhandene Belege bleiben, wie sie sind. Eine feste Regel braucht mindestens eine Bedingung und eine Kategorie (`targetCategory`), `mode` ist `all` oder `any`. `setKind` geht nur zusammen mit einer Kategorie, die zu diesem Belegtyp passt. Kategorien, die bimetrics nur selbst setzt oder die es nur für Buchungen ohne Beleg gibt, lässt eine feste Regel nicht zu. Prüft sie den Belegtyp (`match.kind`), ohne ihn zu setzen, muss die Kategorie zu diesem Belegtyp passen. Bereits gespeicherte Regeln mit derselben `id` bleiben erlaubt, solange `targetCategory`, `setKind` und `match.kind` unverändert sind. Verstößt eine Regel dagegen, antwortet die Route mit `400`, `context.field` nennt das Feld (etwa `rules[0].targetCategory`) und `detail` den Satz der App; gespeichert wird nichts. Höchstens 100 Automatisierungen sind gleichzeitig aktiv, eine weitere aktive ergibt `409 AgentRuleGroupActiveLimit`. Jede Regel bekommt eine `id`; schick sie beim Ändern mit, damit ihre Treffer bei ihr bleiben. Bei einer Wiederholung schickst du denselben Idempotency-Key.

Benötigt einen Schlüssel mit der Berechtigung `automations:write`.

> **Achtung:** Ändert Daten der Firma; wird atomar mit Idempotenzbeleg und Herkunft protokolliert.
>
> KI-Agenten fragen vor diesem Aufruf beim Nutzer nach.

### Authentifizierung

`Authorization: Bearer bm_…` (alternativ `X-API-KEY: bm_…`, nie beide zugleich).

### Parameter

| Name | Ort | Pflicht | Typ | Beschreibung |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | ja | string | Stabiler Schlüssel für genau diese Änderung: 1–128 druckbare ASCII-Zeichen ohne Leerzeichen. Bei Wiederholungen denselben Schlüssel und unveränderten Inhalt senden; das Ergebnis wird nicht nochmals erzeugt. |

### Request-Body (`application/json`)

 

Schema `AutomationWrite`.

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `active` | boolean | `true`: Ihre Regeln wirken auf neue Uploads und Korrekturen. Höchstens 100 Automatisierungen sind gleichzeitig aktiv. |
| `displayName` | string | Name der Automatisierung. |
| `expectedUpdatedAt` | string (date-time) | `updatedAt` der gelesenen Automatisierung, beim Ändern Pflicht. |
| `rules` | Array<AutomationRule>, kann null sein | Alle Regeln; beim Ändern ersetzen sie die bisherigen. |

### Beispiel

```sh
curl --fail-with-body "https://app.bimetrics.de/api/agent-rule-group/" \
  -H "Authorization: Bearer $BIMETRICS_API_KEY" \
  -H "Idempotency-Key: rechnung-2026-001" \
  -H "Content-Type: application/json" \
  -d '{"kind":"and","children":[],"limit":50,"offset":0}'
```

### Antworten

| Status | Beschreibung | Inhalt |
| --- | --- | --- |
| 200 | Erfolg. | `application/json`: Automation |
| 400 | Ungültige Anfrage, z. B. ein Parameter mit ungültigem Wert wie eine ID, die keine UUID ist; korrigieren statt wiederholen. Mehr unter [Fehler](https://developer.bimetrics.de/errors). | `application/json`: Error |
| 401 | Kein gültiger Schlüssel: fehlt (`Unauthorized`), ist unbekannt, abgelaufen oder widerrufen oder wurde nicht in genau einem Header gesendet (`InvalidAPIKey`). Schlüssel prüfen, nicht wiederholen. Auch eine ID, die zu einer anderen Firma gehört, ergibt `401 Unauthorized`. | `application/json`: Error |
| 402 | Der Tarif der Firma enthält keine Automatisierungen (`PlanRequired`, `context.gate` ist `feature_rules`, `context.nextStep` nennt den Weg zum passenden Tarif). Nach einem Tarifwechsel erneut senden. | `application/json`: Error |
| 403 | Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt (`APIKeyPermissionDenied`, `context.scope` nennt sie; Berechtigungen sind fest: neuen Schlüssel anlegen, austauschen, alten widerrufen), der Endpunkt ist für API-Schlüssel nicht freigegeben (`APIKeyPermissionDenied` ohne `context.scope`), oder die Firma hat keinen API-Zugang (mehr), etwa nach Ende der Testphase oder des Abos (`APIUnavailable`). | `application/json`: Error |
| 409 | Versionskonflikt (`VersionConflict`), abweichender Inhalt für denselben Idempotency-Key (`IdempotencyConflict`), Dublette (`ContactDuplicate`) oder fachlich gesperrte Änderung. Aktuellen Zustand laden und prüfen; keinen anderen Schlüssel verwenden, um einen Konflikt zu umgehen. | `application/json`: Error |
| 413 | Die Anfrage ist zu groß (`APIRequestTooLarge`), siehe `x-bimetrics-limits`. | `application/json`: Error |
| 429 | Zu viele Anfragen; nach `Retry-After` Sekunden erneut senden. Mehr unter [Fehler](https://developer.bimetrics.de/errors). (Header: Retry-After) | `application/json`: Error |
| 500 | Serverfehler; die Anfrage später wiederholen. Mehr unter [Fehler](https://developer.bimetrics.de/errors). | `application/json`: Error |

#### Felder der Antwort 200 (`Automation`)

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `active` | boolean | `true`: Ihre Regeln wirken auf neue Uploads und Korrekturen. |
| `companyId` | string (uuid) | ID der Firma. |
| `createdAt` | string (date-time) | Zeitpunkt des Anlegens. |
| `displayName` | string | Name der Automatisierung. |
| `id` | string (uuid) | ID der Automatisierung. |
| `rules` | Array<AutomationRule>, kann null sein | Die Regeln der Automatisierung. |
| `updatedAt` | string (date-time) | Zeitpunkt der letzten Änderung; beim Ändern als `expectedUpdatedAt` zurückschicken. |

Verschachtelte Schemas stehen vollständig in der OpenAPI-Beschreibung: https://app.bimetrics.de/api/openapi.json
