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.

POST /notebooks

Request Body:

{
  "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:

{
  "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:

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.

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:

{
  "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:

# 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.

GET /notebooks/{notebook_id}

Path Parameters:

Parameter	Type	Description
notebook_id	UUID	Notebook unique identifier

Response:

{
  "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:

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

---

Update Notebook

Update a notebook (partial update).

PATCH /notebooks/{notebook_id}

Path Parameters:

Parameter	Type	Description
notebook_id	UUID	Notebook unique identifier

Request Body:

{
  "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:

{
  "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:

# 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.

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:

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

---

Error Responses

All errors follow this format:

{
  "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:

# 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:

# 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

curl http://localhost:8000/health

OpenAPI Schema

# 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