> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getovra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Intents

> Die Approval-tragende Primitive. Kein Geld bewegt sich ohne genehmigten Intent.

Ein Intent ist eine Deklaration *was* ein Agent zahlen will, *wie viel* und *an wen*. Policy-Engine und Risk-Engine bewerten jeden Intent bevor er settlen kann. `requireIntent` ist eine der [Sacred Invariants](/de/introduction#sacred-invariants) — niemals stillschweigend abgeworfen, niemals umgangen.

## Das Intent-Modell

| Feld                  | Beschreibung                                                                  |
| --------------------- | ----------------------------------------------------------------------------- |
| `id`                  | `int_*`                                                                       |
| `agentId`             | Owning Agent                                                                  |
| `cardId` / `cardName` | Welche Karte zu belasten — genau eines davon                                  |
| `purpose`             | Freitext — sichtbar in Audit und Dashboard                                    |
| `expectedAmountEuros` | Optional aber stark empfohlen                                                 |
| `expectedMerchant`    | Optional aber stark empfohlen                                                 |
| `recurring`           | Optional — `cadence` (`daily`/`weekly`/`monthly`/`yearly`) + Toleranz-Windows |
| `clientIntentId`      | Optionaler client-seitiger Dedupe-Key                                         |
| `ttlMinutes`          | Default 24h, max 30 Tage (`43200`)                                            |
| `status`              | FSM (siehe unten)                                                             |

## Lebenszyklus (FSM)

```text theme={}
pending_approval → approved | denied | expired | cancelled
approved         → completed | failed | expired | cancelled
denied | completed | failed | expired | cancelled = terminal
```

| Status             | Bedeutung                                            |
| ------------------ | ---------------------------------------------------- |
| `pending_approval` | Policy oder Risk verlangt einen Menschen             |
| `approved`         | Auto-approved oder human-approved; bereit zum Zahlen |
| `completed`        | Erfolgreich settled                                  |
| `denied`           | Abgelehnt von Policy oder Risk                       |
| `failed`           | Settlement downstream fehlgeschlagen                 |
| `expired`          | TTL abgelaufen                                       |
| `cancelled`        | Owner cancelled vor Settlement                       |

## Intent erstellen

```bash theme={}
curl -X POST https://api.getovra.com/intents \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "agentId": "ag_...",
    "cardName": "subscriptions",
    "purpose": "Hetzner monatlich verlängern",
    "expectedAmountEuros": 4.51,
    "expectedMerchant": "hetzner.com",
    "ttlMinutes": 60
  }'
```

Response:

```json theme={}
{
  "id": "int_...",
  "status": "approved",
  "expiresAt": "2026-04-20T11:00:00Z",
  "agentId": "ag_...",
  "cardId": "ca_...",
  "expectedAmountEuros": 4.51,
  "expectedMerchant": "hetzner.com"
}
```

Wenn Status `pending_approval` ist, vom Dashboard oder API genehmigen.

## Genehmigen / ablehnen

```bash theme={}
# Genehmigen
curl -X POST https://api.getovra.com/intents/int_.../approve \
  -H "Authorization: Bearer $OVRA_API_KEY"

# Ablehnen
curl -X POST https://api.getovra.com/intents/int_.../deny \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Quartalsbudget aufgebraucht" }'
```

## Recurring Intents

Ein einzelner Intent kann eine Serie von Belastungen autorisieren mit Toleranz-Windows auf Amount und Zeit:

```json theme={}
{
  "agentId": "ag_...",
  "cardName": "subscriptions",
  "purpose": "Hetzner — monatlicher Server",
  "expectedAmountEuros": 4.51,
  "expectedMerchant": "hetzner.com",
  "recurring": {
    "cadence": "monthly",
    "windowStartDaysBefore": 3,
    "windowEndDaysAfter": 2,
    "amountTolerancePercent": 10,
    "merchantMatch": true
  }
}
```

## Verifikation (Post-Settlement)

Nach abgeschlossener Belastung kannst du Actual-Amount und Merchant für Reconciliation aufzeichnen:

```bash theme={}
curl -X POST https://api.getovra.com/intents/int_.../verify \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -d '{
    "actualAmountEuros": 4.51,
    "actualMerchant": "hetzner.com"
  }'
```

Wenn `actualAmountEuros` von `expectedAmountEuros` über die `amountTolerancePercent` der Policy hinaus abweicht, wird der Intent geflaggt.

## Webhooks

| Event              | Wann                           |
| ------------------ | ------------------------------ |
| `intent.created`   | Intent-Insert                  |
| `intent.approved`  | Status-Flip auf `approved`     |
| `intent.denied`    | Policy oder Risk hat abgelehnt |
| `intent.expired`   | TTL erreicht                   |
| `intent.cancelled` | Owner hat cancelled            |

## Surfaces

| Surface   | Capability                                                      |
| --------- | --------------------------------------------------------------- |
| REST      | `/intents`, `/intents/:id/{approve,deny,verify,cancel}`         |
| SDK       | `ovra.intents.*`                                                |
| MCP       | `ovra_intent` (action: `declare` · `get` · `cancel` · `verify`) |
| Dashboard | `/dashboard/intents` (Liste, Drawer, inline Approve/Deny)       |

## Weiter

<CardGroup cols={2}>
  <Card title="Policies" icon="shield-check" href="/de/concepts/policies">
    Die Regeln die `approved` vs `pending_approval` vs `denied` treiben.
  </Card>

  <Card title="Bezahlung" icon="credit-card" href="/de/concepts/pay">
    Was nach `approved` passiert.
  </Card>

  <Card title="Transaktionen" icon="receipt" href="/de/concepts/transactions">
    Der Record den ein settled Intent produziert.
  </Card>

  <Card title="Webhooks" icon="bell" href="/de/concepts/webhooks">
    In Echtzeit auf FSM-Transitions reagieren.
  </Card>
</CardGroup>