API Documentation

Build integrations with SHELF using our RESTful JSON API. Manage inventory, shopping lists, and storage locations programmatically.

Base URL

https://myshelf.life/api/v1

Authentifizierung

Alle API-Anfragen müssen einen gültigen API-Schlüssel im Authorization-Header enthalten.

Authorization: Bearer YOUR_API_KEY

Berechtigungsstufen

Nur lesen: Kann Daten abrufen (GET-Anfragen)
Lesen & Schreiben: Kann Daten abrufen und ändern (alle Anfragen)

Fehlerantworten

Bei Fehlern gibt die API einen JSON-Body mit Fehlerdetails zurück.

401 Ungültiger oder fehlender API-Schlüssel

{"error": "Invalid or disabled API key", "code": "unauthorized"}

403 Unzureichende Berechtigungen

{"error": "This API key does not have write permissions", "code": "forbidden"}

404 Ressource nicht gefunden

{"error": "Resource not found", "code": "not_found"}

422 Validierungsfehler

{"error": "Name can't be blank", "code": "unprocessable_entity", "details": {"name": ["can't be blank"]}}

Endpunkte

Lese-Endpunkte

GET /api/v1/locations

Gibt alle aktiven Lagerorte deines Haushalts zurück.

Beispielantwort

{
  "locations": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Kühlschrank",
      "icon": "🧊",
      "location_type": "standard",
      "is_default": true,
      "items_count": 15,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

GET /api/v1/inventory

Gibt alle Lagerorte mit ihren Artikeln zurück.

Beispielantwort

{
  "locations": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Kühlschrank",
      "icon": "🧊",
      "location_type": "standard",
      "items": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440003",
          "name": "Milch",
          "quantity": 2.0,
          "unit": "Liter",
          "category": "dairy",
          "icon": "🥛",
          "expires_on": "2026-03-01",
          "status": "ok",
          "notes": "Bio",
          "added_by": "Max",
          "created_at": "2026-01-15T10:30:00Z"
        }
      ]
    }
  ]
}

GET /api/v1/shopping_list

Gibt die aktive Einkaufsliste mit allen nicht abgehakten Artikeln zurück.

Beispielantwort

{
  "shopping_list": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "name": "Einkaufsliste",
    "active_count": 5,
    "items": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440002",
        "name": "Milch",
        "quantity": 2.0,
        "unit": "Liter",
        "category": "dairy",
        "added_by": "Max",
        "created_at": "2024-01-20T14:00:00Z"
      }
    ]
  }
}

GET /api/v1/household_actions

Gibt alle Haushaltsaktionen (aktive und inaktive) mit ihrem aktuellen claimed_today-Status zurück.

Beispielantwort

{
  "household_actions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Take out trash",
      "emoji": "🗑️",
      "points": 10,
      "active": true,
      "category": "Trash & Recycling",
      "category_emoji": "🗑️",
      "position": 0,
      "claimed_today": true,
      "created_at": "2026-01-15T10:30:00Z"
    }
  ]
}

GET /api/v1/bonus_points

Gibt die Bonuspunkte des API-Nutzers für die aktuelle Woche und insgesamt zurück, sowie das Haushalts-Ranking (ein Eintrag pro Haushaltsmitglied, sortiert nach Wochenpunkten). Rückgängig gemachte Aktivitäten werden nicht gezählt.

Beispielantwort

{
  "week": {
    "start": "2026-05-04",
    "end": "2026-05-10",
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Hendrik",
      "score": 35
    },
    "standings": [
      { "user_id": "550e8400-e29b-41d4-a716-446655440000", "name": "Hendrik", "score": 35, "rank": 1 },
      { "user_id": "660e8400-e29b-41d4-a716-446655440000", "name": "Partner",  "score": 20, "rank": 2 }
    ]
  },
  "all_time": {
    "user": { "score": 1250, "activity_count": 217 }
  }
}

GET /api/v1/bonus_points/activities

Gibt die letzten Bonus-Aktionen des Haushalts zurück (custom_action-Aktivitäten). Neueste zuerst.

Query Parameters

Field	Type	Description
limit	integer	Optional. Maximale Anzahl zurückgegebener Aktivitäten (Standard 50, Maximum 200).
since	iso8601	Optional. ISO8601-Zeitstempel; gibt nur Aktivitäten zurück, die ab dieser Zeit erstellt wurden.
user_id	uuid	Optional. UUID eines Haushaltsmitglieds zum Filtern.
include_undone	boolean	Optional. "false" angeben, um rückgängig gemachte Aktivitäten auszuschließen (Standard: true).

Beispielantwort

{
  "activities": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440000",
      "household_action": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Coffee in bed",
        "emoji": "☕",
        "points": 10
      },
      "user": { "id": "660e8400-e29b-41d4-a716-446655440000", "name": "Hendrik" },
      "points": 10,
      "created_at": "2026-05-09T08:30:00Z",
      "undone_at": null
    }
  ],
  "count": 1
}

Schreib-Endpunkte

Erforderliche Berechtigung: Lesen & Schreiben

POST /api/v1/inventory/items

Fügt einen neuen Artikel zu deinem Vorrat hinzu. Kategorie und Icon werden automatisch basierend auf dem Artikelnamen zugewiesen.

Anfrage-Body

Field	Type	Description
name	string	Erforderlich. Der Artikelname.
location_id	uuid	Erforderlich. UUID des Lagerorts.
quantity	number	Optional. Numerische Menge (Standard: 1).
unit	string	Optional. Maßeinheit.
expires_on	date	Optional. Ablaufdatum (JJJJ-MM-TT).
notes	string	Optional. Zusätzliche Notizen.

Beispielanfrage

curl -X POST "https://myshelf.life/api/v1/inventory/items" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"item": {"name": "Eggs", "location_id": "LOCATION_UUID", "quantity": 6, "expires_on": "2026-03-15"}}'

Beispielantwort (201)

{
  "item": {
    "id": "550e8400-e29b-41d4-a716-446655440010",
    "name": "Eggs",
    "quantity": "6.0",
    "unit": null,
    "category": "dairy",
    "icon": "🥚",
    "expires_on": "2026-03-15",
    "status": "ok",
    "notes": null,
    "added_by": "Max",
    "created_at": "2026-02-15T10:30:00Z"
  }
}

POST /api/v1/shopping_list/items

Fügt einen neuen Artikel zur Einkaufsliste hinzu. Die Kategorie wird automatisch zugewiesen.

Anfrage-Body

Field	Type	Description
name	string	Erforderlich. Der Artikelname.
quantity	number	Optional. Numerische Menge.
unit	string	Optional. Maßeinheit (z.B. "Liter", "g", "Stück").

Beispielanfrage

curl -X POST "https://myshelf.life/api/v1/shopping_list/items" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"item": {"name": "Milch", "quantity": 2, "unit": "Liter"}}'

Beispielantwort (201)

{
  "item": {
    "id": "550e8400-e29b-41d4-a716-446655440010",
    "name": "Milch",
    "quantity": "2.0",
    "unit": "Liter",
    "category": "dairy",
    "added_by": "Max",
    "created_at": "2026-02-15T10:30:00Z"
  }
}

PATCH /api/v1/shopping_list/items/:id

Aktualisiert Menge und/oder Einheit eines aktiven Einkaufslisten-Artikels. Abgehakte Artikel können nicht aktualisiert werden (422).

Beispielanfrage

curl -X PATCH "https://myshelf.life/api/v1/shopping_list/items/ITEM_ID" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"item": {"quantity": 500, "unit": "ml"}}'

Beispielantwort (200)

{
  "item": {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "name": "Milch",
    "quantity": "500.0",
    "unit": "ml",
    "category": "dairy",
    "added_by": "Max",
    "created_at": "2026-01-20T14:00:00Z"
  }
}

PATCH /api/v1/inventory/items/:id

Aktualisiert einen aktiven Vorratsartikel. Du kannst Menge, Einheit, Lagerort oder Ablaufdatum ändern. Archivierte Artikel geben 404 zurück.

Anfrage-Body

Field	Type	Description
quantity	number	Neuer Mengenwert
unit	string	Neue Maßeinheit
location_id	uuid	UUID des neuen Lagerorts
expires_on	date	Neues Ablaufdatum (JJJJ-MM-TT)

Beispielanfrage

curl -X PATCH "https://myshelf.life/api/v1/inventory/items/ITEM_ID" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"item": {"quantity": 500, "unit": "ml", "location_id": "LOCATION_UUID", "expires_on": "2026-03-15"}}'

Beispielantwort (200)

{
  "item": {
    "id": "550e8400-e29b-41d4-a716-446655440003",
    "name": "Milch",
    "quantity": "500.0",
    "unit": "ml",
    "category": "dairy",
    "icon": "🥛",
    "expires_on": "2026-03-15",
    "status": "ok",
    "notes": "Bio",
    "added_by": "Max",
    "created_at": "2026-01-15T10:30:00Z"
  }
}

POST /api/v1/household_actions/:id/log

Protokolliert eine Haushaltsaktion, um Punkte zu verdienen. Gibt 422 zurück, wenn die Aktion inaktiv ist.

Beispielanfrage

curl -X POST "https://myshelf.life/api/v1/household_actions/ACTION_ID/log" \
     -H "Authorization: Bearer YOUR_API_KEY"

Beispielantwort (201)

{
  "household_action": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Take out trash",
    "emoji": "🗑️",
    "points": 10,
    "active": true,
    "category": "Trash & Recycling",
    "category_emoji": "🗑️",
    "position": 0,
    "claimed_today": true,
    "created_at": "2026-01-15T10:30:00Z"
  },
  "activity": {
    "id": "660e8400-e29b-41d4-a716-446655440000",
    "activity_type": "custom_action",
    "points": 10,
    "created_at": "2026-03-07T14:00:00Z"
  }
}

PATCH /api/v1/household_actions/:id/toggle

Schaltet eine Haushaltsaktion zwischen aktiv und inaktiv um.

Beispielanfrage

curl -X PATCH "https://myshelf.life/api/v1/household_actions/ACTION_ID/toggle" \
     -H "Authorization: Bearer YOUR_API_KEY"

Beispielantwort (200)

{
  "household_action": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Take out trash",
    "emoji": "🗑️",
    "points": 10,
    "active": false,
    "category": "Trash & Recycling",
    "category_emoji": "🗑️",
    "position": 0,
    "claimed_today": false,
    "created_at": "2026-01-15T10:30:00Z"
  }
}

POST /api/v1/activities/:id/undo

Markiert eine zuvor protokollierte Bonus-Aktivität als rückgängig gemacht und entfernt deren Punkte aus den Summen. Jedes Haushaltsmitglied kann jede Haushaltsaktivität rückgängig machen. Gibt 422 zurück, wenn die Aktivität bereits rückgängig gemacht wurde, 404, wenn die Aktivität nicht zu deinem Haushalt gehört oder keine Bonus-Aktion ist.

Beispielanfrage

curl -X POST "https://myshelf.life/api/v1/activities/ACTIVITY_ID/undo" \
     -H "Authorization: Bearer YOUR_API_KEY"

Beispielantwort (200)

{
  "activity": {
    "id": "770e8400-e29b-41d4-a716-446655440000",
    "household_action": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Coffee in bed",
      "emoji": "☕",
      "points": 10
    },
    "user": { "id": "660e8400-e29b-41d4-a716-446655440000", "name": "Hendrik" },
    "points": 10,
    "created_at": "2026-05-09T08:30:00Z",
    "undone_at": "2026-05-09T08:32:14Z"
  }
}

POST /api/v1/activities/:id/redo

Stellt eine zuvor rückgängig gemachte Bonus-Aktivität wieder her und fügt deren Punkte wieder hinzu. Gibt 422 zurück, wenn die Aktivität nicht rückgängig gemacht wurde.

Beispielanfrage

curl -X POST "https://myshelf.life/api/v1/activities/ACTIVITY_ID/redo" \
     -H "Authorization: Bearer YOUR_API_KEY"

Beispielantwort (200)

{
  "activity": {
    "id": "770e8400-e29b-41d4-a716-446655440000",
    "household_action": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Coffee in bed",
      "emoji": "☕",
      "points": 10
    },
    "user": { "id": "660e8400-e29b-41d4-a716-446655440000", "name": "Hendrik" },
    "points": 10,
    "created_at": "2026-05-09T08:30:00Z",
    "undone_at": null
  }
}

DELETE /api/v1/inventory/items/:id

Archiviert (soft-delete) einen Vorratsartikel. Bereits archivierte Artikel geben 404 zurück. Der Artikel kann über die Web-Oberfläche aus dem Archiv wiederhergestellt werden.

Beispielanfrage

curl -X DELETE "https://myshelf.life/api/v1/inventory/items/ITEM_ID" \
     -H "Authorization: Bearer YOUR_API_KEY"

Beispielantwort (200)

{
  "item": {
    "id": "550e8400-e29b-41d4-a716-446655440003",
    "name": "Milch",
    "quantity": "2.0",
    "unit": "Liter",
    "category": "dairy",
    "icon": "🥛",
    "expires_on": "2026-03-01",
    "status": "ok",
    "notes": "Bio",
    "added_by": "Max",
    "created_at": "2026-01-15T10:30:00Z"
  }
}

Beispiel mit curl

Hier ist ein Beispiel, wie du die API mit curl aufrufen kannst:

# Read shopping list
curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://myshelf.life/api/v1/shopping_list

# Add item to shopping list
curl -X POST "https://myshelf.life/api/v1/shopping_list/items" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"item": {"name": "Milch", "quantity": 2, "unit": "Liter"}}'