> For the complete documentation index, see [llms.txt](https://docs.kiloiot.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kiloiot.io/kilo-docs-de/kilo-center/kilo-mioty-service-center/integrations/api-reference.md).

# API-Referenz

KiloCenter-gRPC-API-Referenz — Protokollpuffer-Definitionen für Basisstationen, Endpunkte, mit Online-Portal.

KiloCenter stellt eine gRPC-API bereit, um die Plattform zu integrieren oder zu erweitern. Alle API-Definitionen sind Protocol Buffers und im Repository unter gehostet `KC-Core/api/proto/`.

### Interaktive API-Referenz

Eine durchsuchbare API-Referenz mit allen RPC-Endpunkten ist verfügbar unter:

<https://servicecenter-api.kiloiot.io/>

### gRPC-Übersicht

gRPC ist ein leistungsstarkes RPC-Framework, das Protocol Buffers für die Serialisierung und HTTP/2 für den Transport verwendet. Hintergrundinformationen finden Sie unter [grpc.io](https://grpc.io/).

Die API von KiloCenter ist in drei Proto-Dateien definiert:

| Datei              | Beschreibung                                                                                                   |
| ------------------ | -------------------------------------------------------------------------------------------------------------- |
| `kilocenter.proto` | Einheitlicher, abwärtskompatibler Dienst (alle 117 RPCs)                                                       |
| `core.proto`       | Kern-Domänenmeldungen (Endpunkte, Basisstationen, Nachrichten, Downlinks, Ereignisse, Zertifikate, Blueprints) |
| `identity.proto`   | Identitäts-Domänenmeldungen (Benutzer, Organisationen, API-Schlüssel, Authentifizierung)                       |

### Client-Generierung

**Go (mit buf — Projektstandard):**

```bash
cd KC-Core/api/proto && buf generate
```

Ausgabe: `KC-Core/api/gen/` (nur Go-Stubs — `buf.gen.yaml` konfiguriert Go-Plugins).

**Andere Sprachen (mit protoc):**

```bash
# Python-Beispiel
python -m grpc_tools.protoc \\
  -I KC-Core/api/proto \\
  --python_out=./gen --grpc_python_out=./gen \\
  KC-Core/api/proto/kilocenter.proto \\
  KC-Core/api/proto/core.proto \\
  KC-Core/api/proto/identity.proto
```

`buf.gen.yaml` erzeugt nur Go-Stubs. Für andere Sprachen verwenden Sie protoc oder fügen Sie buf-Plugins hinzu. Siehe [grpc.io/docs/languages](https://grpc.io/docs/languages/) für sprachspezifische Anleitungen.

### Authentifizierung

#### Community Edition

Die Community Edition läuft mit deaktivierter Authentifizierung (`KILOCENTER_AUTH_ENABLED=false`). Für keinen RPC sind Header erforderlich — alle Methoden sind direkt zugänglich.

```bash
# Keine Auth-Header erforderlich
grpcurl -plaintext -d '{}' \\
  localhost:9090 kilocenter.api.v1.KiloCenterService/GetSystemStatus
```

#### Enterprise Edition

Wenn die Authentifizierung aktiviert ist (`KILOCENTER_AUTH_ENABLED=true`), gelten drei Metadaten-Header:

| Header              | Erforderlich für                                                          | Wert                                         |
| ------------------- | ------------------------------------------------------------------------- | -------------------------------------------- |
| `authorization`     | Alle nicht öffentlichen RPCs                                              | `Bearer <JWT_TOKEN>` oder `Bearer <API_KEY>` |
| `x-organization-id` | Alle nicht ausgenommenen RPCs                                             | UUID der Zielorganisation                    |
| `x-user-id`         | RPCs, die ohne JWT aufgerufen werden (nur-Header-Authentifizierungsmodus) | UUID des handelnden Benutzers                |

**Öffentliche Methoden** (keine Header erforderlich): `Login`, `RefreshTokens`, `GetAuthSettings`, `ExchangeOIDC`, `ExchangeOAuth2`, `GetReleaseInfo`, `RegisterAccount` Quelle: `KC-Core/pkg/grpc/public_methods.go`

**Methoden ohne Organisationsheader** (Authentifizierung erforderlich, kein Organisationsheader): `GetSystemStatus`, `GetProfile`, `Abmelden`, `ChangePassword`, CRUD für Benutzer/Organisation/Mitgliedschaft (Organisationskontext wird aus den Request-Feldern aufgelöst) Quelle: `KC-Core/pkg/grpc/public_methods.go` → `OrgExemptMethods`

API-Tokens werden über KC-Web oder den `CreateApiKey` RPC erstellt.

### API-Referenz nach Domäne

#### Endpunkte (7)

`CreateEndPoint`, `GetEndPoint`, `UpdateEndPoint`, `DeleteEndPoint`, `ListEndPoints`, `AttachEndPoint`, `DetachEndPoint`

#### Basisstationen (7)

`CreateBaseStation`, `GetBaseStation`, `UpdateBaseStation`, `DeleteBaseStation`, `ListBaseStations`, `GetBaseStationStats`, `UpdateBaseStationEui`

#### Nachrichten (11)

`GetMessage`, `ListMessages`, `StreamMessages`, `ListBaseStationMessages`, `GetBaseStationMessage`, `GetBaseStationMessageStats`, `SearchBaseStationMessages`, `ExportBaseStationMessages`, `StreamBaseStationMessages`, `ListEndpointMessages`, `ListBaseStationActivity`

#### Downlinks (4)

`SendDownlink`, `RevokeDownlink`, `ListDownlinkQueue`, `GetDownlinkResults`

#### UL-Übertragung (1)

`SendULTransmit`

#### Basisstationssteuerung (2)

`RequestBaseStationStatus`, `InitiatePing`

#### DL-RX-Status (3)

`GetDLRXStatus`, `QueryDLRXStatus`, `GetDLRXStatusQueries`

#### System (3)

`GetSystemStatus`, `GetStatistics`, `GetReleaseInfo`

#### API-Schlüssel (4)

`CreateApiKey`, `GetApiKey`, `DeleteApiKey`, `ListApiKeys`

#### Integrationen (5)

`CreateIntegration`, `GetIntegration`, `UpdateIntegration`, `DeleteIntegration`, `ListIntegrations`

#### Analysen (3)

`GetAnalyticsOverview`, `GetActivityAnalytics`, `GetSignalQualityAnalytics`

#### Ereignisse & Warnungen (8)

`ListEvents`, `ListBaseStationEvents`, `ListEndPointEvents`, `StreamEvents`, `StreamBaseStationEvents`, `StreamEndPointEvents`, `ListAlerts`, `GetAlertSummary`

#### SCACI-Monitoring (6)

`ListScaciSessions`, `GetScaciSession`, `GetScaciStatistics`, `ListScaciErrors`, `ListScaciQueues`, `GetScaciStatus`

#### Zertifikate (6)

`GenerateCertificate`, `DownloadCertificate`, `DownloadBaseStationCertificate`, `GenerateServerCertificates`, `RenewServerCertificates`, `GetServerCertificateStatus`

#### Hersteller (5)

`CreateManufacturer`, `GetManufacturer`, `UpdateManufacturer`, `DeleteManufacturer`, `ListManufacturers`

#### Gerätemodelle (5)

`CreateDeviceModel`, `GetDeviceModel`, `UpdateDeviceModel`, `DeleteDeviceModel`, `ListDeviceModels`

#### Blueprints (8)

`CreateBlueprint`, `GetBlueprint`, `UpdateBlueprint`, `DeleteBlueprint`, `ListBlueprints`, `SetDefaultBlueprint`, `SubmitBlueprintToRegistry`, `CreateDeviceModelWithBlueprint`

#### Blueprint-Dienstprogramme (1)

`DecodePreview`

#### Endpunkt-Statistiken (2)

`GetEndPointStats`, `GetEndPointOperations`

#### Authentifizierung & Sitzung (8) — Enterprise

`Login`, `RefreshTokens`, `GetProfile`, `GetAuthSettings`, `Abmelden`, `ChangePassword`, `ExchangeOIDC`, `ExchangeOAuth2`

#### Self-Service-Registrierung (1) — Enterprise

`RegisterAccount`

#### Benutzer (6) — Enterprise

`CreateUser`, `GetUser`, `UpdateUser`, `DeleteUser`, `ListUsers`, `UpdateUserPassword`

#### Organisationen (5) — Enterprise

`CreateOrganization`, `GetOrganization`, `UpdateOrganization`, `DeleteOrganization`, `ListOrganizations`

#### Organisationsmitgliedschaften (6) — Enterprise

`AddOrganizationUser`, `GetOrganizationUser`, `UpdateOrganizationUser`, `RemoveOrganizationUser`, `ListOrganizationUsers`, `ListUserOrganizations`

### Streaming-RPCs

Fünf RPCs verwenden serverseitiges Streaming, um Echtzeitdaten bereitzustellen:

| RPC                         | Anwendungsfall                          |
| --------------------------- | --------------------------------------- |
| `StreamMessages`            | Echtzeit-Uplink-Nachrichten             |
| `StreamBaseStationMessages` | Nachrichten-Feed der Basisstation       |
| `StreamEvents`              | Benachrichtigungen zu Systemereignissen |
| `StreamBaseStationEvents`   | Ereignis-Feed der Basisstation          |
| `StreamEndPointEvents`      | Ereignis-Feed des Endpunkts             |

```typescript
const stream = client.streamMessages(request, metadata);
stream.on('data', (message) => { /* Nachricht verarbeiten */ });
stream.on('error', (err) => { /* Fehler behandeln */ });
stream.on('end', () => { /* Stream geschlossen */ });
```

### Paginierung

Alle `List*` RPCs unterstützen offset-basierte Paginierung über `page_size` und `page_token` Felder.

**Standard-List-RPCs:** Standard 20, max. 100 **Listen mit hohem Volumen** (Endpunkte, Basisstationen, Downlinks): Standard 100, max. 1000

Quelle: `KC-Core/pkg/grpc/pagination.go`

```protobuf
message ListEndPointsRequest {
  int32 page_size = 1;    // Standard 20, max. 100
  string page_token = 2;  // Aus dem vorherigen ListEndPointsResponse.next_page_token
}
```

### Fehlerbehandlung

Alle Fehler verwenden gRPC-Statuscodes mit maschinenlesbaren Fehler-Token aus `KC-Core/pkg/grpc/errors_catalog.go`.

| gRPC-Code                 | HTTP-Äquivalent | Häufige Ursachen                        |
| ------------------------- | --------------- | --------------------------------------- |
| `INVALID_ARGUMENT` (3)    | 400             | Fehlerhafte Anfrage, Validierungsfehler |
| `NOT_FOUND` (5)           | 404             | Ressource existiert nicht               |
| `ALREADY_EXISTS` (6)      | 409             | Doppelte Ressource                      |
| `PERMISSION_DENIED` (7)   | 403             | Autorisierungsfehler                    |
| `UNAUTHENTICATED` (16)    | 401             | Fehlendes oder ungültiges Token         |
| `FAILED_PRECONDITION` (9) | 400             | Statusbasierter Fehler                  |
| `INTERNAL` (13)           | 500             | Serverfehler                            |

Das vollständige Fehlermodell und die Fehler-Token-Bereiche finden Sie in docs/api.md.

### API-Konsole

gRPC-Reflection ist auf KC-Gateway aktiviert. Kompatible Tools:

```bash
# grpcui — interaktive Weboberfläche
grpcui -plaintext localhost:9090

# grpcurl — Befehlszeilen-Client
grpcurl -plaintext localhost:9090 list

# Postman — verwenden Sie den gRPC-Tab mit Server-Reflection
# BloomRPC — Desktop-gRPC-Client
```

### Weiterführende Literatur

* Vollständige API-Referenz — Anfrage-/Antwortverträge und Fehler-Token-Bereiche
* Proto-Quelldateien — kanonische API-Definitionen
* gRPC First Steps — Konnektivität prüfen und Methoden entdecken


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.kiloiot.io/kilo-docs-de/kilo-center/kilo-mioty-service-center/integrations/api-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.