--- updatedAt: 2026-08-05T09:55:35.000Z --- Fetch the complete documentation index at: https://apidocs.hibob.com/llms.txt. Use this file to discover all available pages before exploring further. # Search skills Search API-origin skills with field projection, filters, and cursor pagination. **Testing notes:** 1. Use the testing widget's **Try It!** option to test this endpoint. 2. Use the **Examples > Request Example** option to see how to initiate body parameters. Copy the example into an external tool if needed. # OpenAPI definition ```json { "openapi": "3.1.1", "info": { "title": "Skills API", "contact": { "name": "Hi Bob, Inc." }, "description": "Public API for managing a company's API-origin skills in the Bob skills framework.\n\nUse this API to search, create, update, and archive skills that are owned by an\nexternal system (identified by the mandatory `/skill/source` + `/skill/externalId`\nlocator), and to discover the company's proficiency levels. All write payloads use\nthe flattened `fieldId: value` object contract.", "license": { "name": "Proprietary", "url": "https://apidocs.hibob.com/docs/api-terms-of-use" }, "version": "1.0.0" }, "servers": [ { "url": "https://api.hibob.com/v1", "description": "Production" }, { "url": "https://api.sandbox.hibob.com/v1", "description": "Sandbox" } ], "x-readme": { "metrics-enabled": false }, "tags": [ { "name": "Skills", "description": "Manage a company's API-origin skills and read its proficiency levels." } ], "security": [ { "basic": [] }, { "bearer": [] } ], "paths": { "/skills/search": { "post": { "operationId": "post_skills-search", "tags": [ "Skills" ], "summary": "Search skills", "description": "Search API-origin skills with field projection, filters, and cursor pagination.", "x-readme": { "hidden": true }, "requestBody": { "required": true, "description": "Request body for skill search. All fields are optional. Omit `fields` to return\nthe default field set; omit `filters` to return all API-origin skills.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchSkillsInput" }, "examples": { "filterBySourceAndStatus": { "summary": "Active skills from one source, selected fields", "description": "Project a subset of fields and filter by `/skill/source` and `/skill/status`.", "value": { "fields": [ "/skill/id", "/skill/name", "/skill/categoryName", "/skill/status", "/skill/source", "/skill/externalId" ], "filters": [ { "fieldId": "/skill/source", "operator": "equals", "values": [ "sharepoint" ] }, { "fieldId": "/skill/status", "operator": "equals", "values": [ "active" ] } ], "limit": 100 } }, "nextPage": { "summary": "Next page using cursor", "description": "Continue paging by passing the previous response's `next_cursor`. The cursor is opaque; this value is illustrative.", "value": { "fields": [ "/skill/id", "/skill/name" ], "limit": 100, "cursor": "eyJsYXN0SWQiOjEyMzQ1fQ==" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchSkillsOutput" }, "examples": { "page": { "summary": "A page of results with more to come", "value": { "items": [ { "/skill/id": 12345, "/skill/name": "Stakeholder Management", "/skill/categoryName": "Leadership", "/skill/status": "active", "/skill/source": "sharepoint", "/skill/externalId": "SP-SKILL-001" } ], "response_metadata": { "next_cursor": "eyJsYXN0SWQiOjEyMzQ1fQ==" } } }, "lastPage": { "summary": "Final page (no more results)", "value": { "items": [ { "/skill/id": 12346, "/skill/name": "Data Analysis", "/skill/status": "active", "/skill/source": "sharepoint", "/skill/externalId": "SP-SKILL-002" } ], "response_metadata": { "next_cursor": null } } } } } } }, "400": { "description": "Bad request — malformed request, unsupported field or filter, or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized — authentication credentials are missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Forbidden — the caller lacks the required Skills permission or OAuth scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Too many requests — per-tenant rate limit exceeded. Retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Internal server error — an unexpected error occurred on the server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "x-internal": false } } }, "components": { "securitySchemes": { "basic": { "type": "http", "scheme": "basic" }, "bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "OAuth 2.0", "description": "OAuth 2.0 authentication using an Access Token is available for\nregistered partners only. Try It! does not support the full HiBob OAuth\nflow. You can follow these steps to complete the\nOAuth 2.0 flow in Postman and then paste the token here." } }, "schemas": { "ApiErrorResponse": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable error code" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "type": "object", "additionalProperties": true, "description": "Structured error context keyed by field or domain identifier" }, "request_id": { "type": "string", "description": "Request identifier for support and tracing" } } }, "ProficiencyLevelAssignment": { "description": "A single proficiency-level entry attached to a skill. When `/skill/proficiencyLevels`\nis supplied on create or update, the full array replaces the skill's existing\nproficiency-level content.", "type": "object", "properties": { "proficiencyLevelId": { "type": "integer", "format": "int64", "description": "Numeric ID of an existing company proficiency level. Discover valid IDs with\n`GET /v1/skills/proficiency-levels`." }, "description": { "type": [ "string", "null" ], "maxLength": 1000, "description": "Description of what this skill looks like at that proficiency level. Up to 1000 characters." } }, "required": [ "proficiencyLevelId" ] }, "ResponseMetadata": { "description": "Pagination metadata returned alongside a page of results.", "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor that identifies the start of the next page of results.\nPass this value back as `cursor` on the next request to continue paging.\n`null` when there are no more results." } } }, "SearchSkillsInput": { "description": "Request body for skill search. All fields are optional. Omit `fields` to return\nthe default field set; omit `filters` to return all API-origin skills.", "type": "object", "properties": { "fields": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/SkillFieldId" }, "default": [], "description": "Field IDs to include in each result item (see `SkillFieldId`). When omitted\nor empty, a default field set is returned." }, "filters": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/SkillSearchFilter" }, "maxItems": 10, "default": [], "description": "Filters to apply. Empty or omitted returns all API-origin skills. At most 10\nfilters; only the `equals` operator is supported." }, "limit": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 200, "default": 50, "description": "Maximum number of results per page. Allowed range 1–200; defaults to 50." }, "cursor": { "type": [ "string", "null" ], "description": "Opaque cursor from a previous response's `response_metadata.next_cursor`.\nOmit on the first request." } } }, "SearchSkillsOutput": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SkillSearchItem" }, "description": "Page of matching skills. Each item is keyed by field ID; only requested\nfields are populated. Empty when there are no matches." }, "response_metadata": { "$ref": "#/components/schemas/ResponseMetadata", "description": "Pagination metadata for this page." } }, "required": [ "items", "response_metadata" ] }, "SkillFieldId": { "description": "Field IDs that can be requested in `fields` and that appear as keys on each\nsearch result item.", "type": "string", "enum": [ "/skill/id", "/skill/name", "/skill/description", "/skill/status", "/skill/categoryName", "/skill/source", "/skill/externalId", "/skill/proficiencyLevels", "/skill/createdAt" ] }, "SkillFilterFieldId": { "description": "Field IDs that may be used as a `fieldId` in a search filter.", "type": "string", "enum": [ "/skill/id", "/skill/name", "/skill/categoryName", "/skill/status", "/skill/source", "/skill/externalId" ] }, "SkillSearchFilter": { "description": "A single search filter. Only the `equals` operator is supported.", "type": "object", "properties": { "fieldId": { "$ref": "#/components/schemas/SkillFilterFieldId", "description": "Field ID to filter by (see `SkillFilterFieldId`)." }, "operator": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Comparison operator. Only `equals` is supported; any other value returns\n**400 Bad Request**." }, "values": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Filter values, always sent as JSON strings. IDs that look numeric (such as\n`/skill/id`) must still be sent as strings so large values are not truncated\nby JSON number precision." } }, "required": [ "fieldId", "operator", "values" ] }, "SkillSearchItem": { "description": "A skill result item, keyed by field ID. Only the fields requested in `fields`\nare populated.", "type": "object", "properties": { "/skill/id": { "type": [ "integer", "null" ], "format": "int64", "description": "Read-only Bob skill ID." }, "/skill/name": { "type": [ "string", "null" ], "description": "Display name of the skill." }, "/skill/description": { "type": [ "string", "null" ], "description": "Free-text description of the skill." }, "/skill/status": { "oneOf": [ { "$ref": "#/components/schemas/SkillStatus" }, { "type": "null" } ], "description": "Lifecycle status of the skill." }, "/skill/categoryName": { "type": [ "string", "null" ], "description": "Display name of the skill's category." }, "/skill/source": { "type": [ "string", "null" ], "description": "External source system that owns this skill." }, "/skill/externalId": { "type": [ "string", "null" ], "description": "External ID of the skill in the source system." }, "/skill/proficiencyLevels": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ProficiencyLevelAssignment" }, "description": "Per-skill proficiency-level content, ordered by proficiency level order." }, "/skill/createdAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Read-only creation timestamp (ISO 8601)." } } }, "SkillStatus": { "description": "Lifecycle status of a skill.", "type": "string", "enum": [ "draft", "active", "inactive" ] } } } } ```