Skip to main content

​
Overview

The /api/metadata endpoint returns information about the AI agents and tools available in Maxw AI. This endpoint is useful for discovering capabilities, displaying tool information in UI, and understanding agent architecture.
This endpoint is simplified for the current architecture where only the general agent is active. It returns hardcoded metadata with a 1-hour cache duration.
The endpoint currently returns a subset of available tools for simplicity. The response includes only the main public-facing tools (code_execution, web_search, searchContent, createStudySet), but the agent actually has access to additional programmatic tools (getTodos, createTodo, updateTodo, deleteTodo, getClassAssignments, memory, web_fetch) that are documented below.

​
Endpoint

GET /api/metadata

​
Authentication

No authentication required. This endpoint returns public metadata about agent capabilities.

​
Response Schema

​
agents
AgentMetadata[]
Array of available agents in the system
​
tools
ToolMetadata[]
Array of all tools available across agents

​
Response Example

{
  "agents": [
    {
      "name": "general",
      "description": "AI assistant with web search, code execution, Canvas LMS integration, and study tools",
      "tools": [
        "code_execution",
        "web_search",
        "searchContent",
        "createStudySet"
      ]
    }
  ],
  "tools": [
    {
      "name": "code_execution",
      "description": "Run Python code for calculations, data processing, and programmatic tool calling",
      "agent": "general"
    },
    {
      "name": "web_search",
      "description": "Search the web for current information (location-aware)",
      "agent": "general"
    },
    {
      "name": "searchContent",
      "description": "Search Canvas LMS content (assignments, pages, syllabus)",
      "agent": "general"
    },
    {
      "name": "createStudySet",
      "description": "Create flashcards and practice questions for studying",
      "agent": "general"
    }
  ]
}

​
Current Agent: General

The general agent is the primary AI assistant with comprehensive capabilities:

​
Native Anthropic Tools

Run Python code in a sandboxed environment for:
  • Mathematical calculations and data processing
  • Programmatic tool calling (batch operations)
  • File manipulation within persistent container
  • Complex filtering and transformations
Container lifetime: ~4.5 minutes of inactivity
Persistent user memory system:
  • Filesystem-like interface (create, read, update, delete)
  • Store user preferences, facts, goals, and context
  • Retrieved automatically across conversations
  • Enables personalized responses without re-asking questions
Fetch and process web content:
  • Download HTML, JSON, or text from URLs
  • Extract structured information from web pages
  • Process documentation, articles, or API responses

​
Custom Integration Tools

Canvas LMS semantic searchSearches across student’s course content:
  • Assignments and due dates
  • Course pages and materials
  • Syllabus documents
  • Discussion topics
Uses Upstash vector search with OpenAI embeddings for semantic matching.
Programmatic Canvas assignment fetchingOnly callable from within code_execution blocks:
  • Fetch from all classes or a specific class
  • Returns full assignment data for filtering
  • Ideal for date-based queries (“due this week”)
  • Can be combined with todo creation
result = await getClassAssignments({})  # All classes
assignments = json.loads(result)
Programmatic todo retrievalFetch user’s tasks with filtering:
  • Views: today, upcoming, anytime, someday, active, logbook
  • Returns full todo objects with Canvas links
  • Includes subtasks and scheduling metadata
result = await getTodos({"view": "today"})
todos = json.loads(result)
Programmatic todo creationCreate tasks from within code execution:
  • Link to Canvas assignments automatically
  • Support scheduled dates and due dates
  • Add subtasks as structured data
  • Batch create multiple todos efficiently
await createTodo({
  "title": "Complete problem set",
  "dueDate": "2026-03-10T23:59:00Z",
  "canvasContentType": "assignment",
  "canvasContentId": 12345
})
Programmatic todo updatesModify existing tasks:
  • Mark complete/incomplete
  • Change dates and scheduling
  • Update subtasks
  • Move between date types (calendar, anytime, someday)
Programmatic todo deletionPermanently remove tasks from the system.
Study material generationCreate flashcard sets for studying:
  • Generate term/definition pairs
  • Extract key concepts from content
  • Support for practice questions
Currently simplified - enhanced features planned for future releases.

​
Programmatic Tool Calling

Many tools are designed for programmatic calling only, meaning they can only be invoked from within Python code_execution blocks:

​
Why Programmatic Calling?

Reduced Latency

No round trips to the model between tool calls

Token Savings

Filter data in Python before adding to context

Conditional Logic

Make decisions based on intermediate results

Batch Operations

Process multiple items efficiently in parallel

​
Example Pattern

import json
import asyncio

# Fetch all assignments
result = await getClassAssignments({})
assignments = json.loads(result)

# Filter assignments due this week
from datetime import datetime, timedelta
this_week = datetime.now() + timedelta(days=7)

due_soon = [
    a for a in assignments 
    if a.get('due_at') and datetime.fromisoformat(a['due_at']) < this_week
]

# Create todos in parallel
await asyncio.gather(*[
    createTodo({
        "title": f"Complete {a['name']}",
        "dueDate": a['due_at'],
        "canvasContentType": "assignment",
        "canvasContentId": a['id'],
        "canvasClassId": int(a['_classId'])
    })
    for a in due_soon
])

print(f"Created {len(due_soon)} todos for assignments due this week")

​
Caching

The metadata endpoint includes aggressive caching: 
headers: {
  "Content-Type": "application/json",
  "Cache-Control": "public, max-age=3600", // 1 hour
}
Since agent configuration rarely changes, the response can be safely cached client-side to reduce API calls.

​
Use Cases

Tool Discovery

Display available tools in chat UI or documentation

Capability Checks

Verify which features are available before showing UI

Agent Architecture

Understand system capabilities for integration

Documentation

Auto-generate tool reference documentation

​
Implementation Details

Source: apps/web/src/app/api/metadata/route.ts 
export async function GET() {
  try {
    const agents: AgentMetadata[] = [
      {
        name: "general",
        description:
          "AI assistant with web search, code execution, Canvas LMS integration, and study tools",
        tools: [
          "code_execution",
          "web_search",
          "searchContent",
          "createStudySet",
        ],
      },
    ];

    const tools: ToolMetadata[] = [
      {
        name: "code_execution",
        description:
          "Run Python code for calculations, data processing, and programmatic tool calling",
        agent: "general",
      },
      {
        name: "web_search",
        description: "Search the web for current information (location-aware)",
        agent: "general",
      },
      {
        name: "searchContent",
        description: "Search Canvas LMS content (assignments, pages, syllabus)",
        agent: "general",
      },
      {
        name: "createStudySet",
        description: "Create flashcards and practice questions for studying",
        agent: "general",
      },
    ];

    const response: MetadataResponse = {
      agents,
      tools,
    };

    return new Response(JSON.stringify(response), {
      status: 200,
      headers: {
        "Content-Type": "application/json",
        "Cache-Control": "public, max-age=3600",
      },
    });
  } catch (error) {
    console.error("Error generating metadata:", error);
    return new Response(
      JSON.stringify({ error: "Failed to generate metadata" }),
      {
        status: 500,
        headers: { "Content-Type": "application/json" },
      },
    );
  }
}

​
Error Handling

​
500 Internal Server Error
error
Unexpected server error during metadata generation
{
  "error": "Failed to generate metadata"
}
In practice, this endpoint rarely fails since it returns hardcoded data. The error handler exists for future extensibility when metadata may be dynamically generated.

​
Future Enhancements

The metadata endpoint is designed to support future expansion:
  • Multiple agents: Specialized agents for different domains
  • Dynamic tool registration: Tools loaded at runtime
  • Tool schemas: Full JSON schema definitions for validation
  • Agent capabilities: Fine-grained capability flags (streaming, multimodal, etc.)
  • Version information: API versioning and compatibility

Streaming Chat API

Main chat endpoint with tool execution

Agent Configuration

System prompt and tool setup

Custom Tools

Tool implementation details

Canvas Integration

Canvas LMS data synchronization

Build docs developers (and LLMs) love

Get started for freeTalk to us