Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

Collapse API Reference groups and hide callbacks apis (#333)

Bhavesh Patel5e03c3d54102
diff --git a/.changeset/openapi-docs-groups.md b/.changeset/openapi-docs-groups.md
new file mode 100644
index 000000000..55fcfeca4
--- /dev/null
+++ b/.changeset/openapi-docs-groups.md
@@ -0,0 +1,5 @@
+---
+'@truefoundry/trueforge': patch
+---
+
+Collapse Mintlify API Reference groups to Auth, Capabilities, Models, MCP Servers, Skills, Sandboxes, Agents, and Agent Sessions.
diff --git a/.github/fern/openapi/openapi.json b/.github/fern/openapi/openapi.json
index 0c344c41b..5986edcf8 100644
--- a/.github/fern/openapi/openapi.json
+++ b/.github/fern/openapi/openapi.json
@@ -4516,6 +4516,7 @@
"tags": [
"Auth"
],
+ "x-excluded": true,
"x-fern-ignore": true
}
},
@@ -4543,6 +4544,7 @@
"tags": [
"Auth"
],
+ "x-excluded": true,
"x-fern-ignore": true
}
},
@@ -4558,6 +4560,7 @@
"tags": [
"Auth"
],
+ "x-excluded": true,
"x-fern-sdk-group-name": [
"auth"
],
@@ -4661,7 +4664,7 @@
},
"summary": "Get the MCP catalog",
"tags": [
- "Catalog"
+ "MCP Servers"
],
"x-fern-sdk-group-name": [
"catalogs",
@@ -4697,7 +4700,7 @@
},
"summary": "Get the model catalog",
"tags": [
- "Catalog"
+ "Models"
],
"x-fern-sdk-group-name": [
"catalogs",
@@ -4733,7 +4736,7 @@
},
"summary": "Get the sandbox provider catalog",
"tags": [
- "Catalog"
+ "Sandboxes"
],
"x-fern-sdk-group-name": [
"catalogs",
@@ -4769,7 +4772,7 @@
},
"summary": "Get the skill catalog",
"tags": [
- "Catalog"
+ "Skills"
],
"x-fern-sdk-group-name": [
"catalogs",
@@ -4909,8 +4912,9 @@
},
"summary": "OAuth callback for MCP authorization",
"tags": [
- "MCP OAuth"
+ "MCP Servers"
],
+ "x-excluded": true,
"x-fern-ignore": true
}
},
@@ -5266,7 +5270,7 @@
},
"summary": "List sessions",
"tags": [
- "Sessions"
+ "Agent Sessions"
],
"x-fern-pagination": {
"cursor": "$request.page_token",
@@ -5334,7 +5338,7 @@
},
"summary": "Create a session",
"tags": [
- "Sessions"
+ "Agent Sessions"
],
"x-fern-sdk-group-name": [
"sessions"
@@ -5376,7 +5380,7 @@
},
"summary": "Delete a session",
"tags": [
- "Sessions"
+ "Agent Sessions"
],
"x-fern-sdk-group-name": [
"sessions"
@@ -5433,7 +5437,7 @@
},
"summary": "Get a session",
"tags": [
- "Sessions"
+ "Agent Sessions"
],
"x-fern-sdk-group-name": [
"sessions"
@@ -5520,7 +5524,7 @@
},
"summary": "Update a session",
"tags": [
- "Sessions"
+ "Agent Sessions"
],
"x-fern-sdk-group-name": [
"sessions"
@@ -5599,7 +5603,7 @@
},
"summary": "Cancel a running turn in a session",
"tags": [
- "Sessions"
+ "Agent Sessions"
],
"x-fern-sdk-group-name": [
"sessions"
@@ -5701,7 +5705,7 @@
},
"summary": "List session events",
"tags": [
- "Sessions"
+ "Agent Sessions"
],
"x-fern-pagination": {
"cursor": "$request.page_token",
@@ -5798,7 +5802,7 @@
},
"summary": "List turns in a session",
"tags": [
- "Sessions"
+ "Agent Sessions"
],
"x-fern-pagination": {
"cursor": "$request.page_token",
@@ -5915,7 +5919,7 @@
},
"summary": "Create and execute a turn in a session",
"tags": [
- "Sessions"
+ "Agent Sessions"
],
"x-fern-sdk-group-name": [
"sessions"
@@ -5996,7 +6000,7 @@
},
"summary": "Get a turn",
"tags": [
- "Sessions"
+ "Agent Sessions"
],
"x-fern-sdk-group-name": [
"sessions"
@@ -6128,7 +6132,7 @@
},
"summary": "Download a file from the turn sandbox",
"tags": [
- "Sessions"
+ "Agent Sessions"
],
"x-fern-sdk-group-name": [
"sessions"
@@ -6240,7 +6244,7 @@
},
"summary": "List turn events",
"tags": [
- "Sessions"
+ "Agent Sessions"
],
"x-fern-pagination": {
"cursor": "$request.page_token",
@@ -6349,7 +6353,7 @@
},
"summary": "Subscribe to a running turn",
"tags": [
- "Sessions"
+ "Agent Sessions"
],
"x-fern-sdk-group-name": [
"sessions"
@@ -6611,7 +6615,7 @@
},
"summary": "List configured model providers",
"tags": [
- "Model Providers"
+ "Models"
],
"x-fern-sdk-group-name": [
"settings",
@@ -6665,7 +6669,7 @@
},
"summary": "Create a model provider",
"tags": [
- "Model Providers"
+ "Models"
],
"x-fern-sdk-group-name": [
"settings",
@@ -6709,7 +6713,7 @@
},
"summary": "Create or replace a model provider",
"tags": [
- "Model Providers"
+ "Models"
],
"x-fern-sdk-group-name": [
"settings",
@@ -6745,7 +6749,7 @@
},
"summary": "Get the configured sandbox provider",
"tags": [
- "Sandbox Providers"
+ "Sandboxes"
],
"x-fern-sdk-group-name": [
"settings",
@@ -6799,7 +6803,7 @@
},
"summary": "Create or replace the sandbox provider",
"tags": [
- "Sandbox Providers"
+ "Sandboxes"
],
"x-fern-sdk-group-name": [
"settings",
@@ -6993,5 +6997,31 @@
"BearerAuth": []
}
],
+ "tags": [
+ {
+ "name": "Auth"
+ },
+ {
+ "name": "Capabilities"
+ },
+ {
+ "name": "Models"
+ },
+ {
+ "name": "MCP Servers"
+ },
+ {
+ "name": "Skills"
+ },
+ {
+ "name": "Sandboxes"
+ },
+ {
+ "name": "Agents"
+ },
+ {
+ "name": "Agent Sessions"
+ }
+ ],
"webhooks": {}
}
diff --git a/docs/openapi.json b/docs/openapi.json
index 0c344c41b..5986edcf8 100644
--- a/docs/openapi.json
+++ b/docs/openapi.json
@@ -4516,6 +4516,7 @@
"tags": [
"Auth"
],
+ "x-excluded": true,
"x-fern-ignore": true
}
},
@@ -4543,6 +4544,7 @@
"tags": [
"Auth"
],
+ "x-excluded": true,
"x-fern-ignore": true
}
},
@@ -4558,6 +4560,7 @@
"tags": [
"Auth"
],
+ "x-excluded": true,
"x-fern-sdk-group-name": [
"auth"
],
@@ -4661,7 +4664,7 @@
},
"summary": "Get the MCP catalog",
"tags": [
- "Catalog"
+ "MCP Servers"
],
"x-fern-sdk-group-name": [
"catalogs",
@@ -4697,7 +4700,7 @@
},
"summary": "Get the model catalog",
"tags": [
- "Catalog"
+ "Models"
],
"x-fern-sdk-group-name": [
"catalogs",
@@ -4733,7 +4736,7 @@
},
"summary": "Get the sandbox provider catalog",
"tags": [
- "Catalog"
+ "Sandboxes"
],
"x-fern-sdk-group-name": [
"catalogs",
@@ -4769,7 +4772,7 @@
},
"summary": "Get the skill catalog",
"tags": [
- "Catalog"
+ "Skills"
],
"x-fern-sdk-group-name": [
"catalogs",
@@ -4909,8 +4912,9 @@
},
"summary": "OAuth callback for MCP authorization",
"tags": [
- "MCP OAuth"
+ "MCP Servers"
],
+ "x-excluded": true,
"x-fern-ignore": true
}
},
@@ -5266,7 +5270,7 @@
},
"summary": "List sessions",
"tags": [
- "Sessions"
+ "Agent Sessions"
],
"x-fern-pagination": {
"cursor": "$request.page_token",
@@ -5334,7 +5338,7 @@
},
"summary": "Create a session",
"tags": [
- "Sessions"
+ "Agent Sessions"
],
"x-fern-sdk-group-name": [
"sessions"
@@ -5376,7 +5380,7 @@
},
"summary": "Delete a session",
"tags": [
- "Sessions"
+ "Agent Sessions"
],
"x-fern-sdk-group-name": [
"sessions"
@@ -5433,7 +5437,7 @@
},
"summary": "Get a session",
"tags": [
- "Sessions"
+ "Agent Sessions"
],
"x-fern-sdk-group-name": [
"sessions"
@@ -5520,7 +5524,7 @@
},
"summary": "Update a session",
"tags": [
- "Sessions"
+ "Agent Sessions"
],
"x-fern-sdk-group-name": [
"sessions"
@@ -5599,7 +5603,7 @@
},
"summary": "Cancel a running turn in a session",
"tags": [
- "Sessions"
+ "Agent Sessions"
],
"x-fern-sdk-group-name": [
"sessions"
@@ -5701,7 +5705,7 @@
},
"summary": "List session events",
"tags": [
- "Sessions"
+ "Agent Sessions"
],
"x-fern-pagination": {
"cursor": "$request.page_token",
@@ -5798,7 +5802,7 @@
},
"summary": "List turns in a session",
"tags": [
- "Sessions"
+ "Agent Sessions"
],
"x-fern-pagination": {
"cursor": "$request.page_token",
@@ -5915,7 +5919,7 @@
},
"summary": "Create and execute a turn in a session",
"tags": [
- "Sessions"
+ "Agent Sessions"
],
"x-fern-sdk-group-name": [
"sessions"
@@ -5996,7 +6000,7 @@
},
"summary": "Get a turn",
"tags": [
- "Sessions"
+ "Agent Sessions"
],
"x-fern-sdk-group-name": [
"sessions"
@@ -6128,7 +6132,7 @@
},
"summary": "Download a file from the turn sandbox",
"tags": [
- "Sessions"
+ "Agent Sessions"
],
"x-fern-sdk-group-name": [
"sessions"
@@ -6240,7 +6244,7 @@
},
"summary": "List turn events",
"tags": [
- "Sessions"
+ "Agent Sessions"
],
"x-fern-pagination": {
"cursor": "$request.page_token",
@@ -6349,7 +6353,7 @@
},
"summary": "Subscribe to a running turn",
"tags": [
- "Sessions"
+ "Agent Sessions"
],
"x-fern-sdk-group-name": [
"sessions"
@@ -6611,7 +6615,7 @@
},
"summary": "List configured model providers",
"tags": [
- "Model Providers"
+ "Models"
],
"x-fern-sdk-group-name": [
"settings",
@@ -6665,7 +6669,7 @@
},
"summary": "Create a model provider",
"tags": [
- "Model Providers"
+ "Models"
],
"x-fern-sdk-group-name": [
"settings",
@@ -6709,7 +6713,7 @@
},
"summary": "Create or replace a model provider",
"tags": [
- "Model Providers"
+ "Models"
],
"x-fern-sdk-group-name": [
"settings",
@@ -6745,7 +6749,7 @@
},
"summary": "Get the configured sandbox provider",
"tags": [
- "Sandbox Providers"
+ "Sandboxes"
],
"x-fern-sdk-group-name": [
"settings",
@@ -6799,7 +6803,7 @@
},
"summary": "Create or replace the sandbox provider",
"tags": [
- "Sandbox Providers"
+ "Sandboxes"
],
"x-fern-sdk-group-name": [
"settings",
@@ -6993,5 +6997,31 @@
"BearerAuth": []
}
],
+ "tags": [
+ {
+ "name": "Auth"
+ },
+ {
+ "name": "Capabilities"
+ },
+ {
+ "name": "Models"
+ },
+ {
+ "name": "MCP Servers"
+ },
+ {
+ "name": "Skills"
+ },
+ {
+ "name": "Sandboxes"
+ },
+ {
+ "name": "Agents"
+ },
+ {
+ "name": "Agent Sessions"
+ }
+ ],
"webhooks": {}
}
diff --git a/packages/trueforge-sdk/reference.md b/packages/trueforge-sdk/reference.md
index 653c51c92..aef46b71f 100644
--- a/packages/trueforge-sdk/reference.md
+++ b/packages/trueforge-sdk/reference.md
@@ -495,7 +495,7 @@ await client.server.getCapabilities();
</dl>
</details>
-## McpServers
+## MCP Servers
<details><summary><code>client.mcpServers.<a href="/src/api/resources/mcpServers/client/Client.ts">list</a>() -> TrueForge.ListAvailableMcpServersResponse</code></summary>
<dl>
<dd>
diff --git a/packages/trueforge/src/app.ts b/packages/trueforge/src/app.ts
index 9e3a6b6a3..69a55d3a9 100644
--- a/packages/trueforge/src/app.ts
+++ b/packages/trueforge/src/app.ts
@@ -36,6 +36,7 @@ import type { ISkillStore } from './db/skillStore';
import type { WithTransaction } from './db/transaction';
import type { IOAuthTokenStore } from './mcp/auth/types';
import { PACKAGE_VERSION } from './packageVersion';
+import { OPENAPI_DOCUMENT_TAGS } from './routes/openapiTags';
import type { ActiveTurnRegistry } from './runtime/activeTurns';
import type { EventSubscriptionRegistry } from './runtime/event-subscription';
import { zodErrorResponse, zodValidationHook } from './zodErrorResponse';
@@ -84,6 +85,7 @@ const openApiDocConfig = {
'Covers DB-backed sessions, the agent registry, settings catalogs, and model/MCP/skill/sandbox providers.',
version: PACKAGE_VERSION,
},
+ tags: OPENAPI_DOCUMENT_TAGS,
};
/** Registers the Bearer ID-token scheme used by {@link buildOpenApiDocument}. */
diff --git a/packages/trueforge/src/routes/agentRoutes.ts b/packages/trueforge/src/routes/agentRoutes.ts
index fea097bc7..da72aae21 100644
--- a/packages/trueforge/src/routes/agentRoutes.ts
+++ b/packages/trueforge/src/routes/agentRoutes.ts
@@ -11,8 +11,7 @@ import {
PutAgentRequestSchema,
} from '../schemas/agent';
import { RequestErrorResponseSchema } from '../schemas/errors';
-
-const AGENTS_TAG = 'Agents';
+import { OpenApiTag } from './openapiTags';
export const AgentIdParamsSchema = z.object({
agent_id: z.string().min(1).max(64).describe('Immutable agent identifier.'),
@@ -21,7 +20,7 @@ export const AgentIdParamsSchema = z.object({
export const listAgentsRoute = createRoute({
method: 'get',
path: '/',
- tags: [AGENTS_TAG],
+ tags: [OpenApiTag.AGENTS],
summary: 'List agents',
description: 'All configured agents for the tenant.',
'x-fern-sdk-group-name': ['agents'],
@@ -41,7 +40,7 @@ export const listAgentsRoute = createRoute({
export const createAgentRoute = createRoute({
method: 'post',
path: '/',
- tags: [AGENTS_TAG],
+ tags: [OpenApiTag.AGENTS],
summary: 'Create an agent',
description:
'Creates an agent and allocates an immutable id. Fails if `name` is already taken. Name cannot be changed later.',
@@ -77,7 +76,7 @@ export const createAgentRoute = createRoute({
export const getAgentRoute = createRoute({
method: 'get',
path: '/{agent_id}',
- tags: [AGENTS_TAG],
+ tags: [OpenApiTag.AGENTS],
summary: 'Get an agent',
description: 'Fetch a configured agent by immutable id.',
'x-fern-sdk-group-name': ['agents'],
@@ -100,7 +99,7 @@ export const getAgentRoute = createRoute({
export const deleteAgentRoute = createRoute({
method: 'delete',
path: '/{agent_id}',
- tags: [AGENTS_TAG],
+ tags: [OpenApiTag.AGENTS],
summary: 'Delete an agent',
description: 'Delete a configured agent by immutable id. Idempotent if already gone.',
'x-fern-sdk-group-name': ['agents'],
@@ -123,7 +122,7 @@ export const deleteAgentRoute = createRoute({
export const putAgentRoute = createRoute({
method: 'put',
path: '/{agent_id}',
- tags: [AGENTS_TAG],
+ tags: [OpenApiTag.AGENTS],
summary: 'Update an agent',
description: 'Replaces the manifest for an existing agent keyed by immutable `agent_id`.',
'x-fern-sdk-group-name': ['agents'],
diff --git a/packages/trueforge/src/routes/authRoutes.ts b/packages/trueforge/src/routes/authRoutes.ts
index 132850455..0e45109c5 100644
--- a/packages/trueforge/src/routes/authRoutes.ts
+++ b/packages/trueforge/src/routes/authRoutes.ts
@@ -8,18 +8,18 @@
import { createRoute } from '@hono/zod-openapi';
import { AuthLoginQuerySchema, MeResponseSchema, OAuthCallbackQuerySchema } from '../schemas/auth';
import { RequestErrorResponseSchema } from '../schemas/errors';
-
-const AUTH_TAG = 'Auth';
+import { OpenApiTag } from './openapiTags';
export const authLoginRoute = createRoute({
method: 'get',
path: '/login',
- tags: [AUTH_TAG],
+ tags: [OpenApiTag.AUTH],
summary: 'Start the login flow',
description:
'Redirects the browser to the configured identity provider. In local/single-binary mode, redirects straight ' +
'back into the app — there is nothing to log into.',
'x-fern-ignore': true,
+ 'x-excluded': true,
request: { query: AuthLoginQuerySchema },
responses: {
302: { description: 'Redirect to the IdP authorization endpoint.' },
@@ -29,12 +29,13 @@ export const authLoginRoute = createRoute({
export const oAuthCallbackRoute = createRoute({
method: 'get',
path: '/callback',
- tags: [AUTH_TAG],
+ tags: [OpenApiTag.AUTH],
summary: 'Login callback',
description:
'Browser-redirect target hit by the identity provider after login, never called directly by SDK consumers. ' +
'In local/single-binary mode, redirects straight back into the app.',
'x-fern-ignore': true,
+ 'x-excluded': true,
request: { query: OAuthCallbackQuerySchema },
responses: {
302: { description: 'Redirect back into the app on success, or to /?error=<reason> on failure.' },
@@ -44,13 +45,14 @@ export const oAuthCallbackRoute = createRoute({
export const authLogoutRoute = createRoute({
method: 'post',
path: '/logout',
- tags: [AUTH_TAG],
+ tags: [OpenApiTag.AUTH],
summary: 'Clear the local session',
description:
'Ends the local harness session only — does not hit the IdP end-session endpoint. A no-op in local/single-binary ' +
'mode, since there is no real session to clear.',
'x-fern-sdk-group-name': ['auth'],
'x-fern-sdk-method-name': 'logout',
+ 'x-excluded': true,
responses: {
204: { description: 'Session cookie cleared.' },
},
@@ -59,7 +61,7 @@ export const authLogoutRoute = createRoute({
export const meRoute = createRoute({
method: 'get',
path: '/me',
- tags: [AUTH_TAG],
+ tags: [OpenApiTag.AUTH],
summary: 'Current session',
description:
'Returns the authenticated caller identity. When auth is enabled this requires a valid ' +
diff --git a/packages/trueforge/src/routes/capabilityRoutes.ts b/packages/trueforge/src/routes/capabilityRoutes.ts
index a8f626038..714161ee5 100644
--- a/packages/trueforge/src/routes/capabilityRoutes.ts
+++ b/packages/trueforge/src/routes/capabilityRoutes.ts
@@ -1,5 +1,6 @@
import { createRoute, z } from '@hono/zod-openapi';
import { RequestErrorResponseSchema } from '../schemas/errors';
+import { OpenApiTag } from './openapiTags';
const GetCapabilitiesResponseSchema = z
.object({
@@ -23,7 +24,7 @@ const GetCapabilitiesResponseSchema = z
export const getCapabilitiesRoute = createRoute({
method: 'get',
path: '/',
- tags: ['Capabilities'],
+ tags: [OpenApiTag.CAPABILITIES],
summary: 'Get server capabilities',
'x-fern-sdk-group-name': ['server'],
'x-fern-sdk-method-name': 'get_capabilities',
diff --git a/packages/trueforge/src/routes/catalogRoutes.ts b/packages/trueforge/src/routes/catalogRoutes.ts
index 6300cbd1f..3eb95d688 100644
--- a/packages/trueforge/src/routes/catalogRoutes.ts
+++ b/packages/trueforge/src/routes/catalogRoutes.ts
@@ -8,13 +8,12 @@ import { GetMcpServerCatalogResponseSchema } from '../schemas/mcpCatalog';
import { GetModelProviderCatalogResponseSchema } from '../schemas/modelCatalog';
import { GetSandboxProviderCatalogResponseSchema } from '../schemas/sandboxCatalog';
import { GetSkillCatalogResponseSchema } from '../schemas/skillCatalog';
-
-const CATALOG_TAG = 'Catalog';
+import { OpenApiTag } from './openapiTags';
export const listModelProviderCatalogRoute = createRoute({
method: 'get',
path: '/model-providers',
- tags: [CATALOG_TAG],
+ tags: [OpenApiTag.MODELS],
summary: 'Get the model catalog',
description:
'Shipped model-provider presets (discovery-only). Copy into PUT /settings/model-providers to configure. ' +
@@ -36,7 +35,7 @@ export const listModelProviderCatalogRoute = createRoute({
export const listMcpServerCatalogRoute = createRoute({
method: 'get',
path: '/mcp-servers',
- tags: [CATALOG_TAG],
+ tags: [OpenApiTag.MCP_SERVERS],
summary: 'Get the MCP catalog',
description: 'Shipped MCP server presets (discovery-only). Copy into PUT /settings/mcp-servers to configure.',
'x-fern-sdk-group-name': ['catalogs', 'mcpServers'],
@@ -56,7 +55,7 @@ export const listMcpServerCatalogRoute = createRoute({
export const listSkillCatalogRoute = createRoute({
method: 'get',
path: '/skills',
- tags: [CATALOG_TAG],
+ tags: [OpenApiTag.SKILLS],
summary: 'Get the skill catalog',
description: 'Shipped skill presets (discovery-only). Copy into PUT /settings/skills to configure.',
'x-fern-sdk-group-name': ['catalogs', 'skills'],
@@ -76,7 +75,7 @@ export const listSkillCatalogRoute = createRoute({
export const listSandboxProviderCatalogRoute = createRoute({
method: 'get',
path: '/sandbox-providers',
- tags: [CATALOG_TAG],
+ tags: [OpenApiTag.SANDBOXES],
summary: 'Get the sandbox provider catalog',
description:
'Shipped sandbox-provider presets (discovery-only). Copy into PUT /settings/sandbox-providers to configure.',
diff --git a/packages/trueforge/src/routes/mcpOAuthRoutes.ts b/packages/trueforge/src/routes/mcpOAuthRoutes.ts
index ea60206ed..9fe6610a3 100644
--- a/packages/trueforge/src/routes/mcpOAuthRoutes.ts
+++ b/packages/trueforge/src/routes/mcpOAuthRoutes.ts
@@ -1,13 +1,12 @@
import { createRoute } from '@hono/zod-openapi';
import { OAuthCallbackQuerySchema, OAuthCallbackSuccessSchema } from '../schemas/auth';
import { RequestErrorResponseSchema } from '../schemas/errors';
-
-const MCP_OAUTH_TAG = 'MCP OAuth';
+import { OpenApiTag } from './openapiTags';
export const mcpOAuthCallbackRoute = createRoute({
method: 'get',
path: '/callback',
- tags: [MCP_OAUTH_TAG],
+ tags: [OpenApiTag.MCP_SERVERS],
summary: 'OAuth callback for MCP authorization',
description:
'Browser redirect target for MCP server OAuth. The authorization server redirects here with `code`/`state` (or `error`). ' +
@@ -15,6 +14,7 @@ export const mcpOAuthCallbackRoute = createRoute({
'Not called by the SDK — browsers hit this URL directly.',
// Browser-redirect target hit directly by the authorization server, never called by SDK.
'x-fern-ignore': true,
+ 'x-excluded': true,
request: {
query: OAuthCallbackQuerySchema,
},
diff --git a/packages/trueforge/src/routes/mcpServerRoutes.ts b/packages/trueforge/src/routes/mcpServerRoutes.ts
index 1efd668e5..7ef1d7e4c 100644
--- a/packages/trueforge/src/routes/mcpServerRoutes.ts
+++ b/packages/trueforge/src/routes/mcpServerRoutes.ts
@@ -13,14 +13,13 @@ import {
McpAuthStatusSchema,
PutMcpServerRequestSchema,
} from '../schemas/mcpServer';
-
-const MCP_SERVERS_TAG = 'MCP Servers';
+import { OpenApiTag } from './openapiTags';
/** Chat/composer read view — mounted at /api/v1/mcp-servers (not under settings). */
export const listAvailableMcpServersRoute = createRoute({
method: 'get',
path: '/',
- tags: [MCP_SERVERS_TAG],
+ tags: [OpenApiTag.MCP_SERVERS],
summary: 'List MCP servers for chat',
description: 'MCP servers as a slim name/url list for the composer. No auth or auth_status.',
'x-fern-sdk-group-name': ['mcpServers'],
@@ -40,7 +39,7 @@ export const listAvailableMcpServersRoute = createRoute({
export const listMcpServersRoute = createRoute({
method: 'get',
path: '/',
- tags: [MCP_SERVERS_TAG],
+ tags: [OpenApiTag.MCP_SERVERS],
summary: 'List MCP servers',
description:
'All MCP servers with nested auth_status (settings / admin projection). Header auth values are redacted.',
@@ -69,7 +68,7 @@ const McpServerNameParamsSchema = z.object({
export const getMcpServerRoute = createRoute({
method: 'get',
path: '/{name}',
- tags: [MCP_SERVERS_TAG],
+ tags: [OpenApiTag.MCP_SERVERS],
summary: 'Get a single MCP server by name',
description:
'A single MCP server by name, with nested auth_status (settings / admin projection). Header auth values are redacted.',
@@ -93,7 +92,7 @@ export const getMcpServerRoute = createRoute({
export const createMcpServerRoute = createRoute({
method: 'post',
path: '/',
- tags: [MCP_SERVERS_TAG],
+ tags: [OpenApiTag.MCP_SERVERS],
summary: 'Create an MCP server',
description:
'Creates an MCP server by `name`. Fails if `name` is already taken. Runs DCR registration when `auth.type` is `dcr`. ' +
@@ -129,7 +128,7 @@ export const createMcpServerRoute = createRoute({
export const putMcpServerRoute = createRoute({
method: 'put',
path: '/',
- tags: [MCP_SERVERS_TAG],
+ tags: [OpenApiTag.MCP_SERVERS],
summary: 'Create or replace an MCP server',
description:
'Create or replace by `name`. Does not start DCR or change oauth client columns. ' +
@@ -170,7 +169,7 @@ const ListMcpServerToolsResponseSchema = z
export const listMcpServerToolsRoute = createRoute({
method: 'get',
path: '/{name}/tools',
- tags: [MCP_SERVERS_TAG],
+ tags: [OpenApiTag.MCP_SERVERS],
summary: 'List tools of an MCP server',
'x-fern-sdk-group-name': ['mcpServers'],
'x-fern-sdk-method-name': 'list_tools',
@@ -214,7 +213,7 @@ const McpAuthorizeQuerySchema = z.object({
export const authorizeMcpServerRoute = createRoute({
method: 'get',
path: '/{name}/authorize',
- tags: [MCP_SERVERS_TAG],
+ tags: [OpenApiTag.MCP_SERVERS],
summary: 'Start (or short-circuit) the auth flow for an MCP server',
'x-fern-sdk-group-name': ['mcpServers'],
'x-fern-sdk-method-name': 'authorize',
@@ -258,7 +257,7 @@ export const authorizeMcpServerRoute = createRoute({
export const deleteAuthorizationMcpServerRoute = createRoute({
method: 'delete',
path: '/{name}/authorize',
- tags: [MCP_SERVERS_TAG],
+ tags: [OpenApiTag.MCP_SERVERS],
summary: 'Disconnect OAuth for an MCP server',
'x-fern-sdk-group-name': ['mcpServers'],
'x-fern-sdk-method-name': 'delete_authorization',
diff --git a/packages/trueforge/src/routes/modelProviderRoutes.ts b/packages/trueforge/src/routes/modelProviderRoutes.ts
index ee7879f3e..e2a3ffd1c 100644
--- a/packages/trueforge/src/routes/modelProviderRoutes.ts
+++ b/packages/trueforge/src/routes/modelProviderRoutes.ts
@@ -11,13 +11,12 @@ import {
ListModelProvidersResponseSchema,
PutModelProviderRequestSchema,
} from '../schemas/modelProvider';
-
-const MODEL_PROVIDERS_TAG = 'Model Providers';
+import { OpenApiTag } from './openapiTags';
export const listModelProvidersRoute = createRoute({
method: 'get',
path: '/',
- tags: [MODEL_PROVIDERS_TAG],
+ tags: [OpenApiTag.MODELS],
summary: 'List configured model providers',
description: 'All configured providers with nested manifests.',
'x-fern-sdk-group-name': ['settings', 'modelProviders'],
@@ -41,7 +40,7 @@ export const listModelProvidersRoute = createRoute({
export const createModelProviderRoute = createRoute({
method: 'post',
path: '/',
- tags: [MODEL_PROVIDERS_TAG],
+ tags: [OpenApiTag.MODELS],
summary: 'Create a model provider',
description:
'Creates a provider (models included). Fails if `name` is already taken. Well-known types use `type` as `name` (one each); ' +
@@ -73,7 +72,7 @@ export const createModelProviderRoute = createRoute({
export const putModelProviderRoute = createRoute({
method: 'put',
path: '/',
- tags: [MODEL_PROVIDERS_TAG],
+ tags: [OpenApiTag.MODELS],
summary: 'Create or replace a model provider',
description:
'Create or replace a provider (models included). Well-known types use `type` as `name` (one each); ' +
diff --git a/packages/trueforge/src/routes/modelRoutes.ts b/packages/trueforge/src/routes/modelRoutes.ts
index d89d53bc2..750e9f6aa 100644
--- a/packages/trueforge/src/routes/modelRoutes.ts
+++ b/packages/trueforge/src/routes/modelRoutes.ts
@@ -1,11 +1,12 @@
import { createRoute } from '@hono/zod-openapi';
import { RequestErrorResponseSchema } from '../schemas/errors';
import { ListModelsResponseSchema } from '../schemas/modelProvider';
+import { OpenApiTag } from './openapiTags';
export const listModelsRoute = createRoute({
method: 'get',
path: '/',
- tags: ['Models'],
+ tags: [OpenApiTag.MODELS],
summary: 'List models',
'x-fern-sdk-group-name': ['models'],
'x-fern-sdk-method-name': 'list',
diff --git a/packages/trueforge/src/routes/openapiTags.ts b/packages/trueforge/src/routes/openapiTags.ts
new file mode 100644
index 000000000..549f94b58
--- /dev/null
+++ b/packages/trueforge/src/routes/openapiTags.ts
@@ -0,0 +1,23 @@
+/** Mintlify API Reference groups — the only OpenAPI `tags` values. */
+export enum OpenApiTag {
+ AUTH = 'Auth',
+ CAPABILITIES = 'Capabilities',
+ MODELS = 'Models',
+ MCP_SERVERS = 'MCP Servers',
+ SKILLS = 'Skills',
+ SANDBOXES = 'Sandboxes',
+ AGENTS = 'Agents',
+ AGENT_SESSIONS = 'Agent Sessions',
+}
+
+/** Document-level tag order for `/api/v1/docs` and Mintlify. */
+export const OPENAPI_DOCUMENT_TAGS: { name: OpenApiTag }[] = [
+ { name: OpenApiTag.AUTH },
+ { name: OpenApiTag.CAPABILITIES },
+ { name: OpenApiTag.MODELS },
+ { name: OpenApiTag.MCP_SERVERS },
+ { name: OpenApiTag.SKILLS },
+ { name: OpenApiTag.SANDBOXES },
+ { name: OpenApiTag.AGENTS },
+ { name: OpenApiTag.AGENT_SESSIONS },
+];
diff --git a/packages/trueforge/src/routes/sandboxProviderRoutes.ts b/packages/trueforge/src/routes/sandboxProviderRoutes.ts
index 3c83ebc18..5c9144b3c 100644
--- a/packages/trueforge/src/routes/sandboxProviderRoutes.ts
+++ b/packages/trueforge/src/routes/sandboxProviderRoutes.ts
@@ -6,13 +6,12 @@
import { createRoute } from '@hono/zod-openapi';
import { RequestErrorResponseSchema } from '../schemas/errors';
import { GetSandboxProviderResponseSchema, PutSandboxProviderRequestSchema } from '../schemas/sandboxProvider';
-
-const SANDBOX_PROVIDERS_TAG = 'Sandbox Providers';
+import { OpenApiTag } from './openapiTags';
export const getSandboxProviderRoute = createRoute({
method: 'get',
path: '/',
- tags: [SANDBOX_PROVIDERS_TAG],
+ tags: [OpenApiTag.SANDBOXES],
summary: 'Get the configured sandbox provider',
description: 'The single configured sandbox provider for this tenant. `auth.api_key` is redacted.',
'x-fern-sdk-group-name': ['settings', 'sandboxProviders'],
@@ -32,7 +31,7 @@ export const getSandboxProviderRoute = createRoute({
export const putSandboxProviderRoute = createRoute({
method: 'put',
path: '/',
- tags: [SANDBOX_PROVIDERS_TAG],
+ tags: [OpenApiTag.SANDBOXES],
summary: 'Create or replace the sandbox provider',
description:
'Upserts the single sandbox provider for this tenant: creates it or replaces its entire configuration. ' +
diff --git a/packages/trueforge/src/routes/sessionRoutes.ts b/packages/trueforge/src/routes/sessionRoutes.ts
index e87eb95bc..441657579 100644
--- a/packages/trueforge/src/routes/sessionRoutes.ts
+++ b/packages/trueforge/src/routes/sessionRoutes.ts
@@ -15,8 +15,7 @@ import {
} from '../schemas/session';
import { CancelSessionRequestSchema, CancelSessionResponseSchema } from '../schemas/turn';
import { TOKEN_PAGINATION } from './fernExtensions';
-
-const SESSIONS_TAG = 'Sessions';
+import { OpenApiTag } from './openapiTags';
export const SessionIdParamsSchema = z.object({
session_id: z.string().min(1).max(64).describe('Session identifier.'),
@@ -25,7 +24,7 @@ export const SessionIdParamsSchema = z.object({
export const createSessionRoute = createRoute({
method: 'post',
path: '/',
- tags: [SESSIONS_TAG],
+ tags: [OpenApiTag.AGENT_SESSIONS],
summary: 'Create a session',
description:
'Create a session with `agent` as either `{ name }` (named registry binding) or `{ spec: AgentSpec }` (inline). Named sessions snapshot the agent name at create and resolve the live agent on each turn. Responses use `{ type: "reference", name, id }` or `{ type: "inline", spec }`.',
@@ -61,7 +60,7 @@ export const createSessionRoute = createRoute({
export const getSessionRoute = createRoute({
method: 'get',
path: '/{session_id}',
- tags: [SESSIONS_TAG],
+ tags: [OpenApiTag.AGENT_SESSIONS],
summary: 'Get a session',
description: 'Fetch a session by ID. Only the session creator (`created_by`) may fetch it.',
'x-fern-sdk-group-name': ['sessions'],
@@ -88,7 +87,7 @@ export const getSessionRoute = createRoute({
export const deleteSessionRoute = createRoute({
method: 'delete',
path: '/{session_id}',
- tags: [SESSIONS_TAG],
+ tags: [OpenApiTag.AGENT_SESSIONS],
summary: 'Delete a session',
description:
'Delete a session and all related turns, events, and internal state. Only the session creator (`created_by`) may delete it. Idempotent if already gone.',
@@ -111,7 +110,7 @@ export const deleteSessionRoute = createRoute({
export const updateSessionRoute = createRoute({
method: 'patch',
path: '/{session_id}',
- tags: [SESSIONS_TAG],
+ tags: [OpenApiTag.AGENT_SESSIONS],
summary: 'Update a session',
description:
'Update a session by replacing `agent` with `{ spec: AgentSpec }`. Named (reference) sessions reject agent updates. An empty body is a valid no-op that refreshes `updated_at`. Only the session creator (`created_by`) may update it.',
@@ -152,7 +151,7 @@ export const updateSessionRoute = createRoute({
export const listSessionsRoute = createRoute({
method: 'get',
path: '/',
- tags: [SESSIONS_TAG],
+ tags: [OpenApiTag.AGENT_SESSIONS],
summary: 'List sessions',
description:
"List the caller's sessions (newest first by default), token-paginated. Results are scoped to the authenticated identity via the session store's `created_by` filter (not a client query param). Optional `agent_id` filters to sessions bound to that named agent. Pass `page_token` to fetch the next page, keeping the other query params constant.",
@@ -177,7 +176,7 @@ export const listSessionsRoute = createRoute({
export const cancelSessionRoute = createRoute({
method: 'post',
path: '/{session_id}/cancel',
- tags: [SESSIONS_TAG],
+ tags: [OpenApiTag.AGENT_SESSIONS],
summary: 'Cancel a running turn in a session',
description: 'Cancel the running last turn for a session. Only the session creator (`created_by`) may cancel.',
'x-fern-sdk-group-name': ['sessions'],
@@ -213,7 +212,7 @@ export const cancelSessionRoute = createRoute({
export const listSessionEventsRoute = createRoute({
method: 'get',
path: '/{session_id}/events',
- tags: [SESSIONS_TAG],
+ tags: [OpenApiTag.AGENT_SESSIONS],
summary: 'List session events',
description:
'List session events as `{ turn_id, event }` across the active turn branch (newest first), including persisted events from a running tip. Each turn contributes turn.created, content events (model.message, tool.call, …), and turn.done when terminal; streaming deltas are not included. Use `page_token` to paginate backward toward older events while retaining the original branch anchor. Only the session creator (`created_by`) may list events.',
diff --git a/packages/trueforge/src/routes/skillRoutes.ts b/packages/trueforge/src/routes/skillRoutes.ts
index 9dbbcb8aa..cd286e496 100644
--- a/packages/trueforge/src/routes/skillRoutes.ts
+++ b/packages/trueforge/src/routes/skillRoutes.ts
@@ -13,14 +13,13 @@ import {
ListSkillsResponseSchema,
PutSkillRequestSchema,
} from '../schemas/skill';
-
-const SKILLS_TAG = 'Skills';
+import { OpenApiTag } from './openapiTags';
/** Chat/composer read view — mounted at /api/v1/skills (not under settings). */
export const listAvailableSkillsRoute = createRoute({
method: 'get',
path: '/',
- tags: [SKILLS_TAG],
+ tags: [OpenApiTag.SKILLS],
summary: 'List skills for chat',
description: 'Configured skills as a slim name/description list for the composer.',
'x-fern-sdk-group-name': ['skills'],
@@ -40,7 +39,7 @@ export const listAvailableSkillsRoute = createRoute({
export const listConfiguredSkillsRoute = createRoute({
method: 'get',
path: '/',
- tags: [SKILLS_TAG],
+ tags: [OpenApiTag.SKILLS],
summary: 'List configured skills',
description: 'All configured skills with nested manifests (settings / admin projection).',
'x-fern-sdk-group-name': ['settings', 'skills'],
@@ -64,7 +63,7 @@ export const listConfiguredSkillsRoute = createRoute({
export const createSkillRoute = createRoute({
method: 'post',
path: '/',
- tags: [SKILLS_TAG],
+ tags: [OpenApiTag.SKILLS],
summary: 'Create a skill',
description: 'Creates a skill keyed by `name`. Fails if `name` is already taken.',
'x-fern-sdk-group-name': ['settings', 'skills'],
@@ -94,7 +93,7 @@ export const createSkillRoute = createRoute({
export const putSkillRoute = createRoute({
method: 'put',
path: '/',
- tags: [SKILLS_TAG],
+ tags: [OpenApiTag.SKILLS],
summary: 'Create or replace a skill',
description: 'Full upsert keyed by `name`: creates the skill or replaces its entire manifest.',
'x-fern-sdk-group-name': ['settings', 'skills'],
diff --git a/packages/trueforge/src/routes/turnRoutes.ts b/packages/trueforge/src/routes/turnRoutes.ts
index 1c2dbf1ae..7bf74ab23 100644
--- a/packages/trueforge/src/routes/turnRoutes.ts
+++ b/packages/trueforge/src/routes/turnRoutes.ts
@@ -17,10 +17,9 @@ import {
SubscribeTurnQuerySchema,
} from '../schemas/turn';
import { TOKEN_PAGINATION } from './fernExtensions';
+import { OpenApiTag } from './openapiTags';
import { SessionIdParamsSchema } from './sessionRoutes';
-const SESSIONS_TAG = 'Sessions';
-
export const TurnIdParamsSchema = SessionIdParamsSchema.extend({
turn_id: z.string().min(1).describe('Turn identifier.'),
});
@@ -28,7 +27,7 @@ export const TurnIdParamsSchema = SessionIdParamsSchema.extend({
export const listTurnsRoute = createRoute({
method: 'get',
path: '/{session_id}/turns',
- tags: [SESSIONS_TAG],
+ tags: [OpenApiTag.AGENT_SESSIONS],
summary: 'List turns in a session',
description:
'List turns for a session (newest first by default), token-paginated. Only the session creator (`created_by`) may list turns.',
@@ -62,7 +61,7 @@ export const listTurnsRoute = createRoute({
export const getTurnRoute = createRoute({
method: 'get',
path: '/{session_id}/turns/{turn_id}',
- tags: [SESSIONS_TAG],
+ tags: [OpenApiTag.AGENT_SESSIONS],
summary: 'Get a turn',
description: 'Fetch a single turn by ID. Only the session creator (`created_by`) may fetch it.',
'x-fern-sdk-group-name': ['sessions'],
@@ -89,7 +88,7 @@ export const getTurnRoute = createRoute({
export const downloadSandboxFileRoute = createRoute({
method: 'get',
path: '/{session_id}/turns/{turn_id}/download-sandbox-file',
- tags: [SESSIONS_TAG],
+ tags: [OpenApiTag.AGENT_SESSIONS],
summary: 'Download a file from the turn sandbox',
description:
"Download a file from the sandbox this turn ran in. Paths come from the assistant's `sandbox_artifacts` block. Only the session creator (`created_by`) may download.",
@@ -138,7 +137,7 @@ export const downloadSandboxFileRoute = createRoute({
export const listTurnEventsRoute = createRoute({
method: 'get',
path: '/{session_id}/turns/{turn_id}/events',
- tags: [SESSIONS_TAG],
+ tags: [OpenApiTag.AGENT_SESSIONS],
summary: 'List turn events',
description:
'Paginated persisted events for a turn (insertion order by default). Only the session creator (`created_by`) may list events.',
@@ -172,7 +171,7 @@ export const listTurnEventsRoute = createRoute({
export const createAndExecuteTurnRoute = createRoute({
method: 'post',
path: '/{session_id}/turns',
- tags: [SESSIONS_TAG],
+ tags: [OpenApiTag.AGENT_SESSIONS],
summary: 'Create and execute a turn in a session',
description: `Create a turn within a session and execute it.
Only the session creator (\`created_by\`) may create turns.
@@ -242,7 +241,7 @@ Use \`previous_turn_id\` to chain to the session's last turn (defaults to \`auto
export const subscribeTurnRoute = createRoute({
method: 'get',
path: '/{session_id}/turns/{turn_id}/subscribe',
- tags: [SESSIONS_TAG],
+ tags: [OpenApiTag.AGENT_SESSIONS],
summary: 'Subscribe to a running turn',
description:
'Subscribe to the live SSE stream for a turn. Only the session creator (`created_by`) may subscribe. Pass `after_sequence_number` to resume after a disconnect (exclusive — events after this sequence number are replayed).',