# SHELF API Reference

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

**Base URL:** `https://myshelf.life/api/v1`

---

## Authentication

All API requests require a Bearer token in the Authorization header:

```
Authorization: Bearer YOUR_API_KEY
```

API keys can be created in the SHELF app under Settings > API Keys.

### Permission Levels

- **Read**: Can view locations, inventory, and shopping list data
- **Read & Write**: Full access including creating, updating, and deleting items

---

## Error Responses

The API returns standard HTTP status codes with JSON error bodies:

### 401 Unauthorized

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

### 403 Forbidden

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

### 404 Not Found

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

### 422 Unprocessable Entity

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

---

## Endpoints

### Read Endpoints

These endpoints require a key with **Read** permission or higher.

#### GET /api/v1/locations

List all storage locations in your household.

**Example Request:**

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://myshelf.life/api/v1/locations
```

**Example Response:**

```json
{
  "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

Get full inventory grouped by location, including all items with expiry dates and status.

**Example Request:**

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://myshelf.life/api/v1/inventory
```

**Example Response:**

```json
{
  "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

Get the active shopping list with all items.

**Example Request:**

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://myshelf.life/api/v1/shopping_list
```

**Example Response:**

```json
{
  "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"
      }
    ]
  }
}
```

---

### Write Endpoints

These endpoints require a key with **Read & Write** permission.

#### POST /api/v1/shopping_list/items

Add a new item to the shopping list.

**Request Body:**

| Field    | Type   | Description                      |
|----------|--------|----------------------------------|
| name     | string | Item name (required)             |
| quantity | number | Amount (optional, default: 1)    |
| unit     | string | Unit of measurement (optional)   |

**Example Request:**

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

**Example Response (201 Created):**

```json
{
  "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

Update a shopping list item.

**Example Request:**

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

**Example Response (200 OK):**

```json
{
  "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

Update an inventory item (quantity, unit, notes, expiry date, etc.).

**Example Request:**

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

**Example Response (200 OK):**

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

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

Archive an inventory item (moves it to the archive, does not permanently delete).

**Example Request:**

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

**Example Response (200 OK):**

```json
{
  "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"
  }
}
```

---

## Quick Start Examples

```bash
# 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"}}'
```