# Bulk API

Der Bulk-Dienst ist für Publisher, CMS-Integrationen, Agenturen und andere professionelle Workflows gedacht. Er stellt sowohl eine browserbasierte Bulk Workspace als auch die serverseitige API bereit.

## Capability

Die Runtime-Lizenz benötigt:

```text
bulk_api
```

Optional kann die Lizenzplattform ein Limit liefern:

```text
bulk_items=250
```

Der effektive Grenzwert ist der kleinere Wert aus Lizenzlimit und `BULK_MAX_ITEMS`.

## Dedizierter Container

`Dockerfile.bulk` verwendet dasselbe getestete Go-Binary, setzt aber sichere Betriebsdefaults:

```text
SERVICE_MODE=bulk
REQUIRE_LICENSE=true
BULK_REQUIRE_API_KEY=true
API_ALLOWED_ORIGIN=
```

Der dedizierte Modus enthält bewusst keine öffentliche Generator-, Produkt- oder Hintergrundseite, stellt aber die spezialisierte Bulk Workspace unter `/` und `/bulk` bereit. Die eigentliche Verarbeitung erfolgt weiterhin über denselben authentifizierten API-Endpunkt.

## Bulk Workspace

Die browserbasierte Oberfläche ist erreichbar unter:

```text
/
/bulk
```

Sie bietet einen visuellen Mehrfach-Workflow, einen erweiterten JSON-Modus, Ergebnislinks sowie JSON-/CSV-Export. Details stehen in [`BULK-WORKSPACE.md`](BULK-WORKSPACE.md).

## Authentifizierung

Bei aktivierter API-Key-Pflicht:

```http
Authorization: Bearer <key>
```

oder:

```http
X-API-Key: <key>
```

Der Schlüssel kann über `BULK_API_KEY_FILE` aus einem Container-/Kubernetes-Secret gelesen werden.

## Anfrage

```http
POST /v1/bulk/declarations
Content-Type: application/json
Authorization: Bearer ...
```

```json
{
  "items": [
    {
      "id": "post-1001",
      "parameters": {
        "mode": "article",
        "lang": "de",
        "textExtent": "none",
        "textReview": "none",
        "coverImageExtent": "full",
        "coverImageReview": "editorial",
        "researchExtent": "assisted",
        "researchReview": "expert",
        "assurance": "technicallyRecorded"
      }
    }
  ]
}
```

Jedes Element wird unabhängig verarbeitet. Ein fachlich fehlerhaftes Element führt zu einem Item-Fehler, ohne die übrigen Elemente zu verwerfen.

## Betriebsgrenzen

- `BULK_MAX_ITEMS` begrenzt Items pro Request;
- `BULK_MAX_BODY_BYTES` begrenzt die Requestgröße;
- ein Lizenzlimit `bulk_items` kann die Itemzahl weiter reduzieren;
- der Dedicated Container wird ohne gültige `bulk_api`-Capability nicht ready;
- bei `REQUIRE_LICENSE=true` werden fachliche Requests ohne gültige Runtime-Lizenz mit 503 blockiert;
- Prometheus exportiert Bulk-Request-, Item- und Failure-Counter.

## Netzwerk

Der Bulk-Service sollte standardmäßig intern betrieben werden. Die Kubernetes-Vorlage liefert nur einen `ClusterIP`-Service und bewusst keinen Ingress. Bei externer Veröffentlichung empfiehlt sich zusätzlich ein API-Gateway mit TLS, Rate-Limiting und organisationsspezifischer Authentifizierung.

## Getrennte Runtime- und Ausgabe-URL

Bei einer separaten Bulk-Instanz kann `BASE_URL` die interne bzw. lizenzgebundene Adresse des Bulk-Dienstes sein, während `OUTPUT_BASE_URL` auf die öffentliche Full-/API-Instanz zeigt:

```env
BASE_URL=http://ai-disclosure-bulk
OUTPUT_BASE_URL=https://ai.example.org
```

Dadurch enthalten Bulk-Ergebnisse nutzbare öffentliche Deklarations-, Manifest- und Badge-URLs.