▣ HR · SMART GENERATION

Related Skills Generator API

What it does

Related Skills Generator takes a job position or role and returns a ranked list of related job positions or skills. Send a content string, optionally set language, and use max_quantity to limit how many related results you want back.

The service submits the request as a job and returns a job_id plus a status_url for polling. When the job finishes, the status response includes a data object with id, type, and attributes. Inside attributes, you get the job status and a result array of objects with name and weight, so you can sort, filter, or display the related roles by relevance.

Use Related Skills Generator when you need adjacent roles for search, recommendations, career-path mapping, or HR taxonomy enrichment. For example, you can start from "Backend Developer" and build a list of nearby roles to support job matching or related-skill suggestions in a recruiting workflow.

Because the endpoint is asynchronous, you can submit a request, store the job identifier, and fetch the result once the status changes from queued or running to success or failed.

▣ ENDPOINT 01 / 02

POST

Related Skills Generator - Submit Job

http://localhost:8080/sharpapi/related-skills-generator

QUICKSTARTGUIDE

Quickstart

Submit a job to generate related job positions from a role.

curl -X POST "http://localhost:8080/sharpapi/related-skills-generator" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content":"Software Engineer","language":"English","max_quantity":5}'

What you'll get back

Returns a JSON object with job_id and status_url fields. job_id is the unique UUID for the submitted job, and status_url is the URI you can poll for status and results.

{
  "status_url": "https://apyhub.com/services/provider/sharpapi/api/v1/hr/related_skills/job/status/5a46e047-d97e-474d-9d19-84e1a0060813",
  "job_id": "5a46e047-d97e-474d-9d19-84e1a0060813"
}

TRY ITLIVE · 50 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Submits an async job to generate related job positions from a provided role or job title. The response returns a job identifier and a status URL that you can use to poll for completion.

Request Body

Parameter	Type	Mandatory	Description
content	String	Yes	Provide a job position/role to generate related job positions for.
language	String	No	Specify the language of the output. Default: `English`.
max_quantity	Number	No	Maximum number of related job positions to generate. Minimum: `1`.

Response

Returns a JSON object with two string fields: job_id and status_url. job_id is the unique identifier of the submitted job, and status_url is the URL to poll for the job's status and result.

Parameter	Type	Mandatory	Description
job_id	String	Yes	The unique identifier of the submitted job. Format: UUID.
status_url	String	Yes	URL to poll for the job's status and result. Format: URI.

Notes

This endpoint kicks off an async job and returns immediately with a job identifier; the actual work runs in the background. Pair this call with the corresponding job_check endpoint — poll that until the status reaches a terminal state to retrieve the result. Use job_id to track the submitted job.

Body

Name

Type

Description

bodyREQUIRED

object

—

▣ ENDPOINT 02 / 02

GET

Related Skills Generator - Check Job Status

http://localhost:8080/sharpapi/related-skills-generator/job/status/:job_id

QUICKSTARTGUIDE

Quickstart

Check the status of a related-skills generation job by replacing :job_id with your UUID job ID.

curl -X GET "http://localhost:8080/sharpapi/related-skills-generator/job/status/:job_id" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a JSON object with a data object field. data contains id and type, plus an attributes object with type, result, and status.

{
  "data": {
    "id": "8b7f2f0a-7b8c-4d6d-9c2f-5a1f2a3c4d5e",
    "type": "api_job_result",
    "attributes": {
      "type": "hr_related_skills",
      "result": [
        {
          "name": "Talent Acquisition Specialist",
          "weight": 0.92
        }
      ],
      "status": "success"
    }
  }
}

TRY ITLIVE · 1 ATOM

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Checks the status of a previously submitted related-skills generation job using its job ID. The response returns the job result container and its current status; when the job has completed successfully, the related skills data is available in the result payload.

Path Parameter(s)

Attribute	Type	Mandatory	Description
job_id	String	Yes	UUID that identifies the job.

Response

Returns a JSON object with a data object field. data contains the job result identifier, a result type, and an attributes object with the job type, the current status, and the generated related skills results.

Attribute	Type	Mandatory	Description
data	Object	No	Job result container.
data.id	String	No	UUID that identifies the job result.
data.type	String	No	Result type. The schema example is `api_job_result`.
data.attributes	Object	No	Job attributes container.
data.attributes.type	String	No	Job type. The schema example is `hr_related_skills`.
data.attributes.result	Object Array	No	Array of related skill/job position objects. Each item contains `name` and `weight`.
data.attributes.result[].name	String	No	The name of the related job position/skill.
data.attributes.result[].weight	Number	No	The relevance weight of this related job position/skill.
data.attributes.status	ENUM	No	Job status. Allowed values: `running`, `failed`, `queued`, `success`.

Notes

Poll this endpoint with the job_id returned by the submit call. The status field at data.attributes.status cycles through transitional values (queued, running) before reaching a terminal state (success, failed). The result fields are only populated once status is success; treat them as absent otherwise.

Path parameters

Name

Type

Description

job_idREQUIRED

string

—

▣ COMMON ERRORS

Errors any endpoint can return

400bad_request

Required parameter missing or malformed body.

401unauthorized

API key missing, revoked, or not authorized for this service.

429rate_limited

Your plan's per-second rate exceeded. Retry with exponential backoff.

503upstream_busy

Backend temporarily unavailable. Try again in a few seconds.