Skip to main content

​
GET /api/suggestions

Retrieve all suggestions for a specific document.

​
Authentication

Requires authenticated session. Returns 401 if not authenticated.

​
Query parameters

​
documentId
string
required
The document ID to retrieve suggestions for

​
Request example

GET /api/suggestions?documentId=550e8400-e29b-41d4-a716-446655440000

​
Response

Returns array of suggestions for the document. 
[
  {
    "id": "770e8400-e29b-41d4-a716-446655440003",
    "documentId": "550e8400-e29b-41d4-a716-446655440000",
    "documentCreatedAt": "2024-01-15T10:30:00Z",
    "originalText": "function Button() { return <button>Click</button>; }",
    "suggestedText": "function Button({ onClick, label }) { return <button onClick={onClick}>{label}</button>; }",
    "description": "Add onClick handler and customizable label props",
    "isResolved": false,
    "userId": "123e4567-e89b-12d3-a456-426614174000",
    "createdAt": "2024-01-15T10:35:00Z"
  },
  {
    "id": "880e8400-e29b-41d4-a716-446655440004",
    "documentId": "550e8400-e29b-41d4-a716-446655440000",
    "documentCreatedAt": "2024-01-15T10:30:00Z",
    "originalText": "function Button({ onClick, label }) { return <button onClick={onClick}>{label}</button>; }",
    "suggestedText": "function Button({ onClick, label, disabled = false }) { return <button onClick={onClick} disabled={disabled}>{label}</button>; }",
    "description": "Add disabled prop with default value",
    "isResolved": true,
    "userId": "123e4567-e89b-12d3-a456-426614174000",
    "createdAt": "2024-01-15T10:40:00Z"
  }
]

​
Suggestion properties

​
id
string
Suggestion UUID
​
documentId
string
Associated document UUID
​
documentCreatedAt
string
Timestamp of the document version this suggestion applies to
​
originalText
string
The original text being modified
​
suggestedText
string
The suggested replacement text
​
description
string
Optional description of the suggestion (can be null)
​
isResolved
boolean
Whether the suggestion has been accepted or rejected
​
userId
string
User ID who owns the document
​
createdAt
string
ISO 8601 timestamp when suggestion was created

​
Response when no suggestions

If no suggestions exist for the document, returns empty array: 
[]

​
Error responses

​
400
Bad Request
Missing documentId parameter
​
401
Unauthorized
Not authenticated
​
403
Forbidden
Document belongs to different user (suggestions inherit document ownership)
From app/(chat)/api/suggestions/route.ts:5-37

​
How suggestions work

Suggestions are generated by the AI using the requestSuggestions tool during chat:
  1. User asks AI to suggest improvements to a document
  2. AI analyzes document content
  3. AI calls requestSuggestions tool with suggested edits
  4. Suggestions are saved to database
  5. UI displays suggestions as inline edits

​
Database schema

From lib/db/schema.ts:128-150, suggestions have:
  • Primary key: id
  • Foreign key: (documentId, documentCreatedAt) references document(id, createdAt)
  • User ownership via userId
  • Resolution tracking via isResolved

​
Database queries

From lib/db/queries.ts:417-448: 
export async function saveSuggestions({
  suggestions,
}: {
  suggestions: Suggestion[];
}) {
  try {
    return await db.insert(suggestion).values(suggestions);
  } catch (_error) {
    throw new ChatbotError(
      "bad_request:database",
      "Failed to save suggestions"
    );
  }
}
Suggestions provide a collaborative editing experience where the AI can propose specific changes that users can review and accept.

​
Use cases

  • Code refactoring suggestions
  • Grammar and style improvements for text documents
  • Data formatting suggestions for spreadsheets
  • Accessibility improvements
  • Performance optimizations

Build docs developers (and LLMs) love

Get started for freeTalk to us