# Apache Superset API Endpoints for Development: Complete Route Reference

> Explore Apache Superset API endpoints for development at apps/api/src/app/api/. Access tRPC data fetching, OAuth, chat services, and integrations with Slack, Linear, and GitHub.

- Repository: [Superset/superset](https://github.com/superset-sh/superset)
- Tags: api-reference
- Published: 2026-03-08

---

**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

- **Endpoint**: `/api/auth/desktop/connect`
- **Method**: `GET`
- **Source**: [`apps/api/src/app/api/auth/desktop/connect/route.ts`](https://github.com/superset-sh/superset/blob/main/apps/api/src/app/api/auth/desktop/connect/route.ts)

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

- **Endpoint**: `/api/chat/tools/web-search`
- **Method**: `POST`
- **Source**: [`apps/api/src/app/api/chat/tools/web-search/route.ts`](https://github.com/superset-sh/superset/blob/main/apps/api/src/app/api/chat/tools/web-search/route.ts)

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.

- **Link Handling**: `/api/integrations/slack/link` (`GET`) → [`apps/api/src/app/api/integrations/slack/link/route.ts`](https://github.com/superset-sh/superset/blob/main/apps/api/src/app/api/integrations/slack/link/route.ts)
- **OAuth Start**: `/api/integrations/slack/connect` (`GET`) → [`apps/api/src/app/api/integrations/slack/connect/route.ts`](https://github.com/superset-sh/superset/blob/main/apps/api/src/app/api/integrations/slack/connect/route.ts)
- **OAuth Callback**: `/api/integrations/slack/callback` (`GET`) → [`apps/api/src/app/api/integrations/slack/callback/route.ts`](https://github.com/superset-sh/superset/blob/main/apps/api/src/app/api/integrations/slack/callback/route.ts)
- **Event Webhook**: `/api/integrations/slack/events` (`POST`) → [`apps/api/src/app/api/integrations/slack/events/route.ts`](https://github.com/superset-sh/superset/blob/main/apps/api/src/app/api/integrations/slack/events/route.ts)
- **Interaction Handler**: `/api/integrations/slack/interactions` (`POST`) → [`apps/api/src/app/api/integrations/slack/interactions/route.ts`](https://github.com/superset-sh/superset/blob/main/apps/api/src/app/api/integrations/slack/interactions/route.ts)
- **Background Jobs**:
  - `/api/integrations/slack/jobs/process-mention` (`POST`) → [`apps/api/src/app/api/integrations/slack/jobs/process-mention/route.ts`](https://github.com/superset-sh/superset/blob/main/apps/api/src/app/api/integrations/slack/jobs/process-mention/route.ts)
  - `/api/integrations/slack/jobs/process-assistant-message` (`POST`) → [`apps/api/src/app/api/integrations/slack/jobs/process-assistant-message/route.ts`](https://github.com/superset-sh/superset/blob/main/apps/api/src/app/api/integrations/slack/jobs/process-assistant-message/route.ts)

### Linear Integration

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

- **OAuth Start**: `/api/integrations/linear/connect` (`GET`) → [`apps/api/src/app/api/integrations/linear/connect/route.ts`](https://github.com/superset-sh/superset/blob/main/apps/api/src/app/api/integrations/linear/connect/route.ts)
- **OAuth Callback**: `/api/integrations/linear/callback` (`GET`) → [`apps/api/src/app/api/integrations/linear/callback/route.ts`](https://github.com/superset-sh/superset/blob/main/apps/api/src/app/api/integrations/linear/callback/route.ts)
- **Webhook Receiver**: `/api/integrations/linear/webhook` (`POST`) → [`apps/api/src/app/api/integrations/linear/webhook/route.ts`](https://github.com/superset-sh/superset/blob/main/apps/api/src/app/api/integrations/linear/webhook/route.ts)
- **Background Sync**:
  - `/api/integrations/linear/jobs/sync-task` (`POST`) → [`apps/api/src/app/api/integrations/linear/jobs/sync-task/route.ts`](https://github.com/superset-sh/superset/blob/main/apps/api/src/app/api/integrations/linear/jobs/sync-task/route.ts)
  - `/api/integrations/linear/jobs/initial-sync` (`POST`) → [`apps/api/src/app/api/integrations/linear/jobs/initial-sync/route.ts`](https://github.com/superset-sh/superset/blob/main/apps/api/src/app/api/integrations/linear/jobs/initial-sync/route.ts)

### GitHub Integration

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

- **Installation Start**: `/api/github/install` (`GET`) → [`apps/api/src/app/api/github/install/route.ts`](https://github.com/superset-sh/superset/blob/main/apps/api/src/app/api/github/install/route.ts)
- **OAuth Callback**: `/api/github/callback` (`GET`) → [`apps/api/src/app/api/github/callback/route.ts`](https://github.com/superset-sh/superset/blob/main/apps/api/src/app/api/github/callback/route.ts)
- **Event Webhook**: `/api/github/webhook` (`POST`) → [`apps/api/src/app/api/github/webhook/route.ts`](https://github.com/superset-sh/superset/blob/main/apps/api/src/app/api/github/webhook/route.ts)
- **Repository Sync**: `/api/github/sync` (`POST`) → [`apps/api/src/app/api/github/sync/route.ts`](https://github.com/superset-sh/superset/blob/main/apps/api/src/app/api/github/sync/route.ts)

### Stripe Integration

- **Slack Notification**: `/api/integrations/stripe/jobs/notify-slack` (`POST`) → [`apps/api/src/app/api/integrations/stripe/jobs/notify-slack/route.ts`](https://github.com/superset-sh/superset/blob/main/apps/api/src/app/api/integrations/stripe/jobs/notify-slack/route.ts)

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

- **Version Endpoint**: `/api/desktop/version` (`GET`) → [`apps/api/src/app/api/desktop/version/route.ts`](https://github.com/superset-sh/superset/blob/main/apps/api/src/app/api/desktop/version/route.ts)

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

### Image Proxy

- **Linear Image Proxy**: `/api/proxy/linear-image` (`GET`) → [`apps/api/src/app/api/proxy/linear-image/route.ts`](https://github.com/superset-sh/superset/blob/main/apps/api/src/app/api/proxy/linear-image/route.ts)

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.

- **OpenID Configuration**: `/.well-known/openid-configuration` (`GET`) → [`apps/api/src/app/api/.well-known/openid-configuration/route.ts`](https://github.com/superset-sh/superset/blob/main/apps/api/src/app/api/.well-known/openid-configuration/route.ts)
- **OAuth Authorization Server**: `/.well-known/oauth-authorization-server` (`GET`) → [`apps/api/src/app/api/.well-known/oauth-authorization-server/route.ts`](https://github.com/superset-sh/superset/blob/main/apps/api/src/app/api/.well-known/oauth-authorization-server/route.ts)
- **OAuth Protected Resource**: `/.well-known/oauth-protected-resource` (`GET`) → [`apps/api/src/app/api/.well-known/oauth-protected-resource/route.ts`](https://github.com/superset-sh/superset/blob/main/apps/api/src/app/api/.well-known/oauth-protected-resource/route.ts)

## Summary

- **Next.js Route Handlers**: Superset’s API uses Next.js 13+ App Router conventions with [`route.ts`](https://github.com/superset-sh/superset/blob/main/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`](https://github.com/superset-sh/superset/blob/main/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`](https://github.com/superset-sh/superset/blob/main/route.ts) file, enabling automated client configuration and identity provider discovery.