HTTP Routes

A comprehensive list of all HTTP routes that Carbon uses for Discord bot interactions and management.

Carbon provides several HTTP routes for handling Discord interactions, command deployment, and plugin functionality. This page documents all available routes that Carbon can handle.

Core Routes

These are the fundamental routes that Carbon provides out of the box when you create a client.

POST/interactions

Purpose:Receives interaction events from Discord

Protected:No

Can be disabled:Yes (via disableInteractionsRoute option)

This is the primary route where Discord sends all interaction events (slash commands, button clicks, select menu selections, etc.). This should be configured as your 'Interactions Endpoint URL' in your Discord application settings.

POST/events

Purpose:Receives Gateway events (when using Gateway Forwarder)

Protected:No

Can be disabled:Yes (via disableEventsRoute option)

This route receives Gateway events forwarded from another Carbon instance running the Gateway Forwarder plugin. Used for hybrid setups where you want Gateway events in a serverless environment.

GET/deploy

Purpose:Deploys commands to Discord

Protected:Yes (requires deploySecret)

Can be disabled:Yes (via disableDeployRoute option)

This route triggers the deployment of all registered commands to Discord's API. It requires authentication via the deploySecret parameter.

Plugin Routes

These routes are added by Carbon plugins and provide additional functionality.

Command Data Plugin Routes

The Command Data Plugin adds routes for retrieving command information.

GET/commandsCommandDataPlugin

Purpose:Returns command data in Discord API format

Protected:No

Can be disabled:No

Returns an array of command data objects that can be sent to Discord's API for command registration.

GET/commands/fullCommandDataPlugin

Purpose:Returns full command data from Discord's API

Protected:No

Can be disabled:No

Fetches and returns the complete command data from Discord's API, including command IDs and other metadata.

Linked Roles Plugin Routes

The Linked Roles plugin adds routes for Discord's Linked Roles functionality.

GET/linked-roles/deployLinkedRoles

Purpose:Deploys linked roles metadata to Discord

Protected:Yes (requires deploySecret)

Can be disabled:No

Registers or updates the linked roles metadata for your application.

GET/linked-roles/verify-userLinkedRoles

Purpose:Initiates user verification flow

Protected:No

Can be disabled:No

Starts the OAuth2 flow for users to connect their accounts and verify linked roles.

GET/linked-roles/verify-user/callbackLinkedRoles

Purpose:Handles OAuth2 callback for user verification

Protected:No

Can be disabled:No

Processes the OAuth2 callback after a user authorizes your application.

Route Configuration

Disabling Routes

You can disable specific routes when creating your client:

const client = new Client({
	baseUrl: "https://your-bot.com",
	clientId: "your-client-id",
	publicKey: "your-public-key",
	token: "your-bot-token",
	
	// Disable specific routes
	disableDeployRoute: true,
	disableInteractionsRoute: false,
	disableEventsRoute: true
})

Protected Routes

Some routes require authentication via a deploy secret:

const client = new Client({
	baseUrl: "https://your-bot.com",
	deploySecret: "your-secret-key",
	// ... other options
})

// Protected routes require: ?secret=your-secret-key

Custom Routes via Plugins

Plugins can register additional routes using the registerRoutes method:

import { Plugin } from "@buape/carbon"

class MyCustomPlugin extends Plugin {
	readonly id = "my-plugin"
	
	registerRoutes(client: Client) {
		client.routes.push({
			method: "GET",
			path: "/my-custom-route",
			handler: this.handleRequest.bind(this),
			protected: false,
			disabled: false
		})
	}
	
	private handleRequest(req: Request) {
		return new Response("Hello from custom route!")
	}
}

Route Interface

All routes in Carbon implement this interface:

interface Route {
	/** The HTTP method of the route */
	method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE"
	
	/** The relative path of the route */
	path: `/${string}`
	
	/** The handler function for the route */
	handler(req: Request, ctx?: Context): Response | Promise<Response>
	
	/** Whether this route requires authentication */
	protected?: boolean
	
	/** Whether this route is disabled */
	disabled?: boolean
}

Debugging Routes

You can see which routes are active by logging them after client initialization:

const client = new Client(/* ... */)

console.log("Active routes:")
client.routes
	.filter(route => !route.disabled)
	.forEach(route => {
		console.log(`  ${route.method} ${route.path}${route.protected ? ' (protected)' : ''}`)
	})

This will output something like:

Active routes:
	GET /deploy (protected)
	POST /interactions
	POST /events
	GET /commands
	GET /commands/full

On this page