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.

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 is an additive V1 leaf for deadlines in the next 24 hours: 0 is a known count, while absence means no trusted expiry count is available. Shared removes a malformed expiry leaf without removing valid used, limit, or sibling modules. Older V1 producers may omit the leaf, and older consumers may ignore it without a synchronized deployment.

curl -i http://localhost:4000/api/copilotkit/inspector-metadata

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.

Enable Rich Threads routes#

If the Inspector says Finish setting up Rich Threads, your Intelligence license is active but the Runtime is not exposing the routes used to list and inspect saved Threads. Complete these steps so /info advertises the Threads capabilities and the Inspector can load saved history.

const handler = createCopilotRuntimeHandler({
  runtime,
  basePath: "/api/copilotkit",
});

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

<CopilotKitProvider runtimeUrl="/api/copilotkit">
  <YourApp />
</CopilotKitProvider>

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 };
  },
});

export {
  handler as GET,
  handler as POST,
  handler as PATCH,
  handler as DELETE,
};

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

{
  "threadEndpoints": {
    "list": true,
    "inspect": true,
    "mutations": true,
    "realtimeMetadata": true
  }
}

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',
  }),
);

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.

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.

For Inspector metadata, Core sends these current browser-to-runtime headers and fetch credentials on the optional request. The Runtime then starts a separate server-to-Intelligence request with only its configured Intelligence API key.

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.
• Inspector: how trusted project context and license-aware actions appear in the Inspector.