Skip to main content

​
Endpoint

POST /api/suggestion
Generates intelligent code suggestions based on the current cursor position, surrounding code context, and file content. Uses Claude 3.7 Sonnet to provide contextually relevant completions.

​
Authentication

Requires a valid Clerk session token. See Authentication for details.

​
Request Body

​
fileName
string
required
The name of the file being edited (e.g., index.ts, App.tsx).
​
code
string
required
The complete code content of the file.
​
currentLine
string
required
The current line where the cursor is positioned.
​
lineNumber
number
required
The line number where the cursor is positioned (1-indexed).
​
textBeforeCursor
string
required
The text on the current line before the cursor position.
​
textAfterCursor
string
required
The text on the current line after the cursor position.
​
previousLines
string
Lines of code appearing before the current line. Can be empty string.
​
nextLines
string
Lines of code appearing after the current line. Can be empty string.

​
Response

​
suggestion
string
The code to insert at the cursor position. Returns an empty string if no completion is needed or if the code is already complete.

​
Request Example

const response = await fetch('/api/suggestion', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fileName: 'utils.ts',
    code: 'function calculateTotal(items) {\n  return items.\n}',
    currentLine: '  return items.',
    lineNumber: 2,
    textBeforeCursor: '  return items.',
    textAfterCursor: '',
    previousLines: 'function calculateTotal(items) {',
    nextLines: '}'
  })
});

const data = await response.json();
console.log(data.suggestion);

​
Response Example

{
  "suggestion": "reduce((sum, item) => sum + item.price, 0)"
}

​
AI Model

This endpoint uses Claude 3.7 Sonnet (claude-3-7-sonnet-20250219) with structured output to ensure consistent suggestion formatting.

​
Suggestion Logic

The AI follows a specific decision tree:
  1. Check Next Lines: If nextLines contains code that continues from the cursor, returns empty string (code already exists)
  2. Check Completeness: If textBeforeCursor ends with a complete statement (;, }, )), returns empty string
  3. Generate Suggestion: Only if the above conditions don’t apply, generates a contextual completion

​
When Suggestions Are Empty

The endpoint returns an empty suggestion when:
  • The code is already written in the following lines
  • The current statement is already complete
  • No meaningful completion can be suggested

​
Context Usage

The AI analyzes multiple context layers:
  • File Context: Full code content and file name
  • Local Context: Current line, previous lines, and next lines
  • Cursor Context: Text immediately before and after cursor
  • Structural Context: Line numbers for precise positioning
This comprehensive context ensures suggestions are:
  • Syntactically correct
  • Contextually appropriate
  • Consistent with existing code style
  • Non-redundant with existing code

​
Error Responses

​
error
string
Description of the error that occurred.

​
Common Errors

Status CodeErrorDescription
400Code is requiredThe code parameter is missing or empty
403UnauthorizedMissing or invalid authentication token
500Failed to generate suggestionAI model error or internal server issue

​
Performance Notes

  • Average response time: 500-2000ms depending on code complexity
  • Suggestions are generated synchronously
  • Consider implementing client-side debouncing for real-time suggestions
  • Cache suggestions when cursor position hasn’t changed

Build docs developers (and LLMs) love

Get started for freeTalk to us