Completion

Stream intelligent inline text completions with personalized writing assistance

Overview

The /api/completion endpoint provides intelligent inline writing assistance for text completions, transformations, grammar fixes, and style adjustments. It’s designed for seamless integration into text editors and input fields, offering personalized suggestions based on user memory.

This endpoint returns Server-Sent Events (SSE) for streaming completions.

Endpoint

POST /api/completion

Authentication

Requires authentication via cookies or Authorization header. Alternatively, accepts userId in request body for internal calls.

Returns 401 Unauthorized if authentication fails.

Request Body

messages · UIMessage[] · required

Array of messages containing the text to complete or transform. Typically contains a single user message with the input text.

interface UIMessage {
  id: string
  role: 'user' | 'assistant' | 'system'
  content: string
  parts?: any[]
}

action · ActionType · required

The type of completion or transformation to perform.

Show Available actions

• fix-grammar: Correct grammar and spelling errors
• shorten: Make text more concise
• expand: Add detail and expand text
• professional-tone: Convert to professional tone
• casual-tone: Convert to casual tone
• friendly-tone: Convert to friendly tone
• email-writer: Format as professional email
• custom: Use custom prompt
• chat: General chat completion
• Any custom string for specialized actions

customPrompt · string

Custom instructions to prepend to the system prompt. Used when action is "custom" or when you want to provide additional context.

{
  "action": "custom",
  "customPrompt": "Translate this to Spanish and make it formal"
}

userId · string

User identifier. Used as fallback if authentication via cookies/headers is not available.

Response

Returns a Server-Sent Events (SSE) stream with JSON payloads:

type · string

Event type (text, tool-call, tool-result, reasoning, finish).

content · string

Text chunk or event content. For completions, this contains the transformed/completed text.

id · string

Unique message or chunk ID.

Available Tools

The completion endpoint has access to memory tools for personalization:

Show searchMemory

Automatically called before every completion to personalize the response based on:

• User’s writing style preferences (formal/casual, verbose/concise)
• Email signatures and tone preferences
• Technical terminology and tech stack
• Previous corrections and feedback

Parameters:

• query (string): Search query extracted from context
• userId (string): User identifier
• limit (number, optional): Maximum results (default: 5)

Show addMemory

Stores new insights about the user’s preferences when they make corrections or reveal new information.

Parameters:

• messages (array): Conversation messages containing user preferences
• userId (string): User identifier

Show tavilySearchTool

Web search for current information when needed for content generation.

Parameters:

• query (string): Search query

Behavior

The completion endpoint is designed to:

• Return only the final transformed text (no explanations or preambles)
• Always search memory first to personalize the output
• Match the user’s preferred writing style and tone
• Preserve formatting and capitalization preferences
• Store corrections and feedback for future improvements

Example Request

const response = await fetch('/api/completion', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    messages: [
      {
        id: '1',
        role: 'user',
        content: 'hey can u send me the report tmrw'
      }
    ],
    action: 'professional-tone'
  })
});

// Handle SSE stream
const reader = response.body.getReader();
const decoder = new TextDecoder();
let result = '';

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  
  const chunk = decoder.decode(value);
  const lines = chunk.split('\n');
  
  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const data = JSON.parse(line.slice(6));
      if (data.type === 'text') {
        result += data.content;
      }
    }
  }
}

console.log(result); // "Hello, could you please send me the report tomorrow?"

Example with Custom Prompt

const response = await fetch('/api/completion', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    messages: [
      {
        id: '1',
        role: 'user',
        content: 'function add(a, b) { return a + b }'
      }
    ],
    action: 'custom',
    customPrompt: 'Add TypeScript types and JSDoc comments'
  })
});

Example Response Stream

data: {"type":"reasoning","content":"Searching user preferences..."}

data: {"type":"text","content":"Hello"}

data: {"type":"text","content":","}

data: {"type":"text","content":" could"}

data: {"type":"text","content":" you"}

data: {"type":"text","content":" please"}

data: {"type":"text","content":" send"}

data: {"type":"text","content":" me"}

data: {"type":"text","content":" the"}

data: {"type":"text","content":" report"}

data: {"type":"text","content":" tomorrow"}

data: {"type":"text","content":"?"}

data: {"type":"finish"}

Error Responses

400 Bad Request · error

Returned when messages parameter is missing or invalid.

"Missing messages"

401 Unauthorized · error

Returned when authentication fails.

"Unauthorized"

Use Cases

• Grammar Correction: Fix spelling and grammar errors inline
• Tone Adjustment: Convert between professional, casual, and friendly tones
• Email Writing: Transform quick notes into polished emails
• Text Expansion: Add detail and context to brief text
• Text Condensing: Shorten verbose text while preserving meaning
• Code Completion: Complete or format code snippets
• Translation: Translate and adapt text to different languages and styles
• Creative Writing: Continue stories or creative content

Best Practices

• Let the system search memory automatically - it will personalize based on past interactions
• Use action types for common transformations instead of custom prompts when possible
• For email writing, the system will automatically include the user’s signature if stored in memory
• The endpoint learns from corrections, so user feedback improves future completions