Runtime HTTP endpoints

When you mount the CopilotKit runtime with createCopilotExpressHandler, createCopilotHonoHandler, copilotRuntimeNextJSAppRouterEndpoint, or any of the other framework adapters, it serves a small set of HTTP routes under the basePath you choose, such as /api/copilotkit. Most applications never call these routes directly. The frontend proxy (ProxiedCopilotRuntimeAgent) calls them for you. When you self-host behind a reverse proxy, lock down auth, or debug a connection failure with curl, use this page to confirm what the runtime exposes.

Multi-route mode (default)#

By default the runtime runs in multi-route mode, exposing a separate route per operation. Given a basePath of /api/copilotkit, the routes are:

:agentId is the key under which you registered the agent in new CopilotRuntime({ agents: { ... } }), for example default or research-agent. :threadId is the thread the run belongs to.

Probing the runtime with curl#

The fastest way to confirm a self-hosted runtime is wired up is to hit /info directly:

curl -s http://localhost:4000/api/copilotkit/info

You should get back a JSON body describing the registered agents. If you get a 404, your basePath doesn't match the URL you're requesting (or the handler isn't mounted). If you get a connection error, the server isn't listening on that host/port.

Single-route mode#

If you prefer to expose a single POST endpoint, for example to simplify a reverse-proxy rule or an API gateway, pass mode: "single-route". In that mode the runtime exposes one POST {basePath} endpoint that accepts a JSON envelope { method, params, body } and dispatches internally to the same handlers:

import { CopilotRuntime, BuiltInAgent } from "@copilotkit/runtime/v2";
import { createCopilotExpressHandler } from "@copilotkit/runtime/v2/express";

const runtime = new CopilotRuntime({
  agents: { default: new BuiltInAgent({ model: "openai/gpt-4o-mini" }) },
});

app.use(
  createCopilotExpressHandler({
    runtime,
    basePath: "/api/copilotkit",
    mode: "single-route",
  }),
);

On the frontend, opt into the matching transport with the useSingleEndpoint prop:

import { CopilotKit } from "@copilotkit/react-core/v2";

<CopilotKit runtimeUrl="/api/copilotkit" useSingleEndpoint>
  <YourApp />
</CopilotKit>;

CORS#

The Express and Hono adapters apply permissive CORS by default (origin: "*", all standard methods, all headers) so local development works out of the box. Pass cors: false to disable the built-in middleware and handle CORS yourself, or pass a configuration object to scope it for production:

createCopilotExpressHandler({
  runtime,
  basePath: "/api/copilotkit",
  cors: { origin: "https://app.example.com", methods: ["GET", "POST", "OPTIONS"] },
});

Authenticating requests#

Because these routes run on your server, they're the right place to enforce auth. The adapters accept lifecycle hooks. An onRequest hook runs before every request and can reject the request by throwing a Response:

createCopilotExpressHandler({
  runtime,
  basePath: "/api/copilotkit",
  hooks: {
    onRequest: ({ request }) => {
      if (!request.headers.get("authorization")) {
        throw new Response("Unauthorized", { status: 401 });
      }
    },
  },
});

See Auth for the full authentication guide.

Connect route 404 on a fresh thread#

A frequent self-hosting symptom is a 404 from the POST /agent/:agentId/connect route right after the page loads, before the user has sent a single message. This usually means one of two things:

1. The agentId in the URL isn't registered. The runtime returns {"error":"Agent not found","message":"Agent '<id>' does not exist"} with a 404 when no agent matches. The prebuilt components default to the agent named "default", so register one under that key (or pass an explicit agentId).
2. connect() is called before any run() for an auto-minted thread. Some persistence backends only know about a thread once a run has produced events. See the AgentRunner guide and the /connect 404 troubleshooting entry.

Related#

• Copilot Runtime: setting up the runtime and adapters.
• AgentRunner: the persistence abstraction behind run/connect/stop.
• Connect AG-UI agents: how the frontend proxy maps onto these routes.
• Error Debugging: the onError codes that map to these routes.