Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

feat(skills): stabilize API and restore MCP access (#19025)

tobi_kld9b656b00d89
diff --git a/fern/apis/server/definition/unstable/skills.yml b/fern/apis/server/definition/skills.yml
similarity index 98%
rename from fern/apis/server/definition/unstable/skills.yml
rename to fern/apis/server/definition/skills.yml
index 16bce4c874..f7d941d7d2 100644
--- a/fern/apis/server/definition/unstable/skills.yml
+++ b/fern/apis/server/definition/skills.yml
@@ -1,9 +1,9 @@
# yaml-language-server: $schema=https://raw.githubusercontent.com/fern-api/fern/main/fern.schema.json
imports:
- pagination: ../utils/pagination.yml
+ pagination: ./utils/pagination.yml
service:
auth: true
- base-path: /api/public/unstable
+ base-path: /api/public
endpoints:
list:
docs: List skills with metadata and timestamps from their latest version, shared tags, and the version assigned to production when present.
diff --git a/packages/shared/src/in-app-agent/server/mcpPolicy.ts b/packages/shared/src/in-app-agent/server/mcpPolicy.ts
index 50375535bd..562925a3d4 100644
--- a/packages/shared/src/in-app-agent/server/mcpPolicy.ts
+++ b/packages/shared/src/in-app-agent/server/mcpPolicy.ts
@@ -304,6 +304,22 @@ export const IN_APP_AGENT_LANGFUSE_MCP_TOOL_POLICIES = {
approval: "approval",
availability: { scope: "prompts:CUD" },
},
+ listSkills: {
+ approval: "auto",
+ availability: { scope: "skills:read" },
+ },
+ getSkill: {
+ approval: "auto",
+ availability: { scope: "skills:read" },
+ },
+ loadSkill: {
+ approval: "auto",
+ availability: { scope: "skills:read" },
+ },
+ loadSkillResource: {
+ approval: "auto",
+ availability: { scope: "skills:read" },
+ },
listScores: {
approval: "auto",
availability: { scope: "project:read" },
diff --git a/web/public/generated/api/openapi.yml b/web/public/generated/api/openapi.yml
index cc0f8192f9..c4ec07c144 100644
--- a/web/public/generated/api/openapi.yml
+++ b/web/public/generated/api/openapi.yml
@@ -6105,26 +6105,77 @@ paths:
application/json:
schema: {}
security: *ref_0
- /api/public/traces/{traceId}:
- delete:
- description: Delete a specific trace
- operationId: trace_delete
+ /api/public/skills:
+ get:
+ description: >-
+ List skills with metadata and timestamps from their latest version,
+ shared tags, and the version assigned to production when present.
+ operationId: skills_list
tags:
- - Trace
+ - Skills
parameters:
- - name: traceId
- in: path
- description: The unique langfuse identifier of the trace to delete
- required: true
+ - name: name
+ in: query
+ description: Filter by exact skill name.
+ required: false
+ schema:
+ type: string
+ nullable: true
+ - name: search
+ in: query
+ description: >-
+ Case-insensitive search across skill names and latest-version
+ descriptions.
+ required: false
+ schema:
+ type: string
+ nullable: true
+ - name: tag
+ in: query
+ description: Filter by a shared skill tag.
+ required: false
+ schema:
+ type: string
+ nullable: true
+ - name: page
+ in: query
+ required: false
+ schema:
+ type: integer
+ nullable: true
+ - name: limit
+ in: query
+ required: false
+ schema:
+ type: integer
+ nullable: true
+ - name: fromUpdatedAt
+ in: query
+ description: >-
+ Include skills whose latest version was updated at or after this
+ timestamp.
+ required: false
+ schema:
+ type: string
+ format: date-time
+ nullable: true
+ - name: toUpdatedAt
+ in: query
+ description: >-
+ Include skills whose latest version was updated before this
+ timestamp.
+ required: false
schema:
type: string
+ format: date-time
+ nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
- $ref: '#/components/schemas/DeleteTraceResponse'
+ $ref: '#/components/schemas/SkillMetaListResponse'
'400':
description: ''
content:
@@ -6151,20 +6202,19 @@ paths:
application/json:
schema: {}
security: *ref_0
- /api/public/traces:
- delete:
- description: Delete multiple traces
- operationId: trace_deleteMultiple
+ post:
+ description: Create skill version
+ operationId: skills_createVersion
tags:
- - Trace
+ - Skills
parameters: []
responses:
- '200':
+ '201':
description: ''
content:
application/json:
schema:
- $ref: '#/components/schemas/DeleteTraceResponse'
+ $ref: '#/components/schemas/SkillVersion'
'400':
description: ''
content:
@@ -6196,40 +6246,40 @@ paths:
content:
application/json:
schema:
- type: object
- properties:
- traceIds:
- type: array
- items:
- type: string
- description: List of trace IDs to delete
- required:
- - traceIds
- /api/public/unstable/dashboard-widgets:
+ $ref: '#/components/schemas/CreateSkillVersionRequest'
+ /api/public/skills/{skillName}:
get:
- description: |-
- List dashboard widgets in the project, ordered by most recently
- updated first.
-
- Responses may include legacy `traces` widgets created before this
- API existed. New widgets cannot be created with `view: traces`.
- operationId: unstable_dashboardWidgets_list
+ description: >-
+ Resolve a skill's metadata and file manifest by version or label.
+ Defaults to the production label. Set includeContent to return file
+ contents inline, or use each file's sha256Hash with getFileContents.
+ operationId: skills_get
tags:
- - UnstableDashboardWidgets
+ - Skills
parameters:
- - name: page
+ - name: skillName
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: version
in: query
- description: 1-based page number. Defaults to `1`.
required: false
schema:
type: integer
nullable: true
- - name: limit
+ - name: label
in: query
- description: Maximum number of items per page. Defaults to `50`.
required: false
schema:
- type: integer
+ type: string
+ nullable: true
+ - name: includeContent
+ in: query
+ description: Include UTF-8 text content in each file. Defaults to false.
+ required: false
+ schema:
+ type: boolean
nullable: true
responses:
'200':
@@ -6237,7 +6287,7 @@ paths:
content:
application/json:
schema:
- $ref: '#/components/schemas/unstableDashboardWidgetList'
+ $ref: '#/components/schemas/SkillVersion'
'400':
description: ''
content:
@@ -6263,61 +6313,28 @@ paths:
content:
application/json:
schema: {}
- '429':
- description: ''
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/unstablePublicApiError'
- '500':
- description: ''
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/unstablePublicApiError'
security: *ref_0
- post:
+ patch:
description: >-
- Create a dashboard widget (a standalone chart definition you place on
-
- any dashboard).
-
-
- This endpoint creates the widget only; place it on a dashboard via
-
- `POST /dashboards/{dashboardId}/placements`.
-
-
- Supported views are `observations`, `scores-numeric`, `scores-boolean`,
- and `scores-categorical`.
-
- The legacy `traces` view is not supported by this unstable API.
-
- Widgets are created as v2 internally.
-
-
- `chartConfig` is optional and defaults to the plain config for
-
- `chartType`; when `chartConfig.type` is given it must match
-
- `chartType`.
-
-
- Unstable API note:
-
- - This surface may evolve while dashboard/widget APIs are being
- finalized.
- operationId: unstable_dashboardWidgets_create
+ Replace the shared tags across all versions of a skill. An empty tags
+ list clears all tags. Returns the latest skill version with the updated
+ tags.
+ operationId: skills_update
tags:
- - UnstableDashboardWidgets
- parameters: []
+ - Skills
+ parameters:
+ - name: skillName
+ in: path
+ required: true
+ schema:
+ type: string
responses:
'200':
description: ''
content:
application/json:
schema:
- $ref: '#/components/schemas/unstableDashboardWidget'
+ $ref: '#/components/schemas/SkillVersion'
'400':
description: ''
content:
@@ -6343,37 +6360,27 @@ paths:
content:
application/json:
schema: {}
- '429':
- description: ''
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/unstablePublicApiError'
- '500':
- description: ''
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/unstablePublicApiError'
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
- $ref: '#/components/schemas/unstableCreateDashboardWidgetRequest'
- /api/public/unstable/dashboard-widgets/{widgetId}:
+ $ref: '#/components/schemas/UpdateSkillRequest'
+ /api/public/skills/files/content:
get:
- description: |-
- Get a dashboard widget by id.
-
- The response may use `view: traces` for legacy widgets.
- operationId: unstable_dashboardWidgets_get
+ description: >-
+ Read a batch of text contents by canonical base64-encoded SHA-256 hashes.
+ operationId: skills_getFileContents
tags:
- - UnstableDashboardWidgets
+ - Skills
parameters:
- - name: widgetId
- in: path
+ - name: sha256Hashes
+ in: query
+ description: >-
+ Comma-separated list of one to 50 canonical base64-encoded SHA-256
+ hashes from skill file manifests. URL-encode the value, including +,
+ /, and = characters.
required: true
schema:
type: string
@@ -6383,7 +6390,7 @@ paths:
content:
application/json:
schema:
- $ref: '#/components/schemas/unstableDashboardWidget'
+ $ref: '#/components/schemas/SkillFileContentsResponse'
'400':
description: ''
content:
@@ -6409,46 +6416,33 @@ paths:
content:
application/json:
schema: {}
- '429':
- description: ''
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/unstablePublicApiError'
- '500':
- description: ''
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/unstablePublicApiError'
security: *ref_0
+ /api/public/skills/{skillName}/versions/{skillVersion}:
patch:
- description: |-
- Update a dashboard widget.
-
- All fields are optional; at least one field is required.
- Changing `chartType` without sending `chartConfig` resets the config
- to the new chart type's defaults. When `chartConfig.type` is given
- it must match the widget's (possibly updated) `chartType`.
-
- `view` cannot be changed to the legacy `traces` value. Existing
- `traces` widgets may be updated on other fields.
- operationId: unstable_dashboardWidgets_update
+ description: >-
+ Replace the labels on a skill version and atomically move them from
+ other versions.
+ operationId: skills_setLabels
tags:
- - UnstableDashboardWidgets
+ - Skills
parameters:
- - name: widgetId
+ - name: skillName
in: path
required: true
schema:
type: string
+ - name: skillVersion
+ in: path
+ required: true
+ schema:
+ type: integer
responses:
'200':
description: ''
content:
application/json:
schema:
- $ref: '#/components/schemas/unstableDashboardWidget'
+ $ref: '#/components/schemas/SkillVersion'
'400':
description: ''
content:
@@ -6474,121 +6468,38 @@ paths:
content:
application/json:
schema: {}
- '429':
- description: ''
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/unstablePublicApiError'
- '500':
- description: ''
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/unstablePublicApiError'
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
- $ref: '#/components/schemas/unstableUpdateDashboardWidgetRequest'
+ $ref: '#/components/schemas/UpdateSkillLabelsRequest'
delete:
- description: |-
- Delete a dashboard widget.
-
- The API returns `409` while the widget is still placed on a dashboard.
- Remove those placements first.
- operationId: unstable_dashboardWidgets_delete
+ description: >-
+ Delete one immutable skill version. Unreferenced blobs are retained for
+ asynchronous cleanup.
+ operationId: skills_deleteVersion
tags:
- - UnstableDashboardWidgets
+ - Skills
parameters:
- - name: widgetId
+ - name: skillName
in: path
- required: true
- schema:
- type: string
- responses:
- '200':
- description: ''
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/unstableDeleteDashboardWidgetResponse'
- '400':
- description: ''
- content:
- application/json:
- schema: {}
- '401':
- description: ''
- content:
- application/json:
- schema: {}
- '403':
- description: ''
- content:
- application/json:
- schema: {}
- '404':
- description: ''
- content:
- application/json:
- schema: {}
- '405':
- description: ''
- content:
- application/json:
- schema: {}
- '409':
- description: ''
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/unstablePublicApiError'
- '429':
- description: ''
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/unstablePublicApiError'
- '500':
- description: ''
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/unstablePublicApiError'
- security: *ref_0
- /api/public/unstable/dashboards:
- get:
- description: |-
- List dashboards in the project, ordered by most recently updated
- first.
- operationId: unstable_dashboards_list
- tags:
- - UnstableDashboards
- parameters:
- - name: page
- in: query
- description: 1-based page number. Defaults to `1`.
- required: false
+ required: true
schema:
- type: integer
- nullable: true
- - name: limit
- in: query
- description: Maximum number of items per page. Defaults to `50`.
- required: false
+ type: string
+ - name: skillVersion
+ in: path
+ required: true
schema:
type: integer
- nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
- $ref: '#/components/schemas/unstableDashboardList'
+ $ref: '#/components/schemas/DeleteSkillVersionResponse'
'400':
description: ''
content:
@@ -6614,32 +6525,27 @@ paths:
content:
application/json:
schema: {}
- '429':
- description: ''
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/unstablePublicApiError'
- '500':
- description: ''
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/unstablePublicApiError'
security: *ref_0
- post:
- description: Create a dashboard.
- operationId: unstable_dashboards_create
+ /api/public/traces/{traceId}:
+ delete:
+ description: Delete a specific trace
+ operationId: trace_delete
tags:
- - UnstableDashboards
- parameters: []
+ - Trace
+ parameters:
+ - name: traceId
+ in: path
+ description: The unique langfuse identifier of the trace to delete
+ required: true
+ schema:
+ type: string
responses:
'200':
description: ''
content:
application/json:
schema:
- $ref: '#/components/schemas/unstableDashboard'
+ $ref: '#/components/schemas/DeleteTraceResponse'
'400':
description: ''
content:
@@ -6665,44 +6571,21 @@ paths:
content:
application/json:
schema: {}
- '429':
- description: ''
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/unstablePublicApiError'
- '500':
- description: ''
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/unstablePublicApiError'
security: *ref_0
- requestBody:
- required: true
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/unstableCreateDashboardRequest'
- /api/public/unstable/dashboards/{dashboardId}:
- get:
- description: Get a dashboard by id.
- operationId: unstable_dashboards_get
+ /api/public/traces:
+ delete:
+ description: Delete multiple traces
+ operationId: trace_deleteMultiple
tags:
- - UnstableDashboards
- parameters:
- - name: dashboardId
- in: path
- required: true
- schema:
- type: string
+ - Trace
+ parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
- $ref: '#/components/schemas/unstableDashboard'
+ $ref: '#/components/schemas/DeleteTraceResponse'
'400':
description: ''
content:
@@ -6728,37 +6611,54 @@ paths:
content:
application/json:
schema: {}
- '429':
- description: ''
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/unstablePublicApiError'
- '500':
- description: ''
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/unstablePublicApiError'
security: *ref_0
- patch:
- description: Update a dashboard's name, description, definition, or filters.
- operationId: unstable_dashboards_update
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ traceIds:
+ type: array
+ items:
+ type: string
+ description: List of trace IDs to delete
+ required:
+ - traceIds
+ /api/public/unstable/dashboard-widgets:
+ get:
+ description: |-
+ List dashboard widgets in the project, ordered by most recently
+ updated first.
+
+ Responses may include legacy `traces` widgets created before this
+ API existed. New widgets cannot be created with `view: traces`.
+ operationId: unstable_dashboardWidgets_list
tags:
- - UnstableDashboards
+ - UnstableDashboardWidgets
parameters:
- - name: dashboardId
- in: path
- required: true
+ - name: page
+ in: query
+ description: 1-based page number. Defaults to `1`.
+ required: false
schema:
- type: string
+ type: integer
+ nullable: true
+ - name: limit
+ in: query
+ description: Maximum number of items per page. Defaults to `50`.
+ required: false
+ schema:
+ type: integer
+ nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
- $ref: '#/components/schemas/unstableDashboard'
+ $ref: '#/components/schemas/unstableDashboardWidgetList'
'400':
description: ''
content:
@@ -6797,30 +6697,48 @@ paths:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
security: *ref_0
- requestBody:
- required: true
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/unstableUpdateDashboardRequest'
- delete:
- description: Delete a dashboard.
- operationId: unstable_dashboards_delete
+ post:
+ description: >-
+ Create a dashboard widget (a standalone chart definition you place on
+
+ any dashboard).
+
+
+ This endpoint creates the widget only; place it on a dashboard via
+
+ `POST /dashboards/{dashboardId}/placements`.
+
+
+ Supported views are `observations`, `scores-numeric`, `scores-boolean`,
+ and `scores-categorical`.
+
+ The legacy `traces` view is not supported by this unstable API.
+
+ Widgets are created as v2 internally.
+
+
+ `chartConfig` is optional and defaults to the plain config for
+
+ `chartType`; when `chartConfig.type` is given it must match
+
+ `chartType`.
+
+
+ Unstable API note:
+
+ - This surface may evolve while dashboard/widget APIs are being
+ finalized.
+ operationId: unstable_dashboardWidgets_create
tags:
- - UnstableDashboards
- parameters:
- - name: dashboardId
- in: path
- required: true
- schema:
- type: string
+ - UnstableDashboardWidgets
+ parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
- $ref: '#/components/schemas/unstableDeleteDashboardResponse'
+ $ref: '#/components/schemas/unstableDashboardWidget'
'400':
description: ''
content:
@@ -6859,24 +6777,23 @@ paths:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
security: *ref_0
- /api/public/unstable/dashboards/{dashboardId}/placements:
- post:
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/unstableCreateDashboardWidgetRequest'
+ /api/public/unstable/dashboard-widgets/{widgetId}:
+ get:
description: |-
- Add a placement to a dashboard grid (see `DashboardPlacement` for
- grid semantics).
-
- `id` and the position fields are optional: when omitted, the
- placement gets a server-generated id and is appended below all
- existing tiles as a 6x6 tile. Returns the created placement.
+ Get a dashboard widget by id.
- The referenced widget must exist in the same project or be a
- Langfuse-managed widget. The API returns `409` if a placement with
- the same `id` already exists on the dashboard.
- operationId: unstable_dashboards_addPlacement
+ The response may use `view: traces` for legacy widgets.
+ operationId: unstable_dashboardWidgets_get
tags:
- - UnstableDashboards
+ - UnstableDashboardWidgets
parameters:
- - name: dashboardId
+ - name: widgetId
in: path
required: true
schema:
@@ -6887,7 +6804,7 @@ paths:
content:
application/json:
schema:
- $ref: '#/components/schemas/unstableDashboardPlacement'
+ $ref: '#/components/schemas/unstableDashboardWidget'
'400':
description: ''
content:
@@ -6913,12 +6830,6 @@ paths:
content:
application/json:
schema: {}
- '409':
- description: ''
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/unstablePublicApiError'
'429':
description: ''
content:
@@ -6932,29 +6843,22 @@ paths:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
security: *ref_0
- requestBody:
- required: true
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/unstableCreateDashboardPlacementRequest'
- /api/public/unstable/dashboards/{dashboardId}/placements/{placementId}:
patch:
description: |-
- Move or resize a placement. All fields are optional; at least one is
- required. Omitted fields keep their current value. The placement's
- content (widget/preset reference) and id cannot change — delete and
- re-add the placement to swap content. Returns the updated placement.
- operationId: unstable_dashboards_updatePlacement
- tags:
- - UnstableDashboards
- parameters:
- - name: dashboardId
- in: path
- required: true
- schema:
- type: string
- - name: placementId
+ Update a dashboard widget.
+
+ All fields are optional; at least one field is required.
+ Changing `chartType` without sending `chartConfig` resets the config
+ to the new chart type's defaults. When `chartConfig.type` is given
+ it must match the widget's (possibly updated) `chartType`.
+
+ `view` cannot be changed to the legacy `traces` value. Existing
+ `traces` widgets may be updated on other fields.
+ operationId: unstable_dashboardWidgets_update
+ tags:
+ - UnstableDashboardWidgets
+ parameters:
+ - name: widgetId
in: path
required: true
schema:
@@ -6965,7 +6869,7 @@ paths:
content:
application/json:
schema:
- $ref: '#/components/schemas/unstableDashboardPlacement'
+ $ref: '#/components/schemas/unstableDashboardWidget'
'400':
description: ''
content:
@@ -7009,21 +6913,18 @@ paths:
content:
application/json:
schema:
- $ref: '#/components/schemas/unstableUpdateDashboardPlacementRequest'
+ $ref: '#/components/schemas/unstableUpdateDashboardWidgetRequest'
delete:
- description: >-
- Remove a placement from a dashboard grid without deleting the referenced
- widget.
- operationId: unstable_dashboards_deletePlacement
+ description: |-
+ Delete a dashboard widget.
+
+ The API returns `409` while the widget is still placed on a dashboard.
+ Remove those placements first.
+ operationId: unstable_dashboardWidgets_delete
tags:
- - UnstableDashboards
+ - UnstableDashboardWidgets
parameters:
- - name: dashboardId
- in: path
- required: true
- schema:
- type: string
- - name: placementId
+ - name: widgetId
in: path
required: true
schema:
@@ -7034,7 +6935,7 @@ paths:
content:
application/json:
schema:
- $ref: '#/components/schemas/unstableDeleteDashboardPlacementResponse'
+ $ref: '#/components/schemas/unstableDeleteDashboardWidgetResponse'
'400':
description: ''
content:
@@ -7060,6 +6961,12 @@ paths:
content:
application/json:
schema: {}
+ '409':
+ description: ''
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/unstablePublicApiError'
'429':
description: ''
content:
@@ -7073,77 +6980,36 @@ paths:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
security: *ref_0
- /api/public/unstable/skills:
+ /api/public/unstable/dashboards:
get:
- description: >-
- List skills with metadata and timestamps from their latest version,
- shared tags, and the version assigned to production when present.
- operationId: unstable_skills_list
+ description: |-
+ List dashboards in the project, ordered by most recently updated
+ first.
+ operationId: unstable_dashboards_list
tags:
- - UnstableSkills
+ - UnstableDashboards
parameters:
- - name: name
- in: query
- description: Filter by exact skill name.
- required: false
- schema:
- type: string
- nullable: true
- - name: search
- in: query
- description: >-
- Case-insensitive search across skill names and latest-version
- descriptions.
- required: false
- schema:
- type: string
- nullable: true
- - name: tag
- in: query
- description: Filter by a shared skill tag.
- required: false
- schema:
- type: string
- nullable: true
- name: page
in: query
+ description: 1-based page number. Defaults to `1`.
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
+ description: Maximum number of items per page. Defaults to `50`.
required: false
schema:
type: integer
nullable: true
- - name: fromUpdatedAt
- in: query
- description: >-
- Include skills whose latest version was updated at or after this
- timestamp.
- required: false
- schema:
- type: string
- format: date-time
- nullable: true
- - name: toUpdatedAt
- in: query
- description: >-
- Include skills whose latest version was updated before this
- timestamp.
- required: false
- schema:
- type: string
- format: date-time
- nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
- $ref: '#/components/schemas/unstableSkillMetaListResponse'
+ $ref: '#/components/schemas/unstableDashboardList'
'400':
description: ''
content:
@@ -7169,20 +7035,32 @@ paths:
content:
application/json:
schema: {}
+ '429':
+ description: ''
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/unstablePublicApiError'
+ '500':
+ description: ''
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/unstablePublicApiError'
security: *ref_0
post:
- description: Create skill version
- operationId: unstable_skills_createVersion
+ description: Create a dashboard.
+ operationId: unstable_dashboards_create
tags:
- - UnstableSkills
+ - UnstableDashboards
parameters: []
responses:
- '201':
+ '200':
description: ''
content:
application/json:
schema:
- $ref: '#/components/schemas/unstableSkillVersion'
+ $ref: '#/components/schemas/unstableDashboard'
'400':
description: ''
content:
@@ -7208,54 +7086,44 @@ paths:
content:
application/json:
schema: {}
+ '429':
+ description: ''
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/unstablePublicApiError'
+ '500':
+ description: ''
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/unstablePublicApiError'
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
- $ref: '#/components/schemas/unstableCreateSkillVersionRequest'
- /api/public/unstable/skills/{skillName}:
+ $ref: '#/components/schemas/unstableCreateDashboardRequest'
+ /api/public/unstable/dashboards/{dashboardId}:
get:
- description: >-
- Resolve a skill's metadata and file manifest by version or label.
- Defaults to the production label. Set includeContent to return file
- contents inline, or use each file's sha256Hash with getFileContents.
- operationId: unstable_skills_get
+ description: Get a dashboard by id.
+ operationId: unstable_dashboards_get
tags:
- - UnstableSkills
+ - UnstableDashboards
parameters:
- - name: skillName
+ - name: dashboardId
in: path
required: true
schema:
type: string
- - name: version
- in: query
- required: false
- schema:
- type: integer
- nullable: true
- - name: label
- in: query
- required: false
- schema:
- type: string
- nullable: true
- - name: includeContent
- in: query
- description: Include UTF-8 text content in each file. Defaults to false.
- required: false
- schema:
- type: boolean
- nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
- $ref: '#/components/schemas/unstableSkillVersion'
+ $ref: '#/components/schemas/unstableDashboard'
'400':
description: ''
content:
@@ -7281,17 +7149,26 @@ paths:
content:
application/json:
schema: {}
+ '429':
+ description: ''
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/unstablePublicApiError'
+ '500':
+ description: ''
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/unstablePublicApiError'
security: *ref_0
patch:
- description: >-
- Replace the shared tags across all versions of a skill. An empty tags
- list clears all tags. Returns the latest skill version with the updated
- tags.
- operationId: unstable_skills_update
+ description: Update a dashboard's name, description, definition, or filters.
+ operationId: unstable_dashboards_update
tags:
- - UnstableSkills
+ - UnstableDashboards
parameters:
- - name: skillName
+ - name: dashboardId
in: path
required: true
schema:
@@ -7302,7 +7179,7 @@ paths:
content:
application/json:
schema:
- $ref: '#/components/schemas/unstableSkillVersion'
+ $ref: '#/components/schemas/unstableDashboard'
'400':
description: ''
content:
@@ -7328,27 +7205,100 @@ paths:
content:
application/json:
schema: {}
+ '429':
+ description: ''
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/unstablePublicApiError'
+ '500':
+ description: ''
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/unstablePublicApiError'
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
- $ref: '#/components/schemas/unstableUpdateSkillRequest'
- /api/public/unstable/skills/files/content:
- get:
- description: >-
- Read a batch of text contents by canonical base64-encoded SHA-256 hashes.
- operationId: unstable_skills_getFileContents
+ $ref: '#/components/schemas/unstableUpdateDashboardRequest'
+ delete:
+ description: Delete a dashboard.
+ operationId: unstable_dashboards_delete
+ tags:
+ - UnstableDashboards
+ parameters:
+ - name: dashboardId
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: ''
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/unstableDeleteDashboardResponse'
+ '400':
+ description: ''
+ content:
+ application/json:
+ schema: {}
+ '401':
+ description: ''
+ content:
+ application/json:
+ schema: {}
+ '403':
+ description: ''
+ content:
+ application/json:
+ schema: {}
+ '404':
+ description: ''
+ content:
+ application/json:
+ schema: {}
+ '405':
+ description: ''
+ content:
+ application/json:
+ schema: {}
+ '429':
+ description: ''
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/unstablePublicApiError'
+ '500':
+ description: ''
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/unstablePublicApiError'
+ security: *ref_0
+ /api/public/unstable/dashboards/{dashboardId}/placements:
+ post:
+ description: |-
+ Add a placement to a dashboard grid (see `DashboardPlacement` for
+ grid semantics).
+
+ `id` and the position fields are optional: when omitted, the
+ placement gets a server-generated id and is appended below all
+ existing tiles as a 6x6 tile. Returns the created placement.
+
+ The referenced widget must exist in the same project or be a
+ Langfuse-managed widget. The API returns `409` if a placement with
+ the same `id` already exists on the dashboard.
+ operationId: unstable_dashboards_addPlacement
tags:
- - UnstableSkills
+ - UnstableDashboards
parameters:
- - name: sha256Hashes
- in: query
- description: >-
- Comma-separated list of one to 50 canonical base64-encoded SHA-256
- hashes from skill file manifests. URL-encode the value, including +,
- /, and = characters.
+ - name: dashboardId
+ in: path
required: true
schema:
type: string
@@ -7358,7 +7308,7 @@ paths:
content:
application/json:
schema:
- $ref: '#/components/schemas/unstableSkillFileContentsResponse'
+ $ref: '#/components/schemas/unstableDashboardPlacement'
'400':
description: ''
content:
@@ -7384,33 +7334,59 @@ paths:
content:
application/json:
schema: {}
+ '409':
+ description: ''
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/unstablePublicApiError'
+ '429':
+ description: ''
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/unstablePublicApiError'
+ '500':
+ description: ''
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/unstablePublicApiError'
security: *ref_0
- /api/public/unstable/skills/{skillName}/versions/{skillVersion}:
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/unstableCreateDashboardPlacementRequest'
+ /api/public/unstable/dashboards/{dashboardId}/placements/{placementId}:
patch:
- description: >-
- Replace the labels on a skill version and atomically move them from
- other versions.
- operationId: unstable_skills_setLabels
+ description: |-
+ Move or resize a placement. All fields are optional; at least one is
+ required. Omitted fields keep their current value. The placement's
+ content (widget/preset reference) and id cannot change — delete and
+ re-add the placement to swap content. Returns the updated placement.
+ operationId: unstable_dashboards_updatePlacement
tags:
- - UnstableSkills
+ - UnstableDashboards
parameters:
- - name: skillName
+ - name: dashboardId
in: path
required: true
schema:
type: string
- - name: skillVersion
+ - name: placementId
in: path
required: true
schema:
- type: integer
+ type: string
responses:
'200':
description: ''
content:
application/json:
schema:
- $ref: '#/components/schemas/unstableSkillVersion'
+ $ref: '#/components/schemas/unstableDashboardPlacement'
'400':
description: ''
content:
@@ -7436,38 +7412,50 @@ paths:
content:
application/json:
schema: {}
+ '429':
+ description: ''
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/unstablePublicApiError'
+ '500':
+ description: ''
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/unstablePublicApiError'
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
- $ref: '#/components/schemas/unstableUpdateSkillLabelsRequest'
+ $ref: '#/components/schemas/unstableUpdateDashboardPlacementRequest'
delete:
description: >-
- Delete one immutable skill version. Unreferenced blobs are retained for
- asynchronous cleanup.
- operationId: unstable_skills_deleteVersion
+ Remove a placement from a dashboard grid without deleting the referenced
+ widget.
+ operationId: unstable_dashboards_deletePlacement
tags:
- - UnstableSkills
+ - UnstableDashboards
parameters:
- - name: skillName
+ - name: dashboardId
in: path
required: true
schema:
type: string
- - name: skillVersion
+ - name: placementId
in: path
required: true
schema:
- type: integer
+ type: string
responses:
'200':
description: ''
content:
application/json:
schema:
- $ref: '#/components/schemas/unstableDeleteSkillVersionResponse'
+ $ref: '#/components/schemas/unstableDeleteDashboardPlacementResponse'
'400':
description: ''
content:
@@ -7493,6 +7481,18 @@ paths:
content:
application/json:
schema: {}
+ '429':
+ description: ''
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/unstablePublicApiError'
+ '500':
+ description: ''
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/unstablePublicApiError'
security: *ref_0
components:
schemas:
@@ -13801,15 +13801,251 @@ components:
configId:
type: string
nullable: true
- description: >-
- Reference a score config on a score. When set, the score name must
- equal the config name and scores must comply with the config's range
- and data type. For categorical scores, the value must map to a
- config category. Numeric scores might be constrained by the score
- config's max and min values
+ description: >-
+ Reference a score config on a score. When set, the score name must
+ equal the config name and scores must comply with the config's range
+ and data type. For categorical scores, the value must map to a
+ config category. Numeric scores might be constrained by the score
+ config's max and min values
+ required:
+ - name
+ - value
+ SkillMetaListResponse:
+ title: SkillMetaListResponse
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ $ref: '#/components/schemas/SkillMeta'
+ meta:
+ $ref: '#/components/schemas/SkillListPagination'
+ required:
+ - data
+ - meta
+ SkillListPagination:
+ title: SkillListPagination
+ type: object
+ properties:
+ hasNextPage:
+ type: boolean
+ required:
+ - hasNextPage
+ allOf:
+ - $ref: '#/components/schemas/utilsMetaResponse'
+ SkillMeta:
+ title: SkillMeta
+ type: object
+ properties:
+ name:
+ type: string
+ description:
+ type: string
+ tags:
+ type: array
+ items:
+ type: string
+ latestVersion:
+ type: integer
+ latestVersionCreatedAt:
+ type: string
+ format: date-time
+ latestVersionLastUpdatedAt:
+ type: string
+ format: date-time
+ productionVersion:
+ type: integer
+ nullable: true
+ description: >-
+ Version assigned the production label, or null when no version is
+ assigned.
+ required:
+ - name
+ - description
+ - tags
+ - latestVersion
+ - latestVersionCreatedAt
+ - latestVersionLastUpdatedAt
+ - productionVersion
+ SkillVersionFileInput:
+ title: SkillVersionFileInput
+ type: object
+ properties:
+ path:
+ type: string
+ content:
+ type: string
+ description: UTF-8 text content. The server computes the hash and byte length.
+ required:
+ - path
+ - content
+ SkillVersionFileReference:
+ title: SkillVersionFileReference
+ type: object
+ properties:
+ path:
+ type: string
+ sha256Hash:
+ type: string
+ description: >-
+ Canonical base64-encoded SHA-256 from a skill file manifest. The
+ content must already exist in this project.
+ required:
+ - path
+ - sha256Hash
+ SkillVersionFileCreateInput:
+ title: SkillVersionFileCreateInput
+ oneOf:
+ - $ref: '#/components/schemas/SkillVersionFileInput'
+ - $ref: '#/components/schemas/SkillVersionFileReference'
+ description: Provide exactly one of content or sha256Hash for each path.
+ CreateSkillVersionRequest:
+ title: CreateSkillVersionRequest
+ type: object
+ properties:
+ files:
+ type: array
+ items:
+ $ref: '#/components/schemas/SkillVersionFileCreateInput'
+ commitMessage:
+ type: string
+ nullable: true
+ required:
+ - files
+ SkillFile:
+ title: SkillFile
+ type: object
+ properties:
+ id:
+ type: string
+ path:
+ type: string
+ blobId:
+ type: string
+ sha256Hash:
+ type: string
+ contentType:
+ type: string
+ contentLength:
+ type: integer
+ format: int64
+ content:
+ type: string
+ nullable: true
+ description: >-
+ UTF-8 text content, included when fetching a skill with
+ includeContent enabled.
+ required:
+ - id
+ - path
+ - blobId
+ - sha256Hash
+ - contentType
+ - contentLength
+ SkillFileContentsResponse:
+ title: SkillFileContentsResponse
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ $ref: '#/components/schemas/SkillFileContent'
+ required:
+ - data
+ SkillFileContent:
+ title: SkillFileContent
+ type: object
+ properties:
+ sha256Hash:
+ type: string
+ content:
+ type: string
+ required:
+ - sha256Hash
+ - content
+ SkillVersion:
+ title: SkillVersion
+ type: object
+ properties:
+ id:
+ type: string
+ createdAt:
+ type: string
+ format: date-time
+ updatedAt:
+ type: string
+ format: date-time
+ projectId:
+ type: string
+ createdBy:
+ type: string
+ name:
+ type: string
+ description:
+ type: string
+ frontmatter: {}
+ version:
+ type: integer
+ tags:
+ type: array
+ items:
+ type: string
+ labels:
+ type: array
+ items:
+ type: string
+ commitMessage:
+ type: string
+ nullable: true
+ files:
+ type: array
+ items:
+ $ref: '#/components/schemas/SkillFile'
required:
+ - id
+ - createdAt
+ - updatedAt
+ - projectId
+ - createdBy
- name
- - value
+ - description
+ - frontmatter
+ - version
+ - tags
+ - labels
+ - commitMessage
+ - files
+ UpdateSkillRequest:
+ title: UpdateSkillRequest
+ type: object
+ properties:
+ tags:
+ type: array
+ items:
+ type: string
+ description: >-
+ The complete set of tags to apply to every version of the skill.
+ Pass an empty list to clear all tags.
+ required:
+ - tags
+ UpdateSkillLabelsRequest:
+ title: UpdateSkillLabelsRequest
+ type: object
+ properties:
+ labels:
+ type: array
+ items:
+ type: string
+ required:
+ - labels
+ DeleteSkillVersionResponse:
+ title: DeleteSkillVersionResponse
+ type: object
+ properties:
+ deleted:
+ type: boolean
+ required:
+ - deleted
DeleteTraceResponse:
title: DeleteTraceResponse
type: object
@@ -14525,242 +14761,6 @@ components:
required:
- message
- code
- unstableSkillMetaListResponse:
- title: unstableSkillMetaListResponse
- type: object
- properties:
- data:
- type: array
- items:
- $ref: '#/components/schemas/unstableSkillMeta'
- meta:
- $ref: '#/components/schemas/unstableSkillListPagination'
- required:
- - data
- - meta
- unstableSkillListPagination:
- title: unstableSkillListPagination
- type: object
- properties:
- hasNextPage:
- type: boolean
- required:
- - hasNextPage
- allOf:
- - $ref: '#/components/schemas/utilsMetaResponse'
- unstableSkillMeta:
- title: unstableSkillMeta
- type: object
- properties:
- name:
- type: string
- description:
- type: string
- tags:
- type: array
- items:
- type: string
- latestVersion:
- type: integer
- latestVersionCreatedAt:
- type: string
- format: date-time
- latestVersionLastUpdatedAt:
- type: string
- format: date-time
- productionVersion:
- type: integer
- nullable: true
- description: >-
- Version assigned the production label, or null when no version is
- assigned.
- required:
- - name
- - description
- - tags
- - latestVersion
- - latestVersionCreatedAt
- - latestVersionLastUpdatedAt
- - productionVersion
- unstableSkillVersionFileInput:
- title: unstableSkillVersionFileInput
- type: object
- properties:
- path:
- type: string
- content:
- type: string
- description: UTF-8 text content. The server computes the hash and byte length.
- required:
- - path
- - content
- unstableSkillVersionFileReference:
- title: unstableSkillVersionFileReference
- type: object
- properties:
- path:
- type: string
- sha256Hash:
- type: string
- description: >-
- Canonical base64-encoded SHA-256 from a skill file manifest. The
- content must already exist in this project.
- required:
- - path
- - sha256Hash
- unstableSkillVersionFileCreateInput:
- title: unstableSkillVersionFileCreateInput
- oneOf:
- - $ref: '#/components/schemas/unstableSkillVersionFileInput'
- - $ref: '#/components/schemas/unstableSkillVersionFileReference'
- description: Provide exactly one of content or sha256Hash for each path.
- unstableCreateSkillVersionRequest:
- title: unstableCreateSkillVersionRequest
- type: object
- properties:
- files:
- type: array
- items:
- $ref: '#/components/schemas/unstableSkillVersionFileCreateInput'
- commitMessage:
- type: string
- nullable: true
- required:
- - files
- unstableSkillFile:
- title: unstableSkillFile
- type: object
- properties:
- id:
- type: string
- path:
- type: string
- blobId:
- type: string
- sha256Hash:
- type: string
- contentType:
- type: string
- contentLength:
- type: integer
- format: int64
- content:
- type: string
- nullable: true
- description: >-
- UTF-8 text content, included when fetching a skill with
- includeContent enabled.
- required:
- - id
- - path
- - blobId
- - sha256Hash
- - contentType
- - contentLength
- unstableSkillFileContentsResponse:
- title: unstableSkillFileContentsResponse
- type: object
- properties:
- data:
- type: array
- items:
- $ref: '#/components/schemas/unstableSkillFileContent'
- required:
- - data
- unstableSkillFileContent:
- title: unstableSkillFileContent
- type: object
- properties:
- sha256Hash:
- type: string
- content:
- type: string
- required:
- - sha256Hash
- - content
- unstableSkillVersion:
- title: unstableSkillVersion
- type: object
- properties:
- id:
- type: string
- createdAt:
- type: string
- format: date-time
- updatedAt:
- type: string
- format: date-time
- projectId:
- type: string
- createdBy:
- type: string
- name:
- type: string
- description:
- type: string
- frontmatter: {}
- version:
- type: integer
- tags:
- type: array
- items:
- type: string
- labels:
- type: array
- items:
- type: string
- commitMessage:
- type: string
- nullable: true
- files:
- type: array
- items:
- $ref: '#/components/schemas/unstableSkillFile'
- required:
- - id
- - createdAt
- - updatedAt
- - projectId
- - createdBy
- - name
- - description
- - frontmatter
- - version
- - tags
- - labels
- - commitMessage
- - files
- unstableUpdateSkillRequest:
- title: unstableUpdateSkillRequest
- type: object
- properties:
- tags:
- type: array
- items:
- type: string
- description: >-
- The complete set of tags to apply to every version of the skill.
- Pass an empty list to clear all tags.
- required:
- - tags
- unstableUpdateSkillLabelsRequest:
- title: unstableUpdateSkillLabelsRequest
- type: object
- properties:
- labels:
- type: array
- items:
- type: string
- required:
- - labels
- unstableDeleteSkillVersionResponse:
- title: unstableDeleteSkillVersionResponse
- type: object
- properties:
- deleted:
- type: boolean
- required:
- - deleted
utilsMetaResponse:
title: utilsMetaResponse
type: object
diff --git a/web/src/__tests__/server/__snapshots__/public-api-auth-parity.servertest.ts.snap b/web/src/__tests__/server/__snapshots__/public-api-auth-parity.servertest.ts.snap
index bcda97cd04..c12eb89211 100644
--- a/web/src/__tests__/server/__snapshots__/public-api-auth-parity.servertest.ts.snap
+++ b/web/src/__tests__/server/__snapshots__/public-api-auth-parity.servertest.ts.snap
@@ -100,6 +100,13 @@ exports[`public-api auth parity > legacy matches the captured baseline except do
"DELETE scores/[scoreId] | org/bearer": 401,
"DELETE scores/[scoreId] | project/basic": 202,
"DELETE scores/[scoreId] | project/bearer": 403,
+ "DELETE skills/[skillName]/versions/[skillVersion] | admin/admin": 401,
+ "DELETE skills/[skillName]/versions/[skillVersion] | agent/basic": 401,
+ "DELETE skills/[skillName]/versions/[skillVersion] | agent/bearer": 401,
+ "DELETE skills/[skillName]/versions/[skillVersion] | org/basic": 403,
+ "DELETE skills/[skillName]/versions/[skillVersion] | org/bearer": 401,
+ "DELETE skills/[skillName]/versions/[skillVersion] | project/basic": 400,
+ "DELETE skills/[skillName]/versions/[skillVersion] | project/bearer": 403,
"DELETE traces/[traceId] | admin/admin": 401,
"DELETE traces/[traceId] | agent/basic": 401,
"DELETE traces/[traceId] | agent/bearer": 401,
@@ -471,6 +478,27 @@ exports[`public-api auth parity > legacy matches the captured baseline except do
"GET sessions/index | org/bearer": 401,
"GET sessions/index | project/basic": 200,
"GET sessions/index | project/bearer": 403,
+ "GET skills/[skillName]/index | admin/admin": 401,
+ "GET skills/[skillName]/index | agent/basic": 401,
+ "GET skills/[skillName]/index | agent/bearer": 401,
+ "GET skills/[skillName]/index | org/basic": 403,
+ "GET skills/[skillName]/index | org/bearer": 401,
+ "GET skills/[skillName]/index | project/basic": 404,
+ "GET skills/[skillName]/index | project/bearer": 403,
+ "GET skills/files/content | admin/admin": 401,
+ "GET skills/files/content | agent/basic": 401,
+ "GET skills/files/content | agent/bearer": 401,
+ "GET skills/files/content | org/basic": 403,
+ "GET skills/files/content | org/bearer": 401,
+ "GET skills/files/content | project/basic": 404,
+ "GET skills/files/content | project/bearer": 403,
+ "GET skills/index | admin/admin": 401,
+ "GET skills/index | agent/basic": 401,
+ "GET skills/index | agent/bearer": 401,
+ "GET skills/index | org/basic": 403,
+ "GET skills/index | org/bearer": 401,
+ "GET skills/index | project/basic": 200,
+ "GET skills/index | project/bearer": 403,
"GET traces/[traceId] | admin/admin": 401,
"GET traces/[traceId] | agent/basic": 401,
"GET traces/[traceId] | agent/bearer": 401,
@@ -667,6 +695,20 @@ exports[`public-api auth parity > legacy matches the captured baseline except do
"PATCH score-configs/[configId] | org/bearer": 401,
"PATCH score-configs/[configId] | project/basic": 400,
"PATCH score-configs/[configId] | project/bearer": 403,
+ "PATCH skills/[skillName]/index | admin/admin": 401,
+ "PATCH skills/[skillName]/index | agent/basic": 401,
+ "PATCH skills/[skillName]/index | agent/bearer": 401,
+ "PATCH skills/[skillName]/index | org/basic": 403,
+ "PATCH skills/[skillName]/index | org/bearer": 401,
+ "PATCH skills/[skillName]/index | project/basic": 400,
+ "PATCH skills/[skillName]/index | project/bearer": 403,
+ "PATCH skills/[skillName]/versions/[skillVersion] | admin/admin": 401,
+ "PATCH skills/[skillName]/versions/[skillVersion] | agent/basic": 401,
+ "PATCH skills/[skillName]/versions/[skillVersion] | agent/bearer": 401,
+ "PATCH skills/[skillName]/versions/[skillVersion] | org/basic": 403,
+ "PATCH skills/[skillName]/versions/[skillVersion] | org/bearer": 401,
+ "PATCH skills/[skillName]/versions/[skillVersion] | project/basic": 400,
+ "PATCH skills/[skillName]/versions/[skillVersion] | project/bearer": 403,
"PATCH spans | admin/admin": 401,
"PATCH spans | agent/basic": 401,
"PATCH spans | agent/bearer": 401,
@@ -874,6 +916,13 @@ exports[`public-api auth parity > legacy matches the captured baseline except do
"POST scores/index | org/bearer": 401,
"POST scores/index | project/basic": 400,
"POST scores/index | project/bearer": 400,
+ "POST skills/index | admin/admin": 401,
+ "POST skills/index | agent/basic": 401,
+ "POST skills/index | agent/bearer": 401,
+ "POST skills/index | org/basic": 403,
+ "POST skills/index | org/bearer": 401,
+ "POST skills/index | project/basic": 400,
+ "POST skills/index | project/bearer": 403,
"POST spans | admin/admin": 401,
"POST spans | agent/basic": 401,
"POST spans | agent/bearer": 401,
diff --git a/web/src/__tests__/server/mcp-tools-read.servertest.ts b/web/src/__tests__/server/mcp-tools-read.servertest.ts
index 321b1132e1..428e134517 100644
--- a/web/src/__tests__/server/mcp-tools-read.servertest.ts
+++ b/web/src/__tests__/server/mcp-tools-read.servertest.ts
@@ -197,6 +197,11 @@ import {
GetDatasetRunsMcpInput,
GetDatasetsMcpInput,
} from "@/src/features/mcp/server/datasets/schema";
+import { SkillService } from "@/src/features/skills/server";
+import { handleListSkills } from "@/src/features/mcp/server/skills/tools/listSkills";
+import { handleGetSkill } from "@/src/features/mcp/server/skills/tools/getSkill";
+import { handleLoadSkill } from "@/src/features/mcp/server/skills/tools/loadSkill";
+import { handleLoadSkillResource } from "@/src/features/mcp/server/skills/tools/loadSkillResource";
const observationWindow = {
fromStartTime: new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString(),
@@ -377,6 +382,135 @@ const containsPropertyName = (value: unknown, expected: string): boolean => {
};
describe("MCP Read Tools", () => {
+ describe("skills tools", () => {
+ const createSkillForMcpReadTest = async () => {
+ const setup = await createMcpTestSetup();
+ const service = new SkillService(prisma);
+ const name = `mcp-skill-${randomUUID()}`;
+ const root = `---\nname: ${name}\ndescription: Review customer requests\n---\nFollow the reference checklist.\n`;
+ const reference = "Review the customer's résumé before proceeding.\n";
+ const actor = {
+ projectId: setup.projectId,
+ orgId: setup.orgId,
+ apiKeyId: setup.apiKeyId,
+ accessLevel: "project" as const,
+ };
+ const version = await service.createVersion({
+ projectId: setup.projectId,
+ createdBy: "API",
+ input: {
+ files: [
+ { path: "SKILL.md", content: root },
+ { path: "references/checklist.md", content: reference },
+ ],
+ },
+ actor,
+ });
+ return { ...setup, service, actor, name, root, reference, version };
+ };
+
+ it("lists skill metadata and loads the resolved version's manifest and raw text", async () => {
+ const fixture = await createSkillForMcpReadTest();
+ const manifest = (await handleGetSkill(
+ { name: fixture.name, label: "latest" },
+ fixture.context,
+ )) as Awaited<ReturnType<SkillService["get"]>>;
+
+ expect(manifest).toMatchObject({
+ name: fixture.name,
+ version: fixture.version.version,
+ files: expect.arrayContaining([
+ expect.objectContaining({ path: "SKILL.md" }),
+ expect.objectContaining({ path: "references/checklist.md" }),
+ ]),
+ });
+ expect(manifest.files.every((file) => !("content" in file))).toBe(true);
+
+ await fixture.service.createVersion({
+ projectId: fixture.projectId,
+ createdBy: "API",
+ input: {
+ files: [
+ {
+ path: "SKILL.md",
+ content: `${fixture.root}\nUpdated instructions.`,
+ },
+ { path: "references/checklist.md", content: "Updated checklist." },
+ ],
+ },
+ actor: fixture.actor,
+ });
+
+ await expect(
+ handleListSkills(
+ { name: fixture.name, page: 1, limit: 10 },
+ fixture.context,
+ ),
+ ).resolves.toMatchObject({
+ data: [
+ { name: fixture.name, latestVersion: 2, productionVersion: null },
+ ],
+ meta: { totalItems: 1 },
+ });
+ const selector = { name: fixture.name, version: manifest.version };
+ await expect(handleLoadSkill(selector, fixture.context)).resolves.toBe(
+ fixture.root,
+ );
+ await expect(
+ handleLoadSkillResource(
+ { ...selector, path: "references/checklist.md" },
+ fixture.context,
+ ),
+ ).resolves.toBe(fixture.reference);
+ });
+
+ it.each([
+ ["getSkill", handleGetSkill],
+ ["loadSkill", handleLoadSkill],
+ ["loadSkillResource", handleLoadSkillResource],
+ ] as const)(
+ "rejects conflicting selectors in %s",
+ async (_name, handler) => {
+ await expect(
+ handler(
+ {
+ name: "test-skill",
+ version: 1,
+ label: "latest",
+ path: "SKILL.md",
+ },
+ mockServerContext(),
+ ),
+ ).rejects.toThrow("Specify either version or label, not both");
+ },
+ );
+
+ it("keeps skill metadata and contents isolated to the authenticated project", async () => {
+ const fixture = await createSkillForMcpReadTest();
+ const other = await createMcpTestSetup();
+ const selector = { name: fixture.name, version: fixture.version.version };
+
+ await expect(
+ handleListSkills(
+ { name: fixture.name, page: 1, limit: 10 },
+ other.context,
+ ),
+ ).resolves.toMatchObject({ data: [], meta: { totalItems: 0 } });
+ for (const handler of [
+ handleGetSkill,
+ handleLoadSkill,
+ handleLoadSkillResource,
+ ]) {
+ await expect(
+ handler(
+ { ...selector, path: "references/checklist.md" },
+ other.context,
+ ),
+ ).rejects.toThrow("Skill version not found");
+ }
+ });
+ });
+
describe("listMonitors tool", () => {
it("should have readOnlyHint annotation", () => {
verifyToolAnnotations(listMonitorsTool, { readOnlyHint: true });
diff --git a/web/src/__tests__/server/public-api-auth-parity.servertest.ts b/web/src/__tests__/server/public-api-auth-parity.servertest.ts
index 6f1faddc2f..8fbea9b5a5 100644
--- a/web/src/__tests__/server/public-api-auth-parity.servertest.ts
+++ b/web/src/__tests__/server/public-api-auth-parity.servertest.ts
@@ -125,6 +125,13 @@ const projectRoutes: Route[] = [
route: "v2/prompts/[promptName]/versions/[promptVersion]",
methods: ["PATCH"],
},
+ { route: "skills/index", methods: ["GET", "POST"] },
+ { route: "skills/[skillName]/index", methods: ["GET", "PATCH"] },
+ {
+ route: "skills/[skillName]/versions/[skillVersion]",
+ methods: ["PATCH", "DELETE"],
+ },
+ { route: "skills/files/content", methods: ["GET"] },
{ route: "unstable/skills/index", methods: ["GET", "POST"] },
{ route: "unstable/skills/[skillName]/index", methods: ["GET", "PATCH"] },
{
@@ -205,7 +212,10 @@ function queryForRoute(route: string): Record<string, string> {
for (const match of route.matchAll(/\[([^\]]+)\]/g)) {
query[match[1]!] = nonexistentId;
}
- if (route === "unstable/skills/files/content") {
+ if (
+ route === "skills/files/content" ||
+ route === "unstable/skills/files/content"
+ ) {
query.sha256Hashes = Buffer.alloc(32).toString("base64");
}
return query;
diff --git a/web/src/__tests__/server/unit/in-app-agent-mcp-policy.servertest.ts b/web/src/__tests__/server/unit/in-app-agent-mcp-policy.servertest.ts
index 83c945933a..4b6eebbe30 100644
--- a/web/src/__tests__/server/unit/in-app-agent-mcp-policy.servertest.ts
+++ b/web/src/__tests__/server/unit/in-app-agent-mcp-policy.servertest.ts
@@ -1,6 +1,7 @@
import { describe, expect, expectTypeOf, it } from "vitest";
import {
+ createInAppAgentToolPolicy,
IN_APP_AGENT_LANGFUSE_MCP_TOOL_POLICIES,
type InAppAgentLangfuseMcpToolName,
} from "@langfuse/shared/in-app-agent/server/mcpPolicy";
@@ -12,9 +13,26 @@ import { toolRegistry } from "@/src/features/mcp/server/registry";
import { skillsFeature } from "@/src/features/mcp/server/skills";
describe("IN_APP_AGENT_LANGFUSE_MCP_TOOL_POLICIES", () => {
- it("keeps Skills MCP tools unregistered", () => {
+ it("exposes read-only Skills MCP tools to the assistant with skills read access", () => {
+ const policy = createInAppAgentToolPolicy({
+ userAccess: { projectRole: "VIEWER", isAdmin: false },
+ });
for (const { definition } of skillsFeature.tools) {
- expect(toolRegistry.getTool(definition.name)).toBeUndefined();
+ expect(toolRegistry.getTool(definition.name)?.definition).toEqual(
+ definition,
+ );
+ expect(definition.action).toBe("skills:read");
+ expect(definition.annotations?.readOnlyHint).toBe(true);
+ expect([...policy.available]).toContain(definition.name);
+ expect([...policy.autoApproved]).toContain(definition.name);
+ }
+ });
+
+ it("does not expose Skills MCP tools without user access", () => {
+ const policy = createInAppAgentToolPolicy({});
+ for (const { definition } of skillsFeature.tools) {
+ expect([...policy.available]).not.toContain(definition.name);
+ expect([...policy.autoApproved]).not.toContain(definition.name);
}
});
diff --git a/web/src/__tests__/server/unit/skill-file-contents-get.servertest.ts b/web/src/__tests__/server/unit/skill-file-contents-get.servertest.ts
index 2b2904bf5d..728e507720 100644
--- a/web/src/__tests__/server/unit/skill-file-contents-get.servertest.ts
+++ b/web/src/__tests__/server/unit/skill-file-contents-get.servertest.ts
@@ -35,7 +35,8 @@ vi.mock("@/src/features/public-api/server", async () => {
return { createAuthedProjectAPIRoute, withMiddlewares };
});
-import handler from "@/src/pages/api/public/unstable/skills/files/content";
+import handler from "@/src/pages/api/public/skills/files/content";
+import unstableHandler from "@/src/pages/api/public/unstable/skills/files/content";
const hashes = [
Buffer.alloc(32, 251).toString("base64"),
@@ -45,7 +46,7 @@ const hashes = [
async function request(sha256Hashes?: string, method: "GET" | "POST" = "GET") {
const params = new URLSearchParams();
if (sha256Hashes !== undefined) params.set("sha256Hashes", sha256Hashes);
- const url = `/api/public/unstable/skills/files/content?${params}`;
+ const url = `/api/public/skills/files/content?${params}`;
const { req, res } = createMocks<NextApiRequest, NextApiResponse>({
method,
url,
@@ -57,7 +58,11 @@ async function request(sha256Hashes?: string, method: "GET" | "POST" = "GET") {
return res;
}
-describe("GET /api/public/unstable/skills/files/content", () => {
+describe("GET /api/public/skills/files/content", () => {
+ it("keeps the unstable route compatible with existing clients", () => {
+ expect(unstableHandler).toBe(handler);
+ });
+
beforeEach(() => {
vi.clearAllMocks();
shadowAuth.mockResolvedValue({
diff --git a/web/src/features/in-app-agent/components/utils/side-effects.ts b/web/src/features/in-app-agent/components/utils/side-effects.ts
index a3fb5d7fce..92c5bcadc8 100644
--- a/web/src/features/in-app-agent/components/utils/side-effects.ts
+++ b/web/src/features/in-app-agent/components/utils/side-effects.ts
@@ -112,6 +112,10 @@ const IN_APP_AGENT_TOOL_TRPC_INVALIDATION_TARGETS = {
langfuse_createTextPrompt: ["prompts"],
langfuse_createChatPrompt: ["prompts"],
langfuse_updatePromptLabels: ["prompts"],
+ langfuse_listSkills: [],
+ langfuse_getSkill: [],
+ langfuse_loadSkill: [],
+ langfuse_loadSkillResource: [],
langfuse_listScores: [],
langfuse_getScore: [],
langfuse_createScore: ["scores", "scoreAnalytics"],
diff --git a/web/src/features/in-app-agent/components/utils/utils.ts b/web/src/features/in-app-agent/components/utils/utils.ts
index 3ded7eacdc..55dc3007e9 100644
--- a/web/src/features/in-app-agent/components/utils/utils.ts
+++ b/web/src/features/in-app-agent/components/utils/utils.ts
@@ -75,7 +75,9 @@ const IN_APP_AGENT_TOOL_PROGRESS_LABEL_OVERRIDES: Record<string, string> = {
getObservationFilterValues: "Looking up observation filters",
getPromptUnresolved: "Inspecting prompt",
getRequestContext: "Checking request context",
+ getSkill: "Inspecting skill",
listDashboardWidgets: "Browsing widgets",
+ listSkills: "Browsing skills",
loadSkill: "Loading skill",
loadSkillResource: "Loading skill resource",
proposeRedirect: "Opening page",
diff --git a/web/src/features/mcp/server/bootstrap.ts b/web/src/features/mcp/server/bootstrap.ts
index d96f56b79e..5a284cb2b3 100644
--- a/web/src/features/mcp/server/bootstrap.ts
+++ b/web/src/features/mcp/server/bootstrap.ts
@@ -12,6 +12,7 @@
import { toolRegistry, type McpFeatureModule } from "./registry";
import { promptsFeature } from "./prompts";
+import { skillsFeature } from "./skills";
import { observationsFeature } from "./observations";
import { annotationQueuesFeature } from "./annotationQueues";
import { commentsFeature } from "./comments";
@@ -31,6 +32,7 @@ import { v4MigrationFeature } from "./v4Migration";
const MCP_FEATURES = [
promptsFeature,
+ skillsFeature,
observationsFeature,
annotationQueuesFeature,
commentsFeature,
diff --git a/web/src/features/mcp/server/skills/tools/getSkill.ts b/web/src/features/mcp/server/skills/tools/getSkill.ts
index c5733e22f5..31a953c0a8 100644
--- a/web/src/features/mcp/server/skills/tools/getSkill.ts
+++ b/web/src/features/mcp/server/skills/tools/getSkill.ts
@@ -17,7 +17,7 @@ const GetSkillInputSchema = z
export const [getSkillTool, handleGetSkill] = defineTool({
name: "getSkill",
description:
- "Get skill metadata and file paths, without file contents. Select a version or label; defaults to production.",
+ "Get skill metadata and file paths, without file contents. Select a version or label; defaults to production. Use the returned version with loadSkill and loadSkillResource to read files from the same immutable version.",
action: "skills:read",
baseSchema: GetSkillBaseSchema,
inputSchema: GetSkillInputSchema,
diff --git a/web/src/features/mcp/server/skills/tools/loadSkill.ts b/web/src/features/mcp/server/skills/tools/loadSkill.ts
index 022c2e1157..83b0422c5d 100644
--- a/web/src/features/mcp/server/skills/tools/loadSkill.ts
+++ b/web/src/features/mcp/server/skills/tools/loadSkill.ts
@@ -17,7 +17,7 @@ const LoadSkillInputSchema = z
export const [loadSkillTool, handleLoadSkill] = defineTool({
name: "loadSkill",
description:
- "Read a skill's SKILL.md as text. Select a version or label; defaults to production.",
+ "Read a skill's SKILL.md as text. Select a version or label; defaults to production. Reuse the version returned by getSkill when loading multiple files.",
action: "skills:read",
baseSchema: LoadSkillBaseSchema,
inputSchema: LoadSkillInputSchema,
diff --git a/web/src/features/mcp/server/skills/tools/loadSkillResource.ts b/web/src/features/mcp/server/skills/tools/loadSkillResource.ts
index 74459e93a6..70b1804a39 100644
--- a/web/src/features/mcp/server/skills/tools/loadSkillResource.ts
+++ b/web/src/features/mcp/server/skills/tools/loadSkillResource.ts
@@ -22,7 +22,7 @@ const LoadSkillResourceInputSchema = z
export const [loadSkillResourceTool, handleLoadSkillResource] = defineTool({
name: "loadSkillResource",
description:
- "Read a skill file as text by path (see getSkill). Select a version or label; defaults to production.",
+ "Read a skill file as text by path (see getSkill). Select a version or label; defaults to production. Reuse the version returned by getSkill when loading multiple files.",
action: "skills:read",
baseSchema: LoadSkillResourceBaseSchema,
inputSchema: LoadSkillResourceInputSchema,
diff --git a/web/src/features/public-api/server/clickHouseRequestTags.ts b/web/src/features/public-api/server/clickHouseRequestTags.ts
index b782d000c1..210620f99e 100644
--- a/web/src/features/public-api/server/clickHouseRequestTags.ts
+++ b/web/src/features/public-api/server/clickHouseRequestTags.ts
@@ -36,6 +36,8 @@ export const DYNAMIC_API_ROUTE_TEMPLATES = [
"/api/public/unstable/dashboards/[dashboardId]",
"/api/public/unstable/dashboards/[dashboardId]/placements",
"/api/public/unstable/dashboards/[dashboardId]/placements/[placementId]",
+ "/api/public/skills/[skillName]",
+ "/api/public/skills/[skillName]/versions/[skillVersion]",
"/api/public/unstable/skills/[skillName]",
"/api/public/unstable/skills/[skillName]/versions/[skillVersion]",
"/api/public/v2/datasets/[datasetName]",
diff --git a/web/src/features/public-api/types/unstable-skills.ts b/web/src/features/public-api/types/skills.ts
similarity index 100%
rename from web/src/features/public-api/types/unstable-skills.ts
rename to web/src/features/public-api/types/skills.ts
diff --git a/web/src/features/skills/README.md b/web/src/features/skills/README.md
index 3e919ce6e0..b9dd9ac887 100644
--- a/web/src/features/skills/README.md
+++ b/web/src/features/skills/README.md
@@ -1,12 +1,12 @@
## REST
-- `GET /api/public/unstable/skills`
-- `POST /api/public/unstable/skills`
-- `GET /api/public/unstable/skills/{skillName}`
-- `PATCH /api/public/unstable/skills/{skillName}`
-- `GET /api/public/unstable/skills/files/content?sha256Hashes=hash1,hash2`
-- `PATCH /api/public/unstable/skills/{skillName}/versions/{skillVersion}`
-- `DELETE /api/public/unstable/skills/{skillName}/versions/{skillVersion}`
+- `GET /api/public/skills`
+- `POST /api/public/skills`
+- `GET /api/public/skills/{skillName}`
+- `PATCH /api/public/skills/{skillName}`
+- `GET /api/public/skills/files/content?sha256Hashes=hash1,hash2`
+- `PATCH /api/public/skills/{skillName}/versions/{skillVersion}`
+- `DELETE /api/public/skills/{skillName}/versions/{skillVersion}`
## tRPC
@@ -29,3 +29,7 @@ Tools at `/api/public/mcp`:
- `getSkill`
- `loadSkill`
- `loadSkillResource`
+
+These read-only tools are available to the in-app assistant with `skills:read`
+access. Use the version returned by `getSkill` when loading multiple files to
+keep resources pinned to the same immutable skill version.
diff --git a/web/src/features/skills/components/SkillsPage.tsx b/web/src/features/skills/components/SkillsPage.tsx
index aecf33d132..f667d6e301 100644
--- a/web/src/features/skills/components/SkillsPage.tsx
+++ b/web/src/features/skills/components/SkillsPage.tsx
@@ -152,7 +152,7 @@ function SkillsHeaderActions({
<DesignSystemButton
text="API reference"
variant="ghost"
- href="https://api.reference.langfuse.com/#tag/unstableskills"
+ href="https://api.reference.langfuse.com/#tag/skills"
/>
<DesignSystemButton
text="Install with CLI"
diff --git a/web/src/features/skills/server/skill-router.ts b/web/src/features/skills/server/skill-router.ts
index aaba2d2b9c..90971020e0 100644
--- a/web/src/features/skills/server/skill-router.ts
+++ b/web/src/features/skills/server/skill-router.ts
@@ -16,7 +16,7 @@ import {
import { throwIfNoProjectAccess } from "@/src/features/rbac";
import { SkillService } from "./index";
-import { GetSkillFileContentsInputSchema } from "@/src/features/public-api/types/unstable-skills";
+import { GetSkillFileContentsInputSchema } from "@/src/features/public-api/types/skills";
import { SkillListOrderBySchema } from "../constants/skillsSorting";
const projectInput = z.object({ projectId: z.string() });
diff --git a/web/src/pages/api/public/skills/[skillName]/index.ts b/web/src/pages/api/public/skills/[skillName]/index.ts
new file mode 100644
index 0000000000..09649f71e8
--- /dev/null
+++ b/web/src/pages/api/public/skills/[skillName]/index.ts
@@ -0,0 +1,64 @@
+import { prisma } from "@langfuse/shared/src/db";
+import { z } from "zod/v4";
+import {
+ SkillNameSchema,
+ SkillSelectorSchema,
+ SkillVersionSchema,
+ UpdateSkillTagsBodySchema,
+} from "@langfuse/shared";
+import {
+ createAuthedProjectAPIRoute,
+ withMiddlewares,
+} from "@/src/features/public-api/server";
+import { SkillService } from "@/src/features/skills/server";
+import { GetSkillResponseSchema } from "@/src/features/public-api/types/skills";
+
+const querySchema = SkillSelectorSchema.and(
+ z.object({
+ skillName: SkillNameSchema,
+ includeContent: z
+ .enum(["true", "false"])
+ .optional()
+ .transform((value) => value === "true"),
+ }),
+);
+
+export default withMiddlewares({
+ PATCH: createAuthedProjectAPIRoute({
+ name: "Update Skill",
+ action: "skills:CUD",
+ querySchema: z.object({ skillName: SkillNameSchema }),
+ bodySchema: UpdateSkillTagsBodySchema,
+ responseSchema: SkillVersionSchema,
+ rateLimitResource: "public-api",
+ fn: ({ query, body, auth, ctx }) =>
+ new SkillService(prisma).setTags({
+ projectId: auth.scope.projectId,
+ name: query.skillName,
+ tags: body.tags,
+ actor: {
+ apiKeyId: auth.scope.apiKeyId!,
+ orgId: auth.scope.orgId,
+ projectId: auth.scope.projectId,
+ accessLevel: auth.scope.accessLevel,
+ ctx,
+ },
+ }),
+ }),
+ GET: createAuthedProjectAPIRoute({
+ name: "Get Skill",
+ action: "skills:read",
+ querySchema,
+ responseSchema: GetSkillResponseSchema,
+ rateLimitResource: "public-api",
+ fn: async ({ query, auth, res }) => {
+ if (query.includeContent) res.setHeader("Cache-Control", "no-store");
+ return new SkillService(prisma).get({
+ projectId: auth.scope.projectId,
+ name: query.skillName,
+ selector: query,
+ includeContent: query.includeContent,
+ });
+ },
+ }),
+});
diff --git a/web/src/pages/api/public/skills/[skillName]/versions/[skillVersion].ts b/web/src/pages/api/public/skills/[skillName]/versions/[skillVersion].ts
new file mode 100644
index 0000000000..95f09f5c5b
--- /dev/null
+++ b/web/src/pages/api/public/skills/[skillName]/versions/[skillVersion].ts
@@ -0,0 +1,65 @@
+import { prisma } from "@langfuse/shared/src/db";
+import { z } from "zod/v4";
+import {
+ DeleteSkillVersionResponseSchema,
+ SkillNameSchema,
+ SkillVersionSchema,
+ UpdateSkillLabelsBodySchema,
+} from "@langfuse/shared";
+import {
+ createAuthedProjectAPIRoute,
+ withMiddlewares,
+} from "@/src/features/public-api/server";
+import { SkillService } from "@/src/features/skills/server";
+
+const versionQuerySchema = z.object({
+ skillName: SkillNameSchema,
+ skillVersion: z.coerce.number().int().positive(),
+});
+
+export default withMiddlewares({
+ PATCH: createAuthedProjectAPIRoute({
+ name: "Update Skill Version Labels",
+ action: "skills:CUD",
+ querySchema: versionQuerySchema,
+ bodySchema: UpdateSkillLabelsBodySchema,
+ responseSchema: SkillVersionSchema,
+ rateLimitResource: "public-api",
+ fn: ({ query, body, auth, ctx }) =>
+ new SkillService(prisma).setLabels({
+ projectId: auth.scope.projectId,
+ name: query.skillName,
+ version: query.skillVersion,
+ labels: body.labels,
+ actor: {
+ apiKeyId: auth.scope.apiKeyId!,
+ orgId: auth.scope.orgId,
+ projectId: auth.scope.projectId,
+ accessLevel: auth.scope.accessLevel,
+ ctx,
+ },
+ }),
+ }),
+ DELETE: createAuthedProjectAPIRoute({
+ name: "Delete Skill Version",
+ action: "skills:CUD",
+ querySchema: versionQuerySchema,
+ responseSchema: DeleteSkillVersionResponseSchema,
+ rateLimitResource: "public-api",
+ fn: async ({ query, auth, ctx }) => {
+ await new SkillService(prisma).deleteVersion({
+ projectId: auth.scope.projectId,
+ name: query.skillName,
+ version: query.skillVersion,
+ actor: {
+ apiKeyId: auth.scope.apiKeyId!,
+ orgId: auth.scope.orgId,
+ projectId: auth.scope.projectId,
+ accessLevel: auth.scope.accessLevel,
+ ctx,
+ },
+ });
+ return { deleted: true };
+ },
+ }),
+});
diff --git a/web/src/pages/api/public/skills/files/content.ts b/web/src/pages/api/public/skills/files/content.ts
new file mode 100644
index 0000000000..3e1c78a5ba
--- /dev/null
+++ b/web/src/pages/api/public/skills/files/content.ts
@@ -0,0 +1,27 @@
+import { prisma } from "@langfuse/shared/src/db";
+import {
+ createAuthedProjectAPIRoute,
+ withMiddlewares,
+} from "@/src/features/public-api/server";
+import {
+ GetSkillFileContentsQuerySchema,
+ GetSkillFileContentsResponseSchema,
+} from "@/src/features/public-api/types/skills";
+import { SkillService } from "@/src/features/skills/server";
+
+export default withMiddlewares({
+ GET: createAuthedProjectAPIRoute({
+ name: "Get Skill File Contents",
+ action: "skills:read",
+ querySchema: GetSkillFileContentsQuerySchema,
+ responseSchema: GetSkillFileContentsResponseSchema,
+ rateLimitResource: "public-api",
+ fn: async ({ query, auth, res }) => {
+ res.setHeader("Cache-Control", "no-store");
+ return new SkillService(prisma).getFileContents({
+ projectId: auth.scope.projectId,
+ sha256Hashes: query.sha256Hashes,
+ });
+ },
+ }),
+});
diff --git a/web/src/pages/api/public/skills/index.ts b/web/src/pages/api/public/skills/index.ts
new file mode 100644
index 0000000000..100765ae4e
--- /dev/null
+++ b/web/src/pages/api/public/skills/index.ts
@@ -0,0 +1,54 @@
+import { prisma } from "@langfuse/shared/src/db";
+import {
+ CreateSkillVersionBodySchema,
+ ListSkillsQuerySchema,
+ ListSkillsResponseSchema,
+ SkillVersionSchema,
+} from "@langfuse/shared";
+import {
+ createAuthedProjectAPIRoute,
+ withMiddlewares,
+} from "@/src/features/public-api/server";
+import { SkillService } from "@/src/features/skills/server";
+
+export const config = {
+ api: {
+ bodyParser: { sizeLimit: "4.5mb" },
+ },
+};
+
+export default withMiddlewares({
+ GET: createAuthedProjectAPIRoute({
+ name: "List Skills",
+ action: "skills:read",
+ querySchema: ListSkillsQuerySchema,
+ responseSchema: ListSkillsResponseSchema,
+ rateLimitResource: "public-api",
+ fn: ({ query, auth }) =>
+ new SkillService(prisma).list({
+ projectId: auth.scope.projectId,
+ input: query,
+ }),
+ }),
+ POST: createAuthedProjectAPIRoute({
+ name: "Create Skill Version",
+ action: "skills:CUD",
+ bodySchema: CreateSkillVersionBodySchema,
+ responseSchema: SkillVersionSchema,
+ successStatusCode: 201,
+ rateLimitResource: "public-api",
+ fn: ({ body, auth, ctx }) =>
+ new SkillService(prisma).createVersion({
+ projectId: auth.scope.projectId,
+ createdBy: "API",
+ input: body,
+ actor: {
+ apiKeyId: auth.scope.apiKeyId!,
+ orgId: auth.scope.orgId,
+ projectId: auth.scope.projectId,
+ accessLevel: auth.scope.accessLevel,
+ ctx,
+ },
+ }),
+ }),
+});
diff --git a/web/src/pages/api/public/unstable/skills/[skillName]/index.ts b/web/src/pages/api/public/unstable/skills/[skillName]/index.ts
index 2e4fbab50e..51c8a043eb 100644
--- a/web/src/pages/api/public/unstable/skills/[skillName]/index.ts
+++ b/web/src/pages/api/public/unstable/skills/[skillName]/index.ts
@@ -1,64 +1,2 @@
-import { prisma } from "@langfuse/shared/src/db";
-import { z } from "zod/v4";
-import {
- SkillNameSchema,
- SkillSelectorSchema,
- SkillVersionSchema,
- UpdateSkillTagsBodySchema,
-} from "@langfuse/shared";
-import {
- createAuthedProjectAPIRoute,
- withMiddlewares,
-} from "@/src/features/public-api/server";
-import { SkillService } from "@/src/features/skills/server";
-import { GetSkillResponseSchema } from "@/src/features/public-api/types/unstable-skills";
-
-const querySchema = SkillSelectorSchema.and(
- z.object({
- skillName: SkillNameSchema,
- includeContent: z
- .enum(["true", "false"])
- .optional()
- .transform((value) => value === "true"),
- }),
-);
-
-export default withMiddlewares({
- PATCH: createAuthedProjectAPIRoute({
- name: "Update Skill",
- action: "skills:CUD",
- querySchema: z.object({ skillName: SkillNameSchema }),
- bodySchema: UpdateSkillTagsBodySchema,
- responseSchema: SkillVersionSchema,
- rateLimitResource: "public-api",
- fn: ({ query, body, auth, ctx }) =>
- new SkillService(prisma).setTags({
- projectId: auth.scope.projectId,
- name: query.skillName,
- tags: body.tags,
- actor: {
- apiKeyId: auth.scope.apiKeyId!,
- orgId: auth.scope.orgId,
- projectId: auth.scope.projectId,
- accessLevel: auth.scope.accessLevel,
- ctx,
- },
- }),
- }),
- GET: createAuthedProjectAPIRoute({
- name: "Get Skill",
- action: "skills:read",
- querySchema,
- responseSchema: GetSkillResponseSchema,
- rateLimitResource: "public-api",
- fn: async ({ query, auth, res }) => {
- if (query.includeContent) res.setHeader("Cache-Control", "no-store");
- return new SkillService(prisma).get({
- projectId: auth.scope.projectId,
- name: query.skillName,
- selector: query,
- includeContent: query.includeContent,
- });
- },
- }),
-});
+// Compatibility route for clients using the unstable Skills API.
+export { default } from "@/src/pages/api/public/skills/[skillName]/index";
diff --git a/web/src/pages/api/public/unstable/skills/[skillName]/versions/[skillVersion].ts b/web/src/pages/api/public/unstable/skills/[skillName]/versions/[skillVersion].ts
index 95f09f5c5b..1153562fd7 100644
--- a/web/src/pages/api/public/unstable/skills/[skillName]/versions/[skillVersion].ts
+++ b/web/src/pages/api/public/unstable/skills/[skillName]/versions/[skillVersion].ts
@@ -1,65 +1,2 @@
-import { prisma } from "@langfuse/shared/src/db";
-import { z } from "zod/v4";
-import {
- DeleteSkillVersionResponseSchema,
- SkillNameSchema,
- SkillVersionSchema,
- UpdateSkillLabelsBodySchema,
-} from "@langfuse/shared";
-import {
- createAuthedProjectAPIRoute,
- withMiddlewares,
-} from "@/src/features/public-api/server";
-import { SkillService } from "@/src/features/skills/server";
-
-const versionQuerySchema = z.object({
- skillName: SkillNameSchema,
- skillVersion: z.coerce.number().int().positive(),
-});
-
-export default withMiddlewares({
- PATCH: createAuthedProjectAPIRoute({
- name: "Update Skill Version Labels",
- action: "skills:CUD",
- querySchema: versionQuerySchema,
- bodySchema: UpdateSkillLabelsBodySchema,
- responseSchema: SkillVersionSchema,
- rateLimitResource: "public-api",
- fn: ({ query, body, auth, ctx }) =>
- new SkillService(prisma).setLabels({
- projectId: auth.scope.projectId,
- name: query.skillName,
- version: query.skillVersion,
- labels: body.labels,
- actor: {
- apiKeyId: auth.scope.apiKeyId!,
- orgId: auth.scope.orgId,
- projectId: auth.scope.projectId,
- accessLevel: auth.scope.accessLevel,
- ctx,
- },
- }),
- }),
- DELETE: createAuthedProjectAPIRoute({
- name: "Delete Skill Version",
- action: "skills:CUD",
- querySchema: versionQuerySchema,
- responseSchema: DeleteSkillVersionResponseSchema,
- rateLimitResource: "public-api",
- fn: async ({ query, auth, ctx }) => {
- await new SkillService(prisma).deleteVersion({
- projectId: auth.scope.projectId,
- name: query.skillName,
- version: query.skillVersion,
- actor: {
- apiKeyId: auth.scope.apiKeyId!,
- orgId: auth.scope.orgId,
- projectId: auth.scope.projectId,
- accessLevel: auth.scope.accessLevel,
- ctx,
- },
- });
- return { deleted: true };
- },
- }),
-});
+// Compatibility route for clients using the unstable Skills API.
+export { default } from "@/src/pages/api/public/skills/[skillName]/versions/[skillVersion]";
diff --git a/web/src/pages/api/public/unstable/skills/files/content.ts b/web/src/pages/api/public/unstable/skills/files/content.ts
index 8165eb63de..b4d13c3941 100644
--- a/web/src/pages/api/public/unstable/skills/files/content.ts
+++ b/web/src/pages/api/public/unstable/skills/files/content.ts
@@ -1,27 +1,2 @@
-import { prisma } from "@langfuse/shared/src/db";
-import {
- createAuthedProjectAPIRoute,
- withMiddlewares,
-} from "@/src/features/public-api/server";
-import {
- GetSkillFileContentsQuerySchema,
- GetSkillFileContentsResponseSchema,
-} from "@/src/features/public-api/types/unstable-skills";
-import { SkillService } from "@/src/features/skills/server";
-
-export default withMiddlewares({
- GET: createAuthedProjectAPIRoute({
- name: "Get Skill File Contents",
- action: "skills:read",
- querySchema: GetSkillFileContentsQuerySchema,
- responseSchema: GetSkillFileContentsResponseSchema,
- rateLimitResource: "public-api",
- fn: async ({ query, auth, res }) => {
- res.setHeader("Cache-Control", "no-store");
- return new SkillService(prisma).getFileContents({
- projectId: auth.scope.projectId,
- sha256Hashes: query.sha256Hashes,
- });
- },
- }),
-});
+// Compatibility route for clients using the unstable Skills API.
+export { default } from "@/src/pages/api/public/skills/files/content";
diff --git a/web/src/pages/api/public/unstable/skills/index.ts b/web/src/pages/api/public/unstable/skills/index.ts
index 100765ae4e..94e6e7d214 100644
--- a/web/src/pages/api/public/unstable/skills/index.ts
+++ b/web/src/pages/api/public/unstable/skills/index.ts
@@ -1,54 +1,8 @@
-import { prisma } from "@langfuse/shared/src/db";
-import {
- CreateSkillVersionBodySchema,
- ListSkillsQuerySchema,
- ListSkillsResponseSchema,
- SkillVersionSchema,
-} from "@langfuse/shared";
-import {
- createAuthedProjectAPIRoute,
- withMiddlewares,
-} from "@/src/features/public-api/server";
-import { SkillService } from "@/src/features/skills/server";
+// Compatibility route for clients using the unstable Skills API.
+export { default } from "@/src/pages/api/public/skills/index";
export const config = {
api: {
bodyParser: { sizeLimit: "4.5mb" },
},
};
-
-export default withMiddlewares({
- GET: createAuthedProjectAPIRoute({
- name: "List Skills",
- action: "skills:read",
- querySchema: ListSkillsQuerySchema,
- responseSchema: ListSkillsResponseSchema,
- rateLimitResource: "public-api",
- fn: ({ query, auth }) =>
- new SkillService(prisma).list({
- projectId: auth.scope.projectId,
- input: query,
- }),
- }),
- POST: createAuthedProjectAPIRoute({
- name: "Create Skill Version",
- action: "skills:CUD",
- bodySchema: CreateSkillVersionBodySchema,
- responseSchema: SkillVersionSchema,
- successStatusCode: 201,
- rateLimitResource: "public-api",
- fn: ({ body, auth, ctx }) =>
- new SkillService(prisma).createVersion({
- projectId: auth.scope.projectId,
- createdBy: "API",
- input: body,
- actor: {
- apiKeyId: auth.scope.apiKeyId!,
- orgId: auth.scope.orgId,
- projectId: auth.scope.projectId,
- accessLevel: auth.scope.accessLevel,
- ctx,
- },
- }),
- }),
-});