Erste Schritte mit der InLoox API

Dieser Leitfaden hilft Ihnen, die Authentifizierung einzurichten, die Grundlagen von OData zu verstehen und Ihre erste API-Anfrage zu senden.

Voraussetzungen

Bevor Sie beginnen, benötigen Sie:

Ein aktives InLoox-Konto (Cloud oder Self-Hosted)
Ein HTTP-Client wie cURL, Postman oder eine Programmiersprache Ihrer Wahl
Ein gültiges persönliches Zugriffstoken, auch Personal Access Token, oder kurz PAT

Token erstellen

Klicken Sie in InLoox oben rechts auf Ihr eigenes Profilbild und dann auf Mein Profil, anschließend auf den Reiter Persönliche Zugriffstoken. Klicken Sie auf Neues Token. Geben Sie einen Token-Namen ein, wählen Sie einen Account aus (falls Sie Zugriff auf mehrere Accounts haben) und klicken Sie auf Neues Token erstellen. Kopieren Sie das generierte Token — es wird nur einmal angezeigt.

info

Bitte beachten Sie, dass für die Verwendung des Tokens die Benutzerberechtigung "Authentifizierung über persönliches Zugriffstoken erlauben" erforderlich ist. Erst dann kann das Token verwendet werden. Diese Berechtigung wird gecached. Es kann bis zu 1h dauern bis die Berechtigung tatsächlich aktiv ist.

Schützen Sie Ihr Token

Ihr Personal Access Token gewährt vollen Zugriff auf die API in Ihrem Namen. Behandeln Sie es wie ein Passwort — committen Sie es niemals in die Versionskontrolle und teilen Sie es nicht öffentlich.

Ein Token ist so mächtig wie der Benutzer, dem es gehört. Für Produktivumgebungen wird empfohlen, ein eigenes Dienst-Benutzerkonto zu erstellen, dessen Berechtigungen auf den tatsächlich genutzen bzw. erforderlichen Mindestumfang beschränkt sind.

Authentifizierung

Die InLoox API verwendet Personal Access Tokens zur Authentifizierung. Senden Sie Ihr Token bei jeder Anfrage als x-api-key-HTTP-Header mit.

cURL

curl -X GET "https://app.inloox.com/api/odata/Project" \
  -H "x-api-key: YOUR_API_TOKEN"

C# (HttpClient)

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_TOKEN");

var response = await client.GetAsync("https://app.inloox.com/api/odata/Project");
var json = await response.Content.ReadAsStringAsync();
Console.WriteLine(json);

C# (Simple.OData.Client)

var settings = new ODataClientSettings(new Uri("https://app.inloox.com/api/odata/"));
settings.BeforeRequest += delegate (HttpRequestMessage message)
{
    message.Headers.Add("x-api-key", "YOUR_API_TOKEN");
};
var client = new ODataClient(settings);

JavaScript (fetch)

const response = await fetch("https://app.inloox.com/api/odata/Project", {
  headers: {
    "x-api-key": "YOUR_API_TOKEN"
  }
});
const data = await response.json();
console.log(data);

Token überprüfen

Eine schnelle Möglichkeit, Ihr Token zu testen, ist der Aufruf des AccountInfo-Endpunkts:

curl -X GET "https://app.inloox.com/api/odata/AccountInfo" \
  -H "x-api-key: YOUR_API_TOKEN"

Bei erfolgreicher Authentifizierung erhalten Sie die Account-Informationen, z. B. die AccountId sowie Namen des Accounts.

Beispiel: Aktuelles Benutzerprofil abrufen

Verwenden Sie den UserInfo/Me()-Endpunkt, um das Profil des aktuell authentifizierten Benutzers abzurufen:

curl -X GET "https://app.inloox.com/api/odata/UserInfo/Me()" \
  -H "x-api-key: YOUR_API_TOKEN"

Antwort:

{
  "ContactId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "FirstName": "Max",
  "LastName": "Mustermann",
  "DisplayName": "Max Mustermann",
  "Email": "max.mustermann@beispiel.de",
  "ImageId": null,
  "NotifyFrequency": 1,
  "TimeZoneInfo": "W. Europe Standard Time",
  "EmailConfirmed": true,
  "IsReader": false,
  "UILanguage": "de-DE"
}

Hinweis

Um die API mit vollem Lese- und Schreibzugriff nutzen zu können, muss Ihr Konto "EmailConfirmed": true und "IsReader": false aufweisen. Benutzer mit einer unbestätigten E-Mail-Adresse oder einer Nur-Lesen-Lizenz (IsReader: true) haben eingeschränkten API-Zugriff.

Basis-URL

Alle API-Anfragen werden gegen eine Basis-URL gestellt, die von Ihrer Bereitstellung abhängt:

Bereitstellung	Basis-URL
InLoox Cloud	`https://app.inloox.com/api/`
InLoox Self-Hosted	`https://YOUR-SELF-HOSTED-URL/api/v1/`

Alle Endpunkt-Pfade in dieser Dokumentation sind relativ zur Basis-URL. Zum Beispiel:

GET /odata/Project

bedeutet, dass die vollständige URL für die Cloud https://app.inloox.com/api/odata/Project lautet.

OData-Grundlagen

Die InLoox API basiert auf dem OData-Protokoll (Open Data Protocol). OData stellt eine standardisierte Abfragesprache bereit, mit der Sie Daten filtern, sortieren, auswählen und paginieren können — direkt über die URL.

Was ist OData?

OData ist ein offener Standard für den Aufbau und die Nutzung von REST APIs. Er definiert bewährte Muster für Abfragen, die über URL-Parameter ($filter, $select, $orderby usw.) gesteuert werden. So können Sie präzise steuern, welche Daten Sie erhalten, ohne dass spezielle Endpunkte erforderlich sind.

Unterstützte HTTP-Methoden

Methode	Verwendung
`GET`	Entitäten oder Sammlungen lesen
`POST`	Neue Entitäten erstellen oder Aktionen aufrufen
`PATCH`	Bestehende Entitäten aktualisieren (Teilaktualisierung)
`DELETE`	Entitäten löschen

Abfrageoptionen

OData unterstützt leistungsfähige Abfrageoptionen als URL-Parameter. Diese ermöglichen es Ihnen, die von der API zurückgegebenen Daten zu filtern, sortieren, paginieren und zu formen.

`$filter` - Daten filtern

Mit $filter schränken Sie die zurückgegebenen Datensätze anhand von Bedingungen ein.

Projekte nach Name filtern:

curl -X GET "https://app.inloox.com/api/odata/Project?\$filter=Name eq 'Mein Projekt'" \
  -H "x-api-key: YOUR_API_TOKEN"

Projekte, die nach einem bestimmten Datum erstellt wurden:

curl -X GET "https://app.inloox.com/api/odata/Project?\$filter=CreatedDateTime gt 2024-01-01T00:00:00Z" \
  -H "x-api-key: YOUR_API_TOKEN"

Mehrere Bedingungen kombinieren (and / or):

curl -X GET "https://app.inloox.com/api/odata/Project?\$filter=IsArchived eq false and Name ne 'Archiviert'" \
  -H "x-api-key: YOUR_API_TOKEN"

Häufige Filteroperatoren:

Operator	Bedeutung	Beispiel
`eq`	Gleich	`Name eq 'Test'`
`ne`	Ungleich	`Status ne 'Closed'`
`gt`	Größer als	`CreatedDateTime gt 2024-01-01T00:00:00Z`
`lt`	Kleiner als	`Progress lt 50`
`ge`	Größer oder gleich	`Progress ge 80`
`le`	Kleiner oder gleich	`Progress le 100`
`and`	Logisches Und	`IsArchived eq false and Progress gt 0`
`or`	Logisches Oder	`Status eq 'Open' or Status eq 'InProgress'`
`contains()`	Enthält	`contains(Name, 'Marketing')`
`startswith()`	Beginnt mit	`startswith(Name, 'Projekt')`

Zeichenkettenwerte in Filtern

Zeichenkettenwerte müssen in einfache Anführungszeichen eingeschlossen werden: Name eq 'Mein Projekt'. GUIDs und Datumsangaben benötigen keine Anführungszeichen.

// C# mit Simple.OData.Client
var projects = await client
    .For<ApiProject>("Project")
    .Filter(p => p.Name == "Website Redesign")
    .FindEntriesAsync();

`$select` - Felder auswählen

Mit $select bestimmen Sie, welche Eigenschaften in der Antwort zurückgegeben werden. Das reduziert die Datenmenge und verbessert die Performance.

curl -X GET "https://app.inloox.com/api/odata/Project?\$select=ProjectId,Name,StartDate,EndDate" \
  -H "x-api-key: YOUR_API_TOKEN"

C#-Beispiel:

var response = await client.GetAsync("Project?$select=ProjectId,Name,StartDate");

// C# mit Simple.OData.Client
var projects = await client
    .For<ApiProject>("Project")
    .Select(p => new { p.ProjectId, p.Name })
    .FindEntriesAsync();

`$orderby` - Sortierung

Mit $orderby sortieren Sie die Ergebnisse nach einer oder mehreren Eigenschaften.

Aufsteigend sortieren (Standard):

curl -X GET "https://app.inloox.com/api/odata/Project?\$orderby=Name" \
  -H "x-api-key: YOUR_API_TOKEN"

Absteigend sortieren:

curl -X GET "https://app.inloox.com/api/odata/Project?\$orderby=CreatedDateTime desc" \
  -H "x-api-key: YOUR_API_TOKEN"

Mehrere Sortierkriterien:

curl -X GET "https://app.inloox.com/api/odata/Project?\$orderby=IsArchived desc,Name asc" \
  -H "x-api-key: YOUR_API_TOKEN"

// C# mit Simple.OData.Client
var projects = await client
    .For<ApiProject>("Project")
    .OrderBy(p => p.StartDate)
    .FindEntriesAsync();

`$top` und `$skip` - Paging

Verwenden Sie $top und $skip, um die Ergebnisse seitenweise abzurufen.

Parameter	Beschreibung	Beispiel
`$top`	Maximale Anzahl zurückgegebener Einträge	`$top=20`
`$skip`	Anzahl zu überspringender Einträge	`$skip=40`

Erste 20 Projekte:

curl -X GET "https://app.inloox.com/api/odata/Project?\$top=20" \
  -H "x-api-key: YOUR_API_TOKEN"

Seite 3 (Elemente 41–60):

curl -X GET "https://app.inloox.com/api/odata/Project?\$top=20&\$skip=40" \
  -H "x-api-key: YOUR_API_TOKEN"

// C# mit Simple.OData.Client
var page2 = await client
    .For<ApiProject>("Project")
    .Skip(10)
    .Top(10)
    .FindEntriesAsync();

Abfrageoptionen kombinieren

Sie können mehrere Abfrageoptionen in einer einzigen Anfrage kombinieren:

# Top 5 offene Aufgaben in einem Projekt, sortiert nach Fälligkeitsdatum, nur Schlüsselfelder
curl "https://app.inloox.com/api/odata/Task?\$filter=ProjectId eq {projectId} and IsDone eq false&\$orderby=EndDateTime asc&\$top=5&\$select=TaskItemId,Name,EndDateTime" \
  -H "x-api-key: YOUR_API_TOKEN"

Paginierung

Die API gibt standardmäßig maximal 100 Elemente pro Anfrage zurück. Um alle Datensätze abzurufen, müssen Sie durch die Seiten paginieren.

Paginierungsstrategie

Senden Sie eine Anfrage mit $top
Prüfen Sie, ob die Antwort ein @odata.nextLink-Feld enthält
Wenn ja, senden Sie die nächste Anfrage an die im @odata.nextLink angegebene URL
Wiederholen Sie, bis kein @odata.nextLink mehr vorhanden ist

Funktionsweise der Paginierung

Wenn weitere Ergebnisse verfügbar sind, enthält die Antwort eine @odata.nextLink-Eigenschaft mit der URL für die nächste Seite:

{
  "@odata.context": "https://app.inloox.com/api/odata/$metadata#Project",
  "value": [ ... ],
  "@odata.nextLink": "https://app.inloox.com/api/odata/Project?$skip=100"
}

Manuelle Paginierung mit `$top` und `$skip`

# Seite 1 (Einträge 1–100)
curl "https://app.inloox.com/api/odata/Project?\$top=100&\$skip=0" \
  -H "x-api-key: YOUR_API_TOKEN"

# Seite 2 (Einträge 101–200)
curl "https://app.inloox.com/api/odata/Project?\$top=100&\$skip=100" \
  -H "x-api-key: YOUR_API_TOKEN"

# Seite 3 (Einträge 201–300)
curl "https://app.inloox.com/api/odata/Project?\$top=100&\$skip=200" \
  -H "x-api-key: YOUR_API_TOKEN"

Manuelles Paging-Beispiel (C#)

var allProjects = new List<ApiProject>();
int skip = 0;
const int pageSize = 100;

while (true)
{
    var response = await client.GetAsync($"Project?$top={pageSize}&$skip={skip}");
    var json = await response.Content.ReadAsStringAsync();
    var page = JsonSerializer.Deserialize<ODataResponse<ApiProject>>(json);

    allProjects.AddRange(page.Value);

    if (page.Value.Count < pageSize)
        break;

    skip += pageSize;
}

Console.WriteLine($"Insgesamt {allProjects.Count} Projekte geladen.");

Paginierung mit Simple.OData.Client (C#)

Die ODataFeedAnnotations-Klasse verarbeitet die Paginierung automatisch:

var allEntries = new List<ApiProject>();
var annotations = new ODataFeedAnnotations();

var page = (await client
    .For<ApiProject>("Project")
    .FindEntriesAsync(annotations)).ToList();

allEntries.AddRange(page);

while (annotations.NextPageLink != null)
{
    page = (await client
        .For<ApiProject>("Project")
        .FindEntriesAsync(annotations.NextPageLink, annotations)).ToList();
    allEntries.AddRange(page);
}

Console.WriteLine($"Insgesamt geladene Projekte: {allEntries.Count}");

Hinweis zur Performance

Wenn Sie große Datensätze abrufen, verwenden Sie $filter, um die Abfrage einzuschränken, anstatt durch alle Datensätze zu paginieren. Dies reduziert sowohl den Netzwerkverkehr als auch die Serverlast.

Antwortformat

Alle API-Antworten verwenden JSON mit OData-Metadaten-Annotationen. Eine typische Sammlungsantwort sieht wie folgt aus:

{
  "@odata.context": "https://app.inloox.com/api/odata/$metadata#Project",
  "value": [
    {
      "ProjectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "Name": "Website Relaunch",
      "StartDate": "2024-01-15T00:00:00Z",
      "EndDate": "2024-06-30T00:00:00Z"
    }
  ]
}

Wichtige Elemente:

Eigenschaft	Beschreibung
`@odata.context`	URL zum Entitäts-Metadatenschema
`value`	Array der Entitäten (bei Sammlungen)
`@odata.nextLink`	URL der nächsten Seite (wenn weitere Daten verfügbar sind)

Eine Einzel-Entität-Antwort (z. B. GET Project({key})) gibt die Entität direkt ohne den value-Wrapper zurück:

{
  "@odata.context": "https://app.inloox.com/api/odata/$metadata#Project/$entity",
  "ProjectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "Name": "Website Relaunch",
  "StartDate": "2024-01-15T00:00:00Z",
  "EndDate": "2024-06-30T00:00:00Z"
}

Fehlerbehandlung

Die API verwendet Standard-HTTP-Statuscodes, um den Erfolg oder Fehler einer Anfrage anzuzeigen.

Statuscode	Bedeutung	Beschreibung
`200 OK`	Erfolg	Die Anfrage war erfolgreich.
`201 Created`	Erstellt	Eine neue Ressource wurde erfolgreich erstellt.
`204 No Content`	Kein Inhalt	Die Anfrage war erfolgreich, es gibt keine Rückgabedaten (z. B. bei DELETE).
`400 Bad Request`	Fehlerhafte Anfrage	Die Anfrage ist ungültig — prüfen Sie die Parameter und den Request-Body.
`401 Unauthorized`	Nicht autorisiert	Das API-Token fehlt oder ist ungültig.
`403 Forbidden`	Zugriff verweigert	Sie haben keine Berechtigung für diese Ressource.
`404 Not Found`	Nicht gefunden	Die angeforderte Ressource existiert nicht.
`429 Too Many Requests`	Ratenbeschränkung	Zu viele Anfragen in einem kurzen Zeitraum.
`500 Internal Server Error`	Serverfehler	Ein interner Fehler ist aufgetreten — kontaktieren Sie den Support.

Fehlerantwort-Beispiel

{
  "error": {
    "code": "400",
    "message": "The query specified in the URI is not valid. Could not find a property named 'InvalidField' on type 'ApiProject'."
  }
}

Tipps zur Fehlerbehebung

401-Fehler: Prüfen Sie, ob der x-api-key-Header korrekt gesetzt ist und das Token gültig ist.
400-Fehler: Überprüfen Sie die Syntax Ihrer OData-Abfrage und die Feldnamen.
404-Fehler: Stellen Sie sicher, dass die Basis-URL und der Endpunkt-Pfad korrekt sind.
Prüfen Sie bei Bedarf die Schreibweise von Eigenschaftsnamen in $select, $filter und $orderby — diese sind groß-/kleinschreibungssensitiv.
Verwenden Sie den $metadata-Endpunkt, um verfügbare Entitäten und Eigenschaften zu inspizieren:
```
GET https://app.inloox.com/api/odata/$metadata
```

Ratenbeschränkungen

Die InLoox API veröffentlicht keine strikten Ratenbeschränkungen, aber folgen Sie diesen Best Practices, um eine Drosselung zu vermeiden:

Lesevorgänge bündeln — Verwenden Sie $filter und $select, um die Anzahl der Anfragen zu minimieren
Nicht aggressiv abfragen — Warten Sie zwischen wiederholten Anfragen mindestens einige Sekunden
Effizient paginieren — Folgen Sie @odata.nextLink statt überlappende Abfragen zu erstellen
Caching verwenden — Speichern Sie Ergebnisse lokal zwischen, wenn sich die Daten nicht häufig ändern

hinweis

Wenn Sie eine 429 Too Many Requests-Antwort erhalten, warten Sie die im Retry-After-Header angegebene Dauer ab, bevor Sie einen neuen Versuch unternehmen.

Nächste Schritte

Sie sind bereit loszulegen! Hier geht es weiter:

Code-Beispiele — Vollständige, funktionierende C#-Beispiele zum Klonen und Ausführen
Projekte — Arbeiten Sie mit der Project-Entität
Aufgaben — Aufgaben abfragen und verwalten
Zeiteinträge — Zeiterfassungsdaten aufzeichnen und abrufen
Dokumentations-MCP — KI-Tools über MCP mit der InLoox-Dokumentation verbinden

Voraussetzungen​

Authentifizierung​

cURL​

C# (HttpClient)​

C# (Simple.OData.Client)​

JavaScript (fetch)​

Basis-URL​

OData-Grundlagen​

Was ist OData?​

Unterstützte HTTP-Methoden​

Abfrageoptionen​

$filter - Daten filtern​

$select - Felder auswählen​

$orderby - Sortierung​

$top und $skip - Paging​

Abfrageoptionen kombinieren​

Paginierung​

Paginierungsstrategie​

Funktionsweise der Paginierung​

Manuelle Paginierung mit $top und $skip​

Manuelles Paging-Beispiel (C#)​

Paginierung mit Simple.OData.Client (C#)​

Antwortformat​

Fehlerbehandlung​

Fehlerantwort-Beispiel​

Ratenbeschränkungen​

Nächste Schritte​