# Document Summaries

## List all document summaries

**get** `/document-summaries`

Retrieve a paginated list of document summaries using cursor-based pagination

### Query Parameters

- `after: optional string`

  Cursor for forward pagination. Returns items after this cursor.

- `before: optional string`

  Cursor for backward pagination. Returns items before this cursor.

- `document_id: optional string`

  Filter summaries by document ID

- `household_id: optional string`

  Filter summaries by household ID

- `limit: optional number`

  Maximum number of items to return

### Returns

- `data: array of DocumentSummary`

  - `id: string`

    Unique identifier for the document summary

  - `created_at: string`

    Timestamp when the summary was created

  - `display_name: string`

    Display name for the summary

  - `document_id: string`

    ID of the document this summary belongs to

  - `household_id: string`

    ID of the household this summary belongs to

  - `summary: string`

    The summary text content

  - `updated_at: string`

    Timestamp when the summary was last updated

  - `entry_mode: optional DocumentSummaryEntryMode`

    Indicates if the summary was AI-generated or user-entered

    - `"AI_AUTO"`

    - `"USER"`

  - `summary_format: optional DocumentSummaryFormat`

    Format of the summary content

    - `"MARKDOWN"`

    - `"PLAIN_TEXT"`

- `page_info: PageInfo`

  - `has_next_page: boolean`

    When paginating forwards, are there more items?

  - `has_previous_page: boolean`

    When paginating backwards, are there more items?

  - `end_cursor: optional string`

    Cursor pointing to the last item in the current page

  - `start_cursor: optional string`

    Cursor pointing to the first item in the current page

- `total_count: number`

  Total number of items matching the query (across all pages)

### Example

```http
curl https://$WITHLUMINARY_SUBDOMAIN.withluminary.com/api/public/v1/document-summaries
```

#### Response

```json
{
  "data": [
    {
      "id": "document_summary_01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "created_at": "2019-12-27T18:11:19.117Z",
      "display_name": "Default summary",
      "document_id": "document_01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "household_id": "household_01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "summary": "summary",
      "updated_at": "2019-12-27T18:11:19.117Z",
      "entry_mode": "AI_AUTO",
      "summary_format": "MARKDOWN"
    }
  ],
  "page_info": {
    "has_next_page": true,
    "has_previous_page": false,
    "end_cursor": "eyJpZCI6ImhvdXNlaG9sZF8wMUFSWjNOREVLVFNWNFJSRkZRNjlHNUZBViJ9",
    "start_cursor": "eyJpZCI6ImhvdXNlaG9sZF8wMUFSWjNOREVLVFNWNFJSRkZRNjlHNUZBViJ9"
  },
  "total_count": 100
}
```

## Get a document summary by ID

**get** `/document-summaries/{id}`

Retrieve a specific document summary

### Path Parameters

- `id: string`

### Returns

- `DocumentSummary object { id, created_at, display_name, 6 more }`

  - `id: string`

    Unique identifier for the document summary

  - `created_at: string`

    Timestamp when the summary was created

  - `display_name: string`

    Display name for the summary

  - `document_id: string`

    ID of the document this summary belongs to

  - `household_id: string`

    ID of the household this summary belongs to

  - `summary: string`

    The summary text content

  - `updated_at: string`

    Timestamp when the summary was last updated

  - `entry_mode: optional DocumentSummaryEntryMode`

    Indicates if the summary was AI-generated or user-entered

    - `"AI_AUTO"`

    - `"USER"`

  - `summary_format: optional DocumentSummaryFormat`

    Format of the summary content

    - `"MARKDOWN"`

    - `"PLAIN_TEXT"`

### Example

```http
curl https://$WITHLUMINARY_SUBDOMAIN.withluminary.com/api/public/v1/document-summaries/$ID
```

#### Response

```json
{
  "id": "document_summary_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "created_at": "2019-12-27T18:11:19.117Z",
  "display_name": "Default summary",
  "document_id": "document_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "household_id": "household_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "summary": "summary",
  "updated_at": "2019-12-27T18:11:19.117Z",
  "entry_mode": "AI_AUTO",
  "summary_format": "MARKDOWN"
}
```

## Update a document summary

**put** `/document-summaries/{id}`

Update an existing document summary

### Path Parameters

- `id: string`

### Body Parameters

- `display_name: optional string`

  Display name for the summary

- `entry_mode: optional DocumentSummaryEntryMode`

  Indicates if the summary was AI-generated or user-entered

  - `"AI_AUTO"`

  - `"USER"`

- `summary: optional string`

  The summary text content

- `summary_format: optional DocumentSummaryFormat`

  Format of the summary content

  - `"MARKDOWN"`

  - `"PLAIN_TEXT"`

### Returns

- `DocumentSummary object { id, created_at, display_name, 6 more }`

  - `id: string`

    Unique identifier for the document summary

  - `created_at: string`

    Timestamp when the summary was created

  - `display_name: string`

    Display name for the summary

  - `document_id: string`

    ID of the document this summary belongs to

  - `household_id: string`

    ID of the household this summary belongs to

  - `summary: string`

    The summary text content

  - `updated_at: string`

    Timestamp when the summary was last updated

  - `entry_mode: optional DocumentSummaryEntryMode`

    Indicates if the summary was AI-generated or user-entered

    - `"AI_AUTO"`

    - `"USER"`

  - `summary_format: optional DocumentSummaryFormat`

    Format of the summary content

    - `"MARKDOWN"`

    - `"PLAIN_TEXT"`

### Example

```http
curl https://$WITHLUMINARY_SUBDOMAIN.withluminary.com/api/public/v1/document-summaries/$ID \
    -X PUT \
    -H 'Content-Type: application/json' \
    -d '{}'
```

#### Response

```json
{
  "id": "document_summary_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "created_at": "2019-12-27T18:11:19.117Z",
  "display_name": "Default summary",
  "document_id": "document_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "household_id": "household_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "summary": "summary",
  "updated_at": "2019-12-27T18:11:19.117Z",
  "entry_mode": "AI_AUTO",
  "summary_format": "MARKDOWN"
}
```

## Download document summary as PDF

**get** `/document-summaries/{id}/download`

Download the document summary content in the specified format

### Path Parameters

- `id: string`

### Query Parameters

- `format: optional "pdf"`

  Output format for the download

  - `"pdf"`

### Example

```http
curl https://$WITHLUMINARY_SUBDOMAIN.withluminary.com/api/public/v1/document-summaries/$ID/download
```

## Domain Types

### Document Summary

- `DocumentSummary object { id, created_at, display_name, 6 more }`

  - `id: string`

    Unique identifier for the document summary

  - `created_at: string`

    Timestamp when the summary was created

  - `display_name: string`

    Display name for the summary

  - `document_id: string`

    ID of the document this summary belongs to

  - `household_id: string`

    ID of the household this summary belongs to

  - `summary: string`

    The summary text content

  - `updated_at: string`

    Timestamp when the summary was last updated

  - `entry_mode: optional DocumentSummaryEntryMode`

    Indicates if the summary was AI-generated or user-entered

    - `"AI_AUTO"`

    - `"USER"`

  - `summary_format: optional DocumentSummaryFormat`

    Format of the summary content

    - `"MARKDOWN"`

    - `"PLAIN_TEXT"`

### Document Summary Entry Mode

- `DocumentSummaryEntryMode = "AI_AUTO" or "USER"`

  Indicates if the summary was AI-generated or user-entered

  - `"AI_AUTO"`

  - `"USER"`

### Document Summary Format

- `DocumentSummaryFormat = "MARKDOWN" or "PLAIN_TEXT"`

  Format of the summary content

  - `"MARKDOWN"`

  - `"PLAIN_TEXT"`

### Page Info

- `PageInfo object { has_next_page, has_previous_page, end_cursor, start_cursor }`

  - `has_next_page: boolean`

    When paginating forwards, are there more items?

  - `has_previous_page: boolean`

    When paginating backwards, are there more items?

  - `end_cursor: optional string`

    Cursor pointing to the last item in the current page

  - `start_cursor: optional string`

    Cursor pointing to the first item in the current page