Skip to main content

​
Introduction

The Maxw AI API provides access to AI-powered chat, metadata generation, and authentication services. The API is built on Next.js 16 App Router and uses streaming responses for real-time AI interactions.

​
Base URL

All API requests are made to: 
https://your-domain.com/api
For local development: 
http://localhost:3000/api

​
Available Endpoints

​
Chat API

​
/api/chat
POST
Stream AI responses with Claude Sonnet 4.5, supporting tools like web search, code execution, and Canvas LMS integration.

​
Metadata API

​
/api/metadata
GET
Retrieve information about available AI agents and their tools.

​
Authentication

​
/api/auth/*
GET | POST | PATCH | PUT | DELETE
Better-Auth endpoints for user authentication and session management.

​
Cron Jobs

​
/api/cron/canvas-index
GET
Internal endpoint for updating Canvas LMS content index (requires bearer token authorization).

​
Request Format

​
Headers

All requests should include: 
{
  "Content-Type": "application/json"
}
Authenticated requests automatically include session cookies from Better-Auth.

​
Request Body

API requests expect JSON payloads. Example for /api/chat: 
{
  "messages": [
    {
      "role": "user",
      "content": "What are my upcoming assignments?"
    }
  ],
  "id": "chat_123",
  "trigger": "user"
}

​
Response Format

​
Standard JSON Responses

Most endpoints return JSON with this structure:
​
agents
array
List of available AI agents
​
name
string
Agent identifier (e.g., “general”)
​
description
string
Human-readable agent description
​
tools
array
List of tool names available to this agent
​
tools
array
List of available tools
​
name
string
Tool identifier
​
description
string
Tool functionality description
​
agent
string
Agent that provides this tool

​
Streaming Responses

The /api/chat endpoint returns a streaming response using AI SDK’s toUIMessageStreamResponse() format. This enables real-time token streaming for AI responses. 
// Response is a ReadableStream with chunks:
{
  type: "text-delta" | "tool-call" | "tool-result" | "finish",
  content: string,
  metadata?: {
    anthropic?: {
      containerId?: string,
      cacheReadInputTokens?: number,
      cacheCreationInputTokens?: number
    }
  }
}

​
Error Handling

​
Error Response Format

All errors follow a consistent structure: 
{
  "error": "Error message",
  "details": "Additional context (optional)"
}

​
HTTP Status Codes

​
200
Success
Request completed successfully
​
400
Bad Request
Missing required parameters or invalid formatCommon causes:
  • Missing messages array in chat request
  • Missing chatId parameter
  • Invalid message format
​
401
Unauthorized
Authentication required or session expiredSolution: Authenticate via /api/auth endpoints
​
500
Internal Server Error
Server-side processing errorThe response includes error details when available

​
Rate Limiting

Rate limiting is not currently implemented at the API level. Consider implementing rate limiting for production deployments using middleware or services like Upstash Rate Limit.

​
Caching

The /api/metadata endpoint includes cache headers: 
Cache-Control: public, max-age=3600
Responses are cached for 1 hour to reduce unnecessary database queries.

​
Geolocation Support

The chat API extracts geolocation data from request headers (provided by Vercel Edge Functions) to enable location-aware features:
  • Location-aware web search
  • Timezone detection
  • Regional context for AI responses
Geolocation data is automatically included in the agent context and does not require additional configuration.

​
Agent Context

Each chat request builds an AgentContext that includes:
​
userId
string
required
Authenticated user ID from session
​
fullName
string
User’s display name
​
schoolName
string
User’s institution (currently hardcoded to “Harvard University”)
​
classes
array
User’s Canvas LMS courses with assignments and content
​
chatId
string
required
Unique identifier for this conversation
​
currentDateTime
string
Localized timestamp in user’s timezone
​
timezone
string
User’s timezone (extracted from geolocation or browser)
​
country
string
User’s country code (from Vercel geolocation)
​
city
string
User’s city (from Vercel geolocation)
​
region
string
User’s region/state (from Vercel geolocation)

​
Next Steps

Authentication

Learn how to authenticate requests and manage user sessions

Chat API

Explore the streaming chat endpoint and AI agent capabilities

Database Schema

Understand the data models and relationships

Build docs developers (and LLMs) love

Get started for freeTalk to us