documente/docs/api/endpoints.md

# API Endpoints Documentation

Documentation for NotebookLM Agent API endpoints.

**Base URL:** `http://localhost:8000/api/v1`

---

## Notebooks

### Create Notebook

Create a new notebook with title and optional description.

```http
POST /notebooks
```

**Request Body:**

```json
{
  "title": "Research on AI",
  "description": "A comprehensive study on artificial intelligence"
}
```

**Parameters:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `title` | string | Yes | Notebook title (3-100 characters) |
| `description` | string | No | Optional description |

**Response:**

```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Research on AI",
    "description": "A comprehensive study on artificial intelligence",
    "created_at": "2026-04-06T10:30:00Z",
    "updated_at": "2026-04-06T10:30:00Z"
  },
  "meta": {
    "timestamp": "2026-04-06T10:30:00Z",
    "request_id": "uuid"
  }
}
```

**Status Codes:**

- `201 Created` - Notebook created successfully
- `400 Bad Request` - Validation error (title too short/long)
- `502 Bad Gateway` - NotebookLM API error

**Example:**

```bash
curl -X POST http://localhost:8000/api/v1/notebooks \
  -H "Content-Type: application/json" \
  -d '{"title": "Research on AI", "description": "Study"}'
```

---

### List Notebooks

Get a paginated list of all notebooks.

```http
GET /notebooks
```

**Query Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `limit` | integer | 20 | Items per page (1-100) |
| `offset` | integer | 0 | Items to skip |
| `sort` | string | `created_at` | Sort field (`created_at`, `updated_at`, `title`) |
| `order` | string | `desc` | Sort order (`asc`, `desc`) |

**Response:**

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "title": "Research on AI",
        "description": "Study",
        "created_at": "2026-04-06T10:30:00Z",
        "updated_at": "2026-04-06T10:30:00Z"
      }
    ],
    "pagination": {
      "total": 1,
      "limit": 20,
      "offset": 0
    }
  },
  "meta": {
    "timestamp": "2026-04-06T10:30:00Z",
    "request_id": "uuid"
  }
}
```

**Status Codes:**

- `200 OK` - List retrieved successfully
- `422 Unprocessable Entity` - Invalid query parameters
- `502 Bad Gateway` - NotebookLM API error

**Example:**

```bash
# Default pagination
curl http://localhost:8000/api/v1/notebooks

# Custom pagination
curl "http://localhost:8000/api/v1/notebooks?limit=10&offset=20&sort=title&order=asc"
```

---

### Get Notebook

Get a single notebook by ID.

```http
GET /notebooks/{notebook_id}
```

**Path Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `notebook_id` | UUID | Notebook unique identifier |

**Response:**

```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Research on AI",
    "description": "Study",
    "created_at": "2026-04-06T10:30:00Z",
    "updated_at": "2026-04-06T10:30:00Z"
  },
  "meta": {
    "timestamp": "2026-04-06T10:30:00Z",
    "request_id": "uuid"
  }
}
```

**Status Codes:**

- `200 OK` - Notebook found
- `400 Bad Request` - Invalid UUID format
- `404 Not Found` - Notebook not found
- `502 Bad Gateway` - NotebookLM API error

**Example:**

```bash
curl http://localhost:8000/api/v1/notebooks/550e8400-e29b-41d4-a716-446655440000
```

---

### Update Notebook

Update a notebook (partial update).

```http
PATCH /notebooks/{notebook_id}
```

**Path Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `notebook_id` | UUID | Notebook unique identifier |

**Request Body:**

```json
{
  "title": "Updated Title",
  "description": "Updated description"
}
```

**Parameters:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `title` | string | No | New title (3-100 characters) |
| `description` | string | No | New description |

**Response:**

```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Updated Title",
    "description": "Updated description",
    "created_at": "2026-04-06T10:30:00Z",
    "updated_at": "2026-04-06T11:00:00Z"
  },
  "meta": {
    "timestamp": "2026-04-06T11:00:00Z",
    "request_id": "uuid"
  }
}
```

**Status Codes:**

- `200 OK` - Notebook updated
- `400 Bad Request` - Invalid UUID or validation error
- `404 Not Found` - Notebook not found
- `502 Bad Gateway` - NotebookLM API error

**Example:**

```bash
# Update title only
curl -X PATCH http://localhost:8000/api/v1/notebooks/550e8400-e29b-41d4-a716-446655440000 \
  -H "Content-Type: application/json" \
  -d '{"title": "New Title"}'

# Update description only
curl -X PATCH http://localhost:8000/api/v1/notebooks/550e8400-e29b-41d4-a716-446655440000 \
  -H "Content-Type: application/json" \
  -d '{"description": "New description"}'

# Update both
curl -X PATCH http://localhost:8000/api/v1/notebooks/550e8400-e29b-41d4-a716-446655440000 \
  -H "Content-Type: application/json" \
  -d '{"title": "New Title", "description": "New description"}'
```

---

### Delete Notebook

Delete a notebook permanently.

```http
DELETE /notebooks/{notebook_id}
```

**Path Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `notebook_id` | UUID | Notebook unique identifier |

**Response:**

- `204 No Content` - No response body

**Status Codes:**

- `204 No Content` - Notebook deleted successfully
- `400 Bad Request` - Invalid UUID format
- `404 Not Found` - Notebook not found
- `502 Bad Gateway` - NotebookLM API error

**Example:**

```bash
curl -X DELETE http://localhost:8000/api/v1/notebooks/550e8400-e29b-41d4-a716-446655440000
```

---

## Error Responses

All errors follow this format:

```json
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": [
      {"field": "title", "error": "Title must be at least 3 characters"}
    ]
  },
  "meta": {
    "timestamp": "2026-04-06T10:30:00Z",
    "request_id": "uuid"
  }
}
```

### Error Codes

| Code | HTTP Status | Description |
|------|-------------|-------------|
| `VALIDATION_ERROR` | 400 | Invalid input data |
| `NOT_FOUND` | 404 | Resource not found |
| `NOTEBOOKLM_ERROR` | 502 | External API error |

---

## Common Patterns

### Pagination

All list endpoints support pagination:

```bash
# Page 1 (first 20 items)
curl "http://localhost:8000/api/v1/notebooks?limit=20&offset=0"

# Page 2 (next 20 items)
curl "http://localhost:8000/api/v1/notebooks?limit=20&offset=20"
```

### Sorting

Use `sort` and `order` parameters:

```bash
# Sort by title ascending
curl "http://localhost:8000/api/v1/notebooks?sort=title&order=asc"

# Sort by updated date descending (newest first)
curl "http://localhost:8000/api/v1/notebooks?sort=updated_at&order=desc"
```

---

## Testing

### Health Check

```bash
curl http://localhost:8000/health
```

### OpenAPI Schema

```bash
# OpenAPI JSON
curl http://localhost:8000/openapi.json

# Swagger UI (browser)
open http://localhost:8000/docs
```

---

**Version:** 0.2.0  
**Last Updated:** 2026-04-06