---
title: "Update workspace skill"
method: PUT
path: "/api/workspace/skills/{skill_id}"
---

# Update workspace skill

`PUT /api/workspace/skills/{skill_id}`

## Request

- Base URL: `https://app.base44.com`
- URL: `https://app.base44.com/api/workspace/skills/{skill_id}`
- Auth: HTTP bearer

<Info>This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.</Info>

Changes a skill's name, description, or instructions, or turns it on or off. Send only the fields you want to change. A field you leave out, or send as `null`, keeps its value, and an empty body changes nothing.

Set `enabled` to `false` to stop the AI from using the skill without deleting it.

Skills belong to the workspace your credential is for. With a personal access token, that's the token's workspace, and there's no parameter to choose another one.

Skills need the Builder plan or higher. Below it, this returns a `403`.

This is limited to 60 requests per minute, shared with the other endpoints that change skills. A signed-in session has its own limit, and every personal access token for the workspace shares one. Some workspaces have a different limit.

<Note>Call this as an owner or admin of the workspace, with a personal access token sent as a Bearer token, or from a signed-in session. A read-only token is refused, and workspace API keys aren't accepted.</Note>

<Warning>The response includes fields beyond the ones documented here. Don't rely on undocumented response fields, as they can change at any time.</Warning>

## Path parameters

- `skill_id` string, required: ID of the skill to update. Get it from `id` in [List workspace skills](/api-reference/list-workspace-skills).

## Request body

- UpdateSkillRequest
  - `name` string, nullable: New name. Name of the skill, up to 64 characters: lowercase letters and digits in words joined by single hyphens, such as `code-review`. Unique within the workspace.
  - `description` string, nullable: New description. When the skill applies, up to 1024 characters. The AI reads it to decide when to load the skill, so say what the skill is for.
  - `body` string, nullable: New instructions. The instructions the AI follows once it loads the skill, up to 50000 characters.
  - `enabled` boolean, nullable: `true` lets the AI builder use the skill, and `false` stops it.

## Response `200`

The updated skill.

- WorkspaceSkill
  - `id` string, required: ID of the skill.
  - `name` string, required: Name of the skill.
  - `description` string, required: When the skill applies.
  - `body` string, required: The instructions the AI follows once it loads the skill.
  - `enabled` boolean, required: Whether the AI can use the skill.
  - `created_by` string, required: Email of the member who created the skill.
  - `created_date` string, required: Time the skill was created, in UTC, as an ISO 8601 timestamp.
  - `updated_date` string, required: Time the skill last changed, in UTC, as an ISO 8601 timestamp.

## Other responses

- `401`: Missing or invalid credentials.
- `403`: The workspace's plan doesn't include skills, you aren't an owner or admin of the workspace, your token is read-only, or your credential can't be used on this endpoint.
- `404`: Skill not found in this workspace.
- `409`: Another skill in the workspace already has this name, or your workspace requires an unlocked SSO session.
- `422`: Validation Error
- `429`: Rate limit exceeded.

## Changes

- **2026-10-15** `31b59ecae1c9`: 1 info
  - the `body/anyOf[subschema #1]/` request property's maxLength was increased from `15000` to `50000`
- **2026-10-11** `80287813ab84`: 1 info
  - the endpoint scheme security `PersonalAccessTokenAuth` was added to the API
- **2026-10-10** `fc604cdcc3a2`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/idealspot/apis/base44-app-management-api/changes/api/workspace/skills/:skill_id/put.md)

---

[API](https://skmtc.dev/idealspot/apis/base44-app-management-api.md) - [All operations](https://skmtc.dev/idealspot/apis/base44-app-management-api/llms.txt) - [OpenAPI document](https://skmtc.dev/idealspot/apis/base44-app-management-api/revisions/b5b4ebd82a1e?raw)