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"
    }
  ]
}

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"
  }
}

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"}}'