---
title: "Search skills"
method: POST
path: "/skills/search"
tags: ["Skills"]
---

# Search skills

`POST /skills/search`

## Request

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

Search API-origin skills using field projection, filters, and cursor pagination.

Search always returns only API-origin skills (those with a `/skill/source` and
`/skill/externalId`). Use it to verify sync outcomes and reconcile an external
framework against Bob.

**Filters:** optional. Only the `equals` operator is supported, on the fields
listed in `SkillFilterFieldId`. Requesting an unsupported field or operator
returns **400 Bad Request**.

**Pagination:** cursor-based. Pass `limit` (1–200, default 50) and the
`response_metadata.next_cursor` from the previous page as `cursor`. The last
page returns `next_cursor: null`.

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

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

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

## Request body

- SearchSkillsInput: Request body for skill search. All fields are optional. Omit `fields` to return the default field set; omit `filters` to return all API-origin skills.
  - `fields` SkillFieldId[], nullable: Field IDs to include in each result item (see `SkillFieldId`). When omitted or empty, a default field set is returned.
  - `filters` SkillSearchFilter[], nullable: Filters to apply. Empty or omitted returns all API-origin skills. At most 10 filters; only the `equals` operator is supported.
    - `fieldId` '/skill/id' | '/skill/name' | '/skill/categoryName' | '/skill/status' | '/skill/source' | '/skill/externalId', required: Field IDs that may be used as a `fieldId` in a search filter.
    - `operator` string, required: Comparison operator. Only `equals` is supported; any other value returns **400 Bad Request**.
    - `values` string[], required: Filter values, always sent as JSON strings. IDs that look numeric (such as `/skill/id`) must still be sent as strings so large values are not truncated by JSON number precision.
  - `limit` integer, nullable: Maximum number of results per page. Allowed range 1–200; defaults to 50.
  - `cursor` string, nullable: Opaque cursor from a previous response's `response_metadata.next_cursor`. Omit on the first request.

## Response `200`

Success

- SearchSkillsOutput
  - `items` SkillSearchItem[], required: Page of matching skills. Each item is keyed by field ID; only requested fields are populated. Empty when there are no matches.
    - `/skill/id` integer, nullable: Read-only Bob skill ID.
    - `/skill/name` string, nullable: Display name of the skill.
    - `/skill/description` string, nullable: Free-text description of the skill.
    - `/skill/status` 'draft' | 'active' | 'inactive': Lifecycle status of a skill.
    - `/skill/categoryName` string, nullable: Display name of the skill's category.
    - `/skill/source` string, nullable: External source system that owns this skill.
    - `/skill/externalId` string, nullable: External ID of the skill in the source system.
    - `/skill/proficiencyLevels` ProficiencyLevelAssignment[], nullable: Per-skill proficiency-level content, ordered by proficiency level order.
      - `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.
    - `/skill/createdAt` string, date-time, nullable: Read-only creation timestamp (ISO 8601).
  - `response_metadata` ResponseMetadata, required: Pagination metadata returned alongside a page of results.
    - `next_cursor` string, nullable: Opaque cursor that identifies the start of the next page of results. Pass this value back as `cursor` on the next request to continue paging. `null` when there are no more results.

## 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)