GET/v1/skills/search

Fuzzy-search skills by keyword (typo-tolerant)

Return a paginated list of skills whose names fuzzy-match a search query. Matching uses PostgreSQL `pg_trgm` trigram similarity, so typos and partial words still hit — e.g. `progaming` returns `Programming`, and `actv listen` returns `Active Listening`. Results are ranked by similarity score descending. **When to use:** any time a caller has a free-form skill name ('critical thinking', 'excel', 'soldering') and needs the canonical O*NET skill entry before making a downstream call to `GET /v1/skills/{skill_id}` or `GET /v1/occupations/{soc_code}/skills`. **Inputs:** - `q` — the search term (1-200 chars). - `page` / `page_size` — standard pagination. - `category` — optional filter (knowledge / skill / ability). **Response shape:** `ApiResponse[PaginatedData[Skill]]`. Source: O*NET OnLine (USDOL/ETA). Required scope: `skills:read`.

Authentication

Requires API key via X-API-Key header.

Parameters

Name	In	Type	Required	Description
q	query	string	required	Search term for skill name
page	query	integer	optional	Page number (1-based)
page_size	query	integer	optional	Items per page (max 100)
category	query	any	optional	Filter by skill taxonomy category

Example request

curl

curl -X GET \
  "https://skills.wageapi.com/api/v1/skills/search?q=%3Cq%3E&page=1&page_size=20&category=%3Ccategory%3E" \
  -H "X-API-Key: YOUR_API_KEY"

Responses

200Successful Response

dataPaginatedData_Skill_required

itemsarray<Skill>required

array of Skill

skill_idstringrequired

O*NET skill identifier

namestringrequired

Skill name

descriptionanyoptional

What this skill covers

one of:

option 1:

string

option 2:

null

categorystringrequiredenum: knowledge | skill | ability

Skill taxonomy category

totalintegerrequired

Total number of matching records

pageintegerrequired

Current page number (1-based)

page_sizeintegerrequired

Items per page

pagesintegerrequired

Total number of pages

metadataMetadataSchemarequired

sourcesarray<SourceSchema>optional

array of SourceSchema

namestringrequired

Data source name (e.g. O*NET, BLS OES)

urlanyoptional

URL to the source

one of:

option 1:

string

option 2:

null

request_idstringrequired

Unique request identifier

rate_limitanyoptional

one of:

option 1:

limitintegerrequired

Maximum requests per day for current tier

remainingintegerrequired

Requests remaining today

resetstringrequired

UTC timestamp when limit resets

option 2:

null

401Missing or invalid API key.

errorErrorDetailrequired

Structured error payload returned by all Aethar APIs. Mirrors the shape produced by aethar_auth.exception_handlers so the OpenAPI spec accurately describes real error bodies for documentation readers and MCP clients.

codestringrequired

Machine-readable error code (e.g. INVALID_API_KEY)

messagestringrequired

Human-readable error message

statusanyoptional

HTTP status code

one of:

option 1:

integer

option 2:

null

request_idanyoptional

Request identifier — include in support tickets

one of:

option 1:

string

option 2:

null

suggestionanyoptional

Actionable hint on how to resolve the error

one of:

option 1:

string

option 2:

null

doc_urlanyoptional

Link to full documentation for this error code

one of:

option 1:

string

option 2:

null

fieldanyoptional

Field that caused the error (if applicable)

one of:

option 1:

string

option 2:

null

errorsanyoptional

Per-field validation errors (only for 422 VALIDATION_ERROR responses)

one of:

option 1:

array of object

object

option 2:

null

403API key lacks the required scope for this endpoint.

errorErrorDetailrequired

codestringrequired

Machine-readable error code (e.g. INVALID_API_KEY)

messagestringrequired

Human-readable error message

statusanyoptional

HTTP status code

one of:

option 1:

integer

option 2:

null

request_idanyoptional

Request identifier — include in support tickets

one of:

option 1:

string

option 2:

null

suggestionanyoptional

Actionable hint on how to resolve the error

one of:

option 1:

string

option 2:

null

doc_urlanyoptional

Link to full documentation for this error code

one of:

option 1:

string

option 2:

null

fieldanyoptional

Field that caused the error (if applicable)

one of:

option 1:

string

option 2:

null

errorsanyoptional

Per-field validation errors (only for 422 VALIDATION_ERROR responses)

one of:

option 1:

array of object

object

option 2:

null

422Request validation failed (bad query params, unknown category, etc.).

errorErrorDetailrequired

codestringrequired

Machine-readable error code (e.g. INVALID_API_KEY)

messagestringrequired

Human-readable error message

statusanyoptional

HTTP status code

one of:

option 1:

integer

option 2:

null

request_idanyoptional

Request identifier — include in support tickets

one of:

option 1:

string

option 2:

null

suggestionanyoptional

Actionable hint on how to resolve the error

one of:

option 1:

string

option 2:

null

doc_urlanyoptional

Link to full documentation for this error code

one of:

option 1:

string

option 2:

null

fieldanyoptional

Field that caused the error (if applicable)

one of:

option 1:

string

option 2:

null

errorsanyoptional

Per-field validation errors (only for 422 VALIDATION_ERROR responses)

one of:

option 1:

array of object

object

option 2:

null

429Daily rate limit exceeded for this API key.

errorErrorDetailrequired

codestringrequired

Machine-readable error code (e.g. INVALID_API_KEY)

messagestringrequired

Human-readable error message

statusanyoptional

HTTP status code

one of:

option 1:

integer

option 2:

null

request_idanyoptional

Request identifier — include in support tickets

one of:

option 1:

string

option 2:

null

suggestionanyoptional

Actionable hint on how to resolve the error

one of:

option 1:

string

option 2:

null

doc_urlanyoptional

Link to full documentation for this error code

one of:

option 1:

string

option 2:

null

fieldanyoptional

Field that caused the error (if applicable)

one of:

option 1:

string

option 2:

null

errorsanyoptional

Per-field validation errors (only for 422 VALIDATION_ERROR responses)

one of:

option 1:

array of object

object

option 2:

null

500Unexpected server error. Includes a request_id for support.

errorErrorDetailrequired

codestringrequired

Machine-readable error code (e.g. INVALID_API_KEY)

messagestringrequired

Human-readable error message

statusanyoptional

HTTP status code

one of:

option 1:

integer

option 2:

null

request_idanyoptional

Request identifier — include in support tickets

one of:

option 1:

string

option 2:

null

suggestionanyoptional

Actionable hint on how to resolve the error

one of:

option 1:

string

option 2:

null

doc_urlanyoptional

Link to full documentation for this error code

one of:

option 1:

string

option 2:

null

fieldanyoptional

Field that caused the error (if applicable)

one of:

option 1:

string

option 2:

null

errorsanyoptional

Per-field validation errors (only for 422 VALIDATION_ERROR responses)

one of:

option 1:

array of object

object

option 2:

null

Try this endpoint

Create a free Aethar account and generate an API key in 2 minutes.

Create free account →