Runtime HTTP endpoints
The HTTP routes exposed by the CopilotKit runtime for self-hosting, proxying, and debugging.
When you mount the CopilotKit runtime with
createCopilotRuntimeHandler, createCopilotExpressHandler,
createCopilotHonoHandler, 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. See
Connect AG-UI agents for how the proxy maps onto these routes. 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.
Other runtime languages
Python, Go, Ruby, and C#/.NET runtimes require Intelligence and serve multi-route endpoints. Use useSingleEndpoint={false} with the React provider; do not send a single-route envelope to those servers. The JavaScript handler factories, deprecated v1 endpoints, and optional TypeScript features below are specific to the TypeScript runtime. See the Intelligence quickstart for native server setup.
Provider and handler pairs
The browser provider and the Runtime handler have to agree on the transport. CopilotKit ships more than one name for each half, and they are not interchangeable: each provider setting requires a matching handler mode. Different pages and older apps show different pairs, so this table is the mapping:
Vue uses CopilotKitProvider. With use-single-endpoint omitted, it discovers
the transport from /info; set it to true for a single-route handler or
false for a multi-route handler.
Which handlers serve which mode
| Mode | Handlers |
|---|---|
| Multi-route (default) | createCopilotRuntimeHandler, createCopilotHonoHandler, createCopilotExpressHandler, createCopilotNodeHandler, createCopilotNodeListener |
| Single-route | Any of the above with mode: "single-route" |
| Single-route only (deprecated v1) | copilotRuntimeNextJSAppRouterEndpoint, copilotRuntimeNextJSPagesRouterEndpoint, copilotRuntimeNodeHttpEndpoint, copilotRuntimeNodeExpressEndpoint, copilotRuntimeNestEndpoint |
Replace the deprecated v1 wrappers with createCopilotRuntimeHandler from
@copilotkit/runtime/v2.
The framework wrappers support Intelligence resources
Every copilotRuntime*Endpoint wrapper builds its handler with
mode: "single-route". A current client and Runtime carry AG-UI Streams,
Memory, and annotation requests through that endpoint. Setting
useSingleEndpoint={false} still points the browser at REST routes that these
wrappers do not serve.
Older code may use these deprecated aliases:
| Deprecated | Use instead |
|---|---|
createCopilotEndpoint | createCopilotHonoHandler |
createCopilotEndpointSingleRoute | createCopilotHonoHandler with mode: "single-route" |
createCopilotEndpointExpress | createCopilotExpressHandler |
createCopilotEndpointSingleRouteExpress | createCopilotExpressHandler with mode: "single-route" |
A mismatched pair fails at discovery
A mismatch fails at discovery, not at your application code. A multi-route
provider against a single-route Runtime 404s on GET {basePath}/info; a
single-route provider against a multi-route Runtime posts an envelope the
Runtime does not accept. See Connect route 404 on a fresh
thread.
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:
| Method & path | Purpose |
|---|---|
GET /api/copilotkit/info | Runtime info. The frontend calls this on startup to discover registered agents and their metadata. |
GET /api/copilotkit/inspector-metadata | Optional trusted project, plan, license, action, usage, and expiry context for the Inspector. Intelligence-backed runtimes advertise this route with inspectorMetadata: true in the runtime-info response. |
POST /api/copilotkit/agent/:agentId/run | Start an agent run. The request body is an AG-UI RunAgentInput; the response is an SSE stream of AG-UI events. With Intelligence, the response is JSON. See Run and connect with Intelligence. |
POST /api/copilotkit/agent/:agentId/connect | Connect to an agent's thread. Used to resume streaming after a reconnect or page refresh. Also an SSE stream, or JSON with Intelligence. |
POST /api/copilotkit/agent/:agentId/stop/:threadId | Stop the in-progress run on a given thread. An optional JSON body { "runId": "..." } stops only that run. A body that is not valid JSON, or carries any other key, is rejected with 400 and stops nothing. |
POST /api/copilotkit/transcribe | Transcribe audio (used by the voice / transcription input). |
: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.
The GET /info route is the same endpoint the frontend uses for agent
discovery. If it isn't reachable from the runtime, the frontend reports a
runtime_info_fetch_failed error. See Error
Debugging.
An Intelligence runtime also returns runtimeEntitlements. Its status is one
of these values:
ready: includes the normalized feature and limit values.degraded,misconfigured, orunavailable: includes a structured error with a code, message, and retry flag.
The /info request still succeeds when entitlement lookup fails so core Runtime
behavior can continue; features that need a proven entitlement stay off. If
Intelligence rejects the project key with a 401, the Runtime still returns
200 from /info. The body reports runtimeEntitlements.status as
misconfigured with the non-retryable runtime_entitlements_misconfigured
error code.
Run and connect with Intelligence
When the runtime has an intelligence client, the run and connect routes do
not stream events. They return JSON that tells the client where to read the
events:
{
"threadId": "<thread id>",
"runId": "<run id>",
"joinToken": "<join token>",
"realtime": {
"clientUrl": "<Intelligence websocket URL>",
"topic": "thread:<thread id>"
}
}The client opens a websocket to realtime.clientUrl and joins the
realtime.topic channel with the joinToken. The AG-UI events of the run
arrive on that channel. CopilotKitProvider does this for you when runtime
info reports Intelligence. The connect route returns the same body. runId is
present only when the thread has an active run. The connect route returns 204
with no body when the platform returns no connection.
A direct POST to the run route, for example from curl or a test script,
gets this JSON body and no events. To read the events of a thread without a
websocket client, call GET {basePath}/threads/:threadId/events. It returns
{ "events": [...] }. See Thread routes.
Inspector metadata
An Intelligence-backed runtime adds inspectorMetadata: true to its runtime-info
response. After the main connection completes, @copilotkit/core uses that flag
to request GET {basePath}/inspector-metadata in the background. Older runtimes
omit the flag, so newer clients skip the optional request.
A valid response is a versioned InspectorMetadataV1 JSON object. The response
always uses Cache-Control: no-store, private. The route returns 204 with the
same cache policy when data is absent, the schema is unsupported, the runtime is
not backed by Intelligence, or the provider request fails. A metadata failure
does not change the runtime connection or agent state. The upstream Intelligence
request has a five-second deadline; a timeout follows the same private 204
path.
{
"schemaVersion": 1,
"identity": {
"organizationName": "Acme",
"projectName": "Support"
},
"plan": {
"code": "team",
"label": "Team"
},
"license": {
"state": "valid"
},
"action": {
"kind": "manage_plan",
"url": "https://ops.example.com/account/organization/org_123/organization-billing"
},
"usage": {
"used": 42,
"limit": {
"kind": "finite",
"value": 1000
},
"expiringSoonCount": 7
}
}Every module is optional and independent. usage.expiringSoonCount counts
deadlines in the next 24 hours. 0 means none. When the field is absent,
no trusted expiry count is available.
curl -i http://localhost:4000/api/copilotkit/inspector-metadataFor the Inspector metadata request, @copilotkit/core sends the same
headers and fetch credentials as your other runtime requests. The runtime
uses its server-side Intelligence API key for the upstream request. It does not forward browser headers or cookies to Intelligence, and
it does not expose provider error bodies to the browser. Auth headers and
cookies can still protect the browser-to-runtime request like any other
runtime route.
Thread routes
The runtime also serves the conversation history behind the threads UI. These routes exist in multi-route mode whichever runner you use:
| Method & path | Purpose |
|---|---|
GET /api/copilotkit/threads | List threads. With Intelligence, the agentId query parameter is required. Without Intelligence, it is optional and filters the list. |
GET /api/copilotkit/threads/:threadId/messages | That thread's full message history. |
GET /api/copilotkit/threads/:threadId/events | That thread's compacted AG-UI event stream. |
GET /api/copilotkit/threads/:threadId/state | That thread's last state snapshot. |
POST /api/copilotkit/threads/clear | Clear the caller's in-memory threads. Returns 403 without identifyUser unless threads: { access: "open" } is set. Returns 204 and clears nothing on a runner that keeps no local store. |
PATCH or DELETE /api/copilotkit/threads/:threadId | Rename or delete a thread. Intelligence only. |
POST /api/copilotkit/threads/:threadId/archive | Archive a thread. Intelligence only. |
POST /api/copilotkit/threads/subscribe | Subscribe to thread changes. Intelligence only. |
An Intelligence runtime answers GET /threads with 400 when the request has
no agentId. Send the agent key you registered in CopilotRuntime. The
request also has to carry the auth that your identifyUser reads, because the
list holds only that user's threads:
curl -s "http://localhost:4000/api/copilotkit/threads?agentId=default"The response is { "threads": [...], "nextCursor": ... }. To page through it,
pass limit and the cursor from the previous response. Add
includeArchived=true to include archived threads. Those three parameters
apply only with Intelligence.
Thread routes are scoped to a user only with identifyUser
On the default InMemoryAgentRunner, and on anything extending it, such as
AgentCoreRunner, these routes read the runner's local store. Without
identifyUser, a thread id works as a capability: any caller with the id can
read, connect to, continue, and stop that thread. GET /threads and
POST /threads/clear return 403 unless you pass
threads: { access: "open" } to CopilotRuntime. With identifyUser, every
route reaches only the caller's own threads. A runner that keeps no local
store, such as SqliteAgentRunner, answers the four read routes with a 422
instead.
An Intelligence runtime scopes every thread route and the stop route to the
user that identifyUser returns.
:threadId is chosen by the client on the run, so it is not a secret. If more
than one person uses your deployment, pass identifyUser, or authorize these
routes yourself. See Thread authorization.
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/infoYou 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.
Enable AG-UI Streams routes
This section is for Intelligence users whose Inspector shows the Rich Threads setup view instead of saved threads. That view means Runtime info does not advertise the routes that list and inspect saved threads. The view depends on the Runtime's thread routes, not on license metadata. Complete these steps so the Inspector can load saved threads. To connect Intelligence from the start, follow the Intelligence quickstart.
Start with your coding agent
Use this prompt to configure Intelligence and verify that your Runtime exposes Intelligence's AG-UI streams.
Open your coding agent in your project's folder, or in an empty folder for a new app.This runs in a coding agent on your computer.
Choose a Runtime route mode
Single-route and multi-route handlers both expose Intelligence's AG-UI streams. Use single-route
when your server should expose only one POST endpoint:
const handler = createCopilotRuntimeHandler({
runtime,
basePath: "/api/copilotkit",
mode: "single-route",
});For multi-route, omit mode. Your server must mount the full Runtime subtree
and allow GET, POST, PATCH, and DELETE.
Keep CopilotKitProvider pointed at the Runtime base URL. It discovers the
transport when use-single-endpoint is omitted; set
:use-single-endpoint="true" only when you need to pin a single-route handler.
Construct the Intelligence client
intelligence is a CopilotKitIntelligence instance. Build it from your
project's Intelligence API key:
import { CopilotKitIntelligence } from "@copilotkit/runtime/v2";
const intelligence = new CopilotKitIntelligence({
apiKey: process.env.CPK_INTELLIGENCE_API_KEY!,
});apiKey is the only required option. copilotkit project select writes this
key into your project's .env as CPK_INTELLIGENCE_API_KEY, and this is what
consumes it.
Keep the key server-side. It is a project API key, so it is a different
credential from the browser-visible NEXT_PUBLIC_COPILOTKIT_LICENSE_KEY used by
the Inspector. Do not substitute one for the other.
apiUrl and wsUrl default to the cloud-hosted platform. The API and
realtime planes are deployed to different hosts, so one cannot be derived
from the other by swapping the scheme. Override them only for a self-hosted or
non-production deployment. Override both together. If you set only one,
the two planes point at different deployments and the client logs a warning:
const intelligence = new CopilotKitIntelligence({
apiKey: process.env.CPK_INTELLIGENCE_API_KEY!,
apiUrl: process.env.INTELLIGENCE_API_URL,
wsUrl: process.env.INTELLIGENCE_GATEWAY_WS_URL,
});Identify the signed-in application user
An Intelligence-backed web Runtime exposes threads only when it can scope them
to an application user. Add identifyUser and resolve the user from a
server-verified session or token:
const runtime = new CopilotRuntime({
agents,
intelligence,
identifyUser: async (request) => {
const user = await authenticateApplicationUser(request);
if (!user) throw new Error("Unauthorized");
return { id: user.id, name: user.name };
},
});See Scope AG-UI Streams to the signed-in user for the full identity and authorization pattern.
Mount the Runtime handler
For single-route, mount one exact path and allow POST:
export { handler as POST };For multi-route, pass the full basePath subtree to the Runtime. In file-based
routers, use a catch-all or splat route. Allow GET, POST, PATCH, and
DELETE:
export { handler as GET, handler as POST, handler as PATCH, handler as DELETE };See Deploy to any runtime for complete adapter examples.
Verify the advertised capabilities
Restart the Runtime. For multi-route, request its info endpoint:
curl -s http://localhost:4000/api/copilotkit/infoAn Intelligence-backed web Runtime that is ready for Intelligence's AG-UI streams includes:
{
"threadEndpoints": {
"list": true,
"inspect": true,
"mutations": true,
"realtimeMetadata": true
}
}For single-route, post an info envelope:
curl -s http://localhost:4000/api/copilotkit \
-H 'content-type: application/json' \
-d '{"method":"info"}'The response advertises the resource bridge and its thread features:
{
"singleRoute": {
"resourceOperations": true,
"threadEndpoints": {
"list": true,
"inspect": true,
"mutations": true,
"realtimeMetadata": true
}
}
}Reload your app after this response is available. The Inspector replaces the setup state with the saved threads list. Cloud-hosted and self-hosted Intelligence use the same Runtime route setup.
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 express from "express";
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-6-luna" }) },
});
const app = express();
app.use(
createCopilotExpressHandler({
runtime,
basePath: "/api/copilotkit",
mode: "single-route",
}),
);Install express yourself
express is an optional peer dependency of @copilotkit/runtime, so it is
not installed for you. Run npm install express (^4.18.0 || ^5.0.0) in the
app that mounts the adapter. Calling createCopilotExpressHandler without it
throws and names the fix. Nothing else in the runtime needs express, so Hono
and Next.js apps install nothing.
createCopilotExpressHandler requires basePath
createCopilotExpressHandler throws basePath must be provided for Express endpoint at mount time when basePath is missing, so the server fails to
start. Give it the same path the route is mounted at.
Keep every runtime import on /v2
Import the runtime from @copilotkit/runtime/v2 (and the Express adapter from
@copilotkit/runtime/v2/express). Reaching into the package root,
@copilotkit/runtime, gets you the v1 surface: a CopilotRuntime built there
does not serve these routes, and the mismatch shows up as routes that 404
rather than as an import error.
The optional Inspector metadata operation uses the same endpoint with this envelope:
{ "method": "inspector/metadata" }Its response and failure rules match GET {basePath}/inspector-metadata.
The client sends thread, memory, and annotation operations through the same
endpoint with a resource/request envelope. The Runtime accepts only known
resource paths and routes them through the same handlers as multi-route mode.
The Vue SDK also discovers the transport from Runtime info. Point
CopilotKitProvider at the base endpoint; no second route configuration is
needed:
<CopilotKitProvider runtime-url="/api/copilotkit">
<YourApp />
</CopilotKitProvider>Runtime info must remain reachable so the Vue client can discover the transport and registered agents.
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. With Express, pass cors: false to disable the built-in middleware
and handle CORS yourself, or pass a cors options object to scope it for
production. With Hono, pass cors: { origin, credentials } to scope it:
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 });
}
},
},
});onRequest runs before routing, so it knows the path but not the route. For
per-thread decisions use onBeforeHandler, which runs after routing and
receives the resolved route, including its threadId:
createCopilotExpressHandler({
runtime,
basePath: "/api/copilotkit",
hooks: {
onBeforeHandler: async ({ request, route }) => {
const user = await resolveUser(request);
// Routes that name a thread on `route`.
if ("threadId" in route) {
if (!(await userOwnsThread(user.id, route.threadId))) {
throw new Response("Forbidden", { status: 403 });
}
return;
}
// agent/run and agent/connect carry the thread in the body instead.
if (route.method === "agent/run" || route.method === "agent/connect") {
// Clone: the handler still needs to read the original body.
const { threadId } = await request.clone().json();
if (threadId && !(await userOwnsThread(user.id, threadId))) {
throw new Response("Forbidden", { status: 403 });
}
}
},
},
});route.threadId is present on agent/stop, threads/messages,
threads/events, threads/state, threads/update and threads/archive.
threads/list, threads/clear and threads/subscribe carry no thread at all,
so the only decision available for those three is whether to allow them.
See Auth for the full authentication guide and Thread authorization for the ownership map this example assumes.
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:
- The
agentIdin the URL isn't registered. The runtime returns{"error":"Agent not found","message":"Agent '<id>' does not exist"}with a404when no agent matches. The prebuilt components default to the agent named"default", so register one under that key (or pass an explicitagentId). connect()is called before anyrun()for an auto-minted thread. Some persistence backends only know about a thread once a run has produced events. In a custom runner, makeconnect()return an empty stream for a thread it has never seen, asInMemoryAgentRunnerdoes. See the AgentRunner guide and the/connect404 troubleshooting entry.
How is this guide?