api-reference

Apache Superset API Endpoints for Development: Complete Route Reference

March 8, 2026 superset-sh/superset ↗

Apache Superset exposes its development API through Next.js 13+ route handlers located in apps/api/src/app/api/, covering tRPC data fetching, OAuth authentication, real-time chat services, and third-party integrations with Slack, Linear, and GitHub.

The superset-sh/superset repository implements a modern, file-based API layer using Next.js App Router conventions. For developers building on or extending Apache Superset, understanding the API endpoints for Apache Superset development is critical for integrating authentication flows, managing chat sessions, and connecting external services. Each endpoint follows a standard route handler pattern where the directory structure under apps/api/src/app/api/ directly maps to the URL path, with individual files exporting GET, POST, PUT, PATCH, DELETE, or HEAD functions.

Core API Architecture

Superset’s backend is built as a collection of Next.js 13 route handlers (one file per endpoint) inside the apps/api workspace. Each handler exports specific HTTP method functions that the Next.js Runtime maps directly to the URL path derived from the file’s location under /app/api. This approach provides type-safe request handling, automatic route registration, and straightforward colocation of business logic with its corresponding endpoint definition.

tRPC Gateway

The primary data access layer uses tRPC for end-to-end type-safe API calls between client and server.

  • Endpoint: /api/trpc/[trpc]
  • Methods: GET, POST
  • Source: apps/api/src/app/api/trpc/[trpc]/route.ts

This dynamic route acts as the unified gateway for all tRPC procedures, handling procedure calls through the [trpc] segment parameter.

Authentication Endpoints

Superset provides OAuth-based authentication flows for both web and desktop clients through dedicated route handlers.

Generic OAuth Flow

  • Endpoint: /api/auth/[...all]
  • Method: GET
  • Source: apps/api/src/app/api/auth/[...all]/route.ts

This catch-all route handles various OAuth provider callbacks and authentication steps using Next.js spread segments.

Desktop Client Authentication

Specifically designed for the Superset desktop application, this endpoint initiates the device authorization flow for native clients.

Chat Service Endpoints

The chat system provides comprehensive session management, real-time streaming via Server-Sent Events (SSE), and file attachment handling.

Session Management

  • Endpoint: /api/chat/[sessionId]
  • Methods: GET, PUT, PATCH
  • Source: apps/api/src/app/api/chat/[sessionId]/route.ts

Handles CRUD operations for individual chat sessions using the dynamic sessionId parameter.

Real-Time Streaming

  • Endpoint: /api/chat/[sessionId]/stream
  • Method: GET (Server-Sent Events)
  • Source: apps/api/src/app/api/chat/[sessionId]/stream/route.ts

Provides SSE streams for real-time message updates within a specific chat session.

File Attachments

  • Endpoint: /api/chat/[sessionId]/attachments
  • Method: POST
  • Source: apps/api/src/app/api/chat/[sessionId]/attachments/route.ts

Handles multipart file uploads associated with specific chat sessions.

Web Search Tool

Exposes the web-search capability as a callable tool within the chat assistant system.

Third-Party Integration Endpoints

Superset connects with external services through dedicated webhook and OAuth endpoints organized by provider.

Slack Integration

The Slack integration provides comprehensive event handling, interaction processing, and background job triggers.

Linear Integration

Linear integration handles project management syncing, webhooks, and background synchronization tasks.

GitHub Integration

GitHub integration manages repository connections, app installation, and event processing.

Stripe Integration

Handles background notifications to Slack channels based on Stripe events.

Utility and Discovery Endpoints

Electric SQL-over-HTTP

  • Endpoint: /api/electric/[...path]
  • Method: GET
  • Source: apps/api/src/app/api/electric/[...path]/route.ts

Provides dynamic SQL query capabilities over HTTP for Electric database synchronization, using catch-all segments to handle various query paths.

Desktop Client Utilities

Returns the current Superset desktop client version for update checking and compatibility verification.

Image Proxy

Caches and serves Linear attachment images to avoid direct external requests and handle authentication headers.

OpenID Connect Discovery

Superset implements standard OAuth 2.0 and OpenID Connect discovery endpoints for identity provider configuration and automated client configuration.

Summary

  • Next.js Route Handlers: Superset’s API uses Next.js 13+ App Router conventions with route.ts files exporting HTTP method handlers that map directly to URL paths.
  • tRPC Gateway: The /api/trpc endpoint in apps/api/src/app/api/trpc/[trpc]/route.ts provides the primary type-safe data access layer.
  • Authentication Flows: OAuth and desktop authentication are handled through dedicated endpoints in apps/api/src/app/api/auth/, including desktop-specific flows at /api/auth/desktop/connect.
  • Real-Time Chat: Session management, SSE streaming, and file attachments are managed under /api/chat/[sessionId]/ with specific routes for streaming and web-search tools.
  • Third-Party Integrations: Comprehensive webhook and OAuth endpoints exist for Slack, Linear, and GitHub, with background job processors handling asynchronous tasks like mention processing and repository syncing.
  • Discovery Documents: Standard OpenID Connect and OAuth 2.0 discovery endpoints are available at /.well-known/ for automated client configuration.

Frequently Asked Questions

What base path are Superset API endpoints mounted under?

All API endpoints are mounted under the /api path prefix, with the exception of well-known discovery documents which use /.well-known/. The route files are located in apps/api/src/app/api/ and follow Next.js App Router file-system routing conventions where the directory structure directly maps to the URL path.

How does Superset handle real-time chat functionality?

Superset implements Server-Sent Events (SSE) for real-time updates through the /api/chat/[sessionId]/stream endpoint defined in apps/api/src/app/api/chat/[sessionId]/stream/route.ts. Session state is managed via GET, PUT, and PATCH methods on /api/chat/[sessionId], while file uploads use POST to /api/chat/[sessionId]/attachments.

Which endpoints handle third-party integrations like Slack and Linear?

Slack integration uses multiple endpoints under /api/integrations/slack/ including the main events webhook at /api/integrations/slack/events (apps/api/src/app/api/integrations/slack/events/route.ts) and interaction handlers at /api/integrations/slack/interactions. Linear integration follows a similar pattern with webhooks at /api/integrations/linear/webhook and background sync jobs under /api/integrations/linear/jobs/.

Where are the OpenID Connect discovery documents located?

Superset serves standard OpenID Connect and OAuth 2.0 discovery endpoints at /.well-known/openid-configuration, /.well-known/oauth-authorization-server, and /.well-known/oauth-protected-resource. The source files are located in apps/api/src/app/api/.well-known/ with each document having its own route.ts file, enabling automated client configuration and identity provider discovery.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:
curl -s "https://instagit.com/install.md"
Works with
Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →