---
title: "Update skills"
method: PATCH
path: "/skills"
tags: ["Skills"]
---

# Update skills

`PATCH /skills`

## Request

- Base URL: `https://api.hibob.com/v1`
- URL: `https://api.hibob.com/v1/skills`
- Auth: one of:
  - HTTP basic
  - HTTP bearer

Bulk-update API-origin skills. Always a bulk operation: send an `items` array
(1–100 items). Each item is resolved by its `/skill/source` +
`/skill/externalId` locator and must include at least one writable field.
Updates apply only to skills created via this public API; a locator that points
to a non-API-origin skill is reported as not found.

`/skill/proficiencyLevels` is a full replacement when supplied. Per-item results
are returned in `results`; the request returns **200** even when some items fail.

**Rate limit:** 10 requests/min per tenant.

**OAuth scope (app-user):** `job_catalog.skills:write`.

**IAM permission:** `Job catalog / Skills / Manage` (company-scoped).

## Request body

- UpdateSkillsInput
  - `items` SkillUpdateItem[], required: Skills to update (1–100 items).
    - `/skill/source` string, required: External source system that owns this skill. Required — part of the locator.
    - `/skill/externalId` string, required: External ID of the skill in the source system. Required — part of the locator.
    - `/skill/name` string, nullable: New skill display name.
    - `/skill/description` string, nullable: New free-text description (up to 1000 characters).
    - `/skill/categoryName` string, nullable: New category display name. Must reference an existing category.
    - `/skill/status` 'draft' | 'active' | 'inactive': Lifecycle status of a skill.
    - `/skill/proficiencyLevels` ProficiencyLevelAssignment[], nullable: Full replacement of the skill's proficiency-level content. Omit to leave existing content unchanged; send an empty array to remove all content.
      - `proficiencyLevelId` integer, required: Numeric ID of an existing company proficiency level. Discover valid IDs with `GET /v1/skills/proficiency-levels`.
      - `description` string, nullable: Description of what this skill looks like at that proficiency level. Up to 1000 characters.

## Response `200`

Success

- UpdateSkillsOutput
  - `results` SkillBulkItemResult[], required: Per-item outcomes, in request order.
    - `index` integer, required: Zero-based index of the item in the request `items` array.
    - `status` string, required: `succeeded` or `failed`.
    - `httpStatus` integer, required: Per-item HTTP-style status (for example `201` created, `200` updated, `404` not found, `409` conflict, `422` unprocessable).
    - `resource` SkillWriteResult: Locator + identity returned for a successfully written skill.
      - `/skill/id` integer, nullable: Bob skill ID of the created or updated skill.
      - `/skill/source` string, nullable: External source system that owns this skill (echoed from the request locator).
      - `/skill/externalId` string, nullable: External ID of the skill in the source system (echoed from the request locator).
    - `errors` SkillBulkItemError[], nullable: Errors describing why the item failed. Present when `status` is `failed`.
      - `code` string, required: Machine-readable error code (for example `VALIDATION_ERROR`, `DUPLICATE_EXTERNAL_LOCATOR`, `DUPLICATE_SKILL_NAME`, `SKILL_NOT_FOUND`).
      - `message` string, required: Human-readable explanation of the failure for this item.

## Other responses

- `400`: Bad request — malformed request, unsupported field or filter, or failed validation.
- `401`: Unauthorized — authentication credentials are missing or invalid.
- `403`: Forbidden — the caller lacks the required Skills permission or OAuth scope.
- `429`: Too many requests — per-tenant rate limit exceeded. Retry after the indicated delay.
- `500`: Internal server error — an unexpected error occurred on the server.

---

[API](https://skmtc.dev/hibob/apis/skills-api.md) - [All operations](https://skmtc.dev/hibob/apis/skills-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hibob/apis/skills-api/revisions/8609962c0add?raw)