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

# Metadaten

> Füge benutzerdefinierte Schlüssel-Wert-Paare zu API-Ressourcen hinzu

<Info>
  **Derzeit verfügbar für [Batches](/api-reference/batches/create).** Unterstützung für Scrapes, Crawls, Maps und Answers kommt bald.
</Info>

Metadaten ermöglichen es dir, benutzerdefinierte Schlüssel-Wert-Paare zu Olostep-Ressourcen hinzuzufügen. Dies ist nützlich für das Tracking, Filtern, Organisieren und Speichern von Kontext zusammen mit deinen API-Anfragen.

Metadaten folgen [Stripes Ansatz](https://stripe.com/docs/api/metadata) — einfach, flexibel und konsistent über alle Endpunkte hinweg.

***

## Anwendungsfälle

<CardGroup cols={2}>
  <Card title="Tracking & Organisation" icon="folder">
    Verknüpfe Ressourcen mit internen Systemen über Bestell-IDs, Kunden-IDs oder Projektnamen.
  </Card>

  <Card title="Filtern & Suche" icon="magnifying-glass">
    Markiere Ressourcen für einfache Abrufbarkeit und Filterung in deiner Anwendung.
  </Card>

  <Card title="Workflow-Kontext" icon="diagram-project">
    Speichere Pipeline-Status, Prioritätsstufen oder Verarbeitungsanweisungen.
  </Card>

  <Card title="Audit-Trail" icon="clock-rotate-left">
    Zeichne auf, wer eine Anfrage initiiert hat, Zeitstempel oder Versionsinformationen.
  </Card>
</CardGroup>

***

## Hinzufügen von Metadaten bei der Erstellung

Füge den `metadata`-Parameter hinzu, wenn du eine Ressource erstellst:

<CodeGroup>
  ```json Request Body theme={null}
  {
    "url": "https://example.com",
    "metadata": {
      "order_id": "12345",
      "customer_name": "John Doe",
      "priority": "high",
      "internal_ref": "proj-2024-001"
    }
  }
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.olostep.com/v1/batches",
      headers={"Authorization": "Bearer <your_token>"},
      json={
          "items": [{"custom_id": "1", "url": "https://example.com"}],
          "metadata": {
              "project": "q4-analysis",
              "team": "data-ops",
              "priority": "high"
          }
      }
  )
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.olostep.com/v1/batches", {
    method: "POST",
    headers: {
      "Authorization": "Bearer <your_token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      items: [{ custom_id: "1", url: "https://example.com" }],
      metadata: {
        project: "q4-analysis",
        team: "data-ops",
        priority: "high"
      }
    })
  });
  ```
</CodeGroup>

Metadaten werden in allen nachfolgenden GET-Antworten für diese Ressource zurückgegeben.

***

## Validierungsregeln

| Einschränkung            | Limit                  | Fehlerbeispiel                                                                          |
| ------------------------ | ---------------------- | --------------------------------------------------------------------------------------- |
| Maximale Schlüsselanzahl | 50                     | `"Metadaten können maximal 50 Schlüssel haben. Du hast 51 Schlüssel bereitgestellt."`   |
| Schlüssellänge           | 40 Zeichen             | `"Metadatenschlüssel \"my_very_long_key_name...\" überschreitet das 40-Zeichen-Limit."` |
| Schlüsselformat          | Keine eckigen Klammern | `"Metadatenschlüssel \"items[0]\" darf keine eckigen Klammern ([ oder ]) enthalten."`   |
| Wertlänge                | 500 Zeichen            | `"Metadatenwert für Schlüssel \"description\" überschreitet das 500-Zeichen-Limit."`    |
| Werttyp                  | Nur Zeichenketten      | `"Metadatenwert für Schlüssel \"count\" muss eine Zeichenkette sein. Objekt erhalten."` |

<Note>
  **Typumwandlung**: Zahlen und Booleans werden automatisch in Zeichenketten umgewandelt.

  * `42` → `"42"`
  * `true` → `"true"`
  * `3.14` → `"3.14"`

  Objekte und Arrays werden abgelehnt.
</Note>

***

## Aktualisieren von Metadaten (PATCH)

<Info>
  **Derzeit verfügbar für:** Nur [Batches](/api-reference/batches/update).

  Crawls, Scrapes, Maps und Answers unterstützen noch nicht das Aktualisieren von Metadaten nach der Erstellung.
</Info>

Du kannst Metadaten bei bestehenden Batches mit dem [PATCH-Endpunkt](/api-reference/batches/update) aktualisieren. Updates verwenden ein Merge-Verhalten.

### Update-Operationen

<AccordionGroup>
  <Accordion title="Neue Schlüssel hinzufügen" icon="plus">
    Neue Schlüssel werden hinzugefügt, während bestehende beibehalten werden.

    ```bash theme={null}
    curl -X PATCH "https://api.olostep.com/v1/batches/batch_abc123" \
      -H "Authorization: Bearer <your_token>" \
      -H "Content-Type: application/json" \
      -d '{"metadata": {"new_key": "new_value"}}'
    ```

    **Vorher:** `{"project": "alpha"}`\
    **Nachher:** `{"project": "alpha", "new_key": "new_value"}`
  </Accordion>

  <Accordion title="Bestehende Schlüssel aktualisieren" icon="pen">
    Bestehende Schlüssel werden mit neuen Werten überschrieben.

    ```bash theme={null}
    curl -X PATCH "https://api.olostep.com/v1/batches/batch_abc123" \
      -H "Authorization: Bearer <your_token>" \
      -H "Content-Type: application/json" \
      -d '{"metadata": {"project": "beta"}}'
    ```

    **Vorher:** `{"project": "alpha", "priority": "high"}`\
    **Nachher:** `{"project": "beta", "priority": "high"}`
  </Accordion>

  <Accordion title="Bestimmte Schlüssel löschen" icon="trash">
    Setze einen Schlüssel auf `null` oder `""` (leere Zeichenkette), um ihn zu löschen.

    ```bash theme={null}
    curl -X PATCH "https://api.olostep.com/v1/batches/batch_abc123" \
      -H "Authorization: Bearer <your_token>" \
      -H "Content-Type: application/json" \
      -d '{"metadata": {"priority": null}}'
    ```

    **Vorher:** `{"project": "alpha", "priority": "high"}`\
    **Nachher:** `{"project": "alpha"}`
  </Accordion>

  <Accordion title="Alle Metadaten löschen" icon="eraser">
    Setze das gesamte Metadatenfeld auf `null` oder `""`, um alle Schlüssel zu entfernen.

    ```bash theme={null}
    curl -X PATCH "https://api.olostep.com/v1/batches/batch_abc123" \
      -H "Authorization: Bearer <your_token>" \
      -H "Content-Type: application/json" \
      -d '{"metadata": null}'
    ```

    **Vorher:** `{"project": "alpha", "priority": "high"}`\
    **Nachher:** `{}`
  </Accordion>

  <Accordion title="Gemischte Operationen" icon="shuffle">
    Füge hinzu, aktualisiere und lösche Schlüssel in einer einzigen Anfrage.

    ```bash theme={null}
    curl -X PATCH "https://api.olostep.com/v1/batches/batch_abc123" \
      -H "Authorization: Bearer <your_token>" \
      -H "Content-Type: application/json" \
      -d '{"metadata": {"project": "gamma", "new_field": "value", "old_field": null}}'
    ```

    **Vorher:** `{"project": "alpha", "old_field": "remove_me"}`\
    **Nachher:** `{"project": "gamma", "new_field": "value"}`
  </Accordion>
</AccordionGroup>

### Zusammenfassung des PATCH-Verhaltens

| Operation               | Anfrage                                   | Ergebnis                                   |
| ----------------------- | ----------------------------------------- | ------------------------------------------ |
| Schlüssel hinzufügen    | `{"metadata": {"new": "value"}}`          | Schlüssel hinzugefügt, andere beibehalten  |
| Schlüssel aktualisieren | `{"metadata": {"existing": "new_value"}}` | Schlüssel aktualisiert, andere beibehalten |
| Schlüssel löschen       | `{"metadata": {"key": null}}`             | Schlüssel entfernt, andere beibehalten     |
| Schlüssel löschen       | `{"metadata": {"key": ""}}`               | Schlüssel entfernt, andere beibehalten     |
| Alle löschen            | `{"metadata": null}`                      | Alle Schlüssel entfernt                    |
| Alle löschen            | `{"metadata": ""}`                        | Alle Schlüssel entfernt                    |
| Keine Änderung          | `{"metadata": {}}`                        | Keine Änderungen                           |