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

# Archive skills

`PATCH /skills/archive`

## Request

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

Bulk-archive (soft-delete) 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. Archiving applies only to skills created via this
public API; a locator that points to a non-API-origin skill is reported as not
found. 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

- ArchiveSkillsInput
  - `items` SkillArchiveItem[], required: Skills to archive (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.

## Response `200`

Success

- ArchiveSkillsOutput
  - `results` SkillArchiveItemResult[], 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 (`204` archived, `404` not found, `409` conflict).
    - `resource` SkillArchiveResult: Identity + status returned for a successfully archived skill. Unlike create and update, archive echoes the skill's new status rather than the source locator.
      - `/skill/id` integer, nullable: Bob skill ID of the archived skill.
      - `/skill/status` string, nullable: Lifecycle status after archiving. Always `archived`.
    - `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)