An endpoint is an address where an application receives a request for a particular operation. In an AI web application, a frontend can call its own server endpoint, which then calls a model provider’s endpoint. Keeping those two boundaries distinct makes it easier to handle input, credentials, responses, and errors on the server. section 2.5.5 section 9.4.2
For example, an Express server can accept a POST request, read the user’s text from JSON, and pass it to an OpenAI handler. The handler calls the provider’s `chat.completions` endpoint with system and user messages, a model, and generation options. It then extracts the assistant’s message for the frontend and handles errors. The application’s POST endpoint and the provider’s `chat.completions` endpoint have different jobs: one serves the application; the other generates the response. section 2.5.5
Next.js API routes provide the same server-side boundary for application features:
- `/api/tts` is a protected route that streams generated audio to the client. section 10.3.2
- Knowledge-base routes create, retrieve, and delete records; document and upload routes receive files and start processing; chat routes retrieve relevant document chunks and generate responses. section 11.1.3
- A chat route can receive user input, invoke a LangChain agent with MCP tools, and stream its output back to the UI. section 12.5.2
Listing 11.1 Creating a new knowledge base route
import { NextResponse } from 'next/server';
import { createKnowledgeBase,
getAllKnowledgeBases } from '@/lib/database'; #1
export async function POST(request) {
try {
const body = await request.json();
const { name, description } = body;
if (!name) {
return NextResponse.json({ error: 'Name is required' }, { status: 400 });
}
const knowledgeBase =
await createKnowledgeBase({ #2
name,
description: description || '',
});
return NextResponse.json(knowledgeBase); #3
} catch (error) {
console.error('Error creating knowledge base:', error);
return NextResponse.json(
{ error: 'Failed to create knowledge base' },
{ status: 500 }
);
}
}
This POST route shows a concrete endpoint contract: parse JSON, reject a missing name with status 400, create a knowledge base, and return either the result or a status-500 error. section 11.1.3
Treat an endpoint as a security and testing boundary, not just a URL. Validate requests on the server; keep provider API keys in private environment variables and make authenticated provider calls through server routes. For public endpoints, consider API abuse and rate limiting. Integration tests can check that requests, responses, and data transformations work across the route, frontend, and external service. section 9.7 section 8.4.1 section 9.4.2
