Chat API (/api/chat)

Relevant source files

The following files were used as context for generating this wiki page:

• app/api/chat/route.ts
• package.json
• README.md
• middleware.ts
• app/page.module.css

The Chat API is a server-side endpoint within the GeNCorE Command Center that facilitates direct interaction with Anthropic's Claude AI model. It acts as a secure proxy, handling request validation, authentication via API keys, and communication with the Anthropic SDK.

The API is primarily designed to support chat-based interfaces where users or agents can exchange messages. While other endpoints like /api/task focus on GitHub integration, this endpoint provides a raw interface to claude-sonnet-4-6 for general-purpose AI reasoning and text generation.

Architecture and Data Flow

The Chat API is implemented as a Next.js Route Handler using the App Router. It processes POST requests, validates incoming payloads, and utilizes the @anthropic-ai/sdk to communicate with Anthropic's servers.

Request Processing Flow

The following diagram illustrates the sequence of operations when a client sends a message to the Chat API.

Validation Logic

The API performs several layers of validation before attempting to contact Anthropic:

1. Authentication: Checks for a valid session via middleware.ts.
2. API Key Verification: Ensures the x-api-key header is present and starts with the required prefix sk-ant-.
3. Payload Structural Integrity: Verifies that the messages field is a non-empty array.
4. Message Role Validation: Every message in the array must have a role of either user' or assistant`.
5. Content Validation: Every message must contain a non-empty string in the content field.

Sources: app/api/chat/route.ts:21-61, middleware.ts:48-63

API Specification

Endpoint Configuration

Detail	Value
Method	POST
Route	/api/chat
Model Used	claude-sonnet-4-6
Max Tokens	4096
Auth Header	x-api-key (Anthropic API Key)

Sources: app/api/chat/route.ts:21, app/api/chat/route.ts:67-68

Request Body Parameters

Parameter	Type	Required	Description
messages	Array<Message>	Yes	An array of message objects containing conversation history.
messages[].role	string	Yes	Must be either 'user' or 'assistant'.
messages[].content	string	Yes	The text content of the message.

Sources: app/api/chat/route.ts:43-61

Response Format

Success responses return a JSON object containing the text response from the model.

{
  "content": "Hello! How can I help you today?"
}

Sources: app/api/chat/route.ts:83-85

Error Handling

The API implements comprehensive error catching to handle both client-side misconfigurations and upstream API failures.

HTTP Status	Reason
400	Invalid JSON body, missing/invalid x-api-key, or malformed messages array.
401	Unauthorized (handled by middleware if session cookie is invalid).
500	Anthropic API error, empty response from Claude, or internal server processing error.

Sources: app/api/chat/route.ts:13-97, middleware.ts:58-61

Code Snippet: Anthropic SDK Integration

const anthropic = new Anthropic({
  apiKey: apiKey,
})

const response = await anthropic.messages.create({
  model: 'claude-sonnet-4-6',
  max_tokens: 4096,
  messages: messages.map((msg: { role: string; content: string }) => ({
    role: msg.role as 'user' | 'assistant',
    content: msg.content,
  })),
})

Sources: app/api/chat/route.ts:63-74

Security Considerations

The Chat API is protected by two distinct security mechanisms:

• Session-based Middleware: The middleware.ts file ensures that only authenticated users with a valid auth cookie (derived from ADMIN_TOKEN) can access the route.
• Header-based API Keys: Unlike other GitHub-integrated routes that use server-side environment variables (GITHUB_TOKEN), the Chat API requires the client to provide an Anthropic API key via the x-api-key header for every request.

Sources: middleware.ts:48-63, app/api/chat/route.ts:21-32, README.md:104-115

Summary

The /api/chat route serves as the bridge between the GeNCorE platform and Anthropic's Claude AI. By enforcing strict message schemas and requiring valid Anthropic credentials alongside internal session management, it provides a robust and secure way to integrate conversational AI into the command center's workflows.