Roles

A role is a job opening you’re hiring for. Roles are stored independently of assessments, and an assessment can be linked to one or more roles. A role holds a title, an optional job description (markdown) and/or posting URL, and up to five custom priority skills selected from the JD.

List Roles

GET /api/roles

Returns the org’s roles (newest first), each with a count of linked assessments.

curl "https://app.trygradient.ai/api/roles" \
  -H "Authorization: Bearer gai_your_key"

const res = await fetch('https://app.trygradient.ai/api/roles', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const { roles } = await res.json();

Create Role

POST /api/roles

string

required

The role title, e.g. “Senior Product Manager”.

string

The job description body (markdown). Optional.

string

A URL to the job posting. Optional.

curl -X POST "https://app.trygradient.ai/api/roles" \
  -H "Authorization: Bearer gai_your_key" \
  -H "Content-Type: application/json" \
  -d '{"title":"Senior Product Manager","jdText":"# About the role..."}'

Returns { role } with a 201 status.

Import Roles from ATS

Bulk-create roles from open jobs in a connected ATS. One role is created per selected job, with its title and job description filled in from the ATS. Jobs already linked to a role (same provider and job id) are auto-skipped, so the call is idempotent — re-running it never creates duplicate roles. Requires the ATS integrations feature to be enabled for the org.

POST /api/roles/import-ats

string

required

The ATS provider to import from, e.g. ashby or greenhouse.

array

required

The jobs to import. Each item is { jobId, title? }, where jobId is the ATS job’s external id. title is optional and used only for skip/failure display.

curl -X POST "https://app.trygradient.ai/api/roles/import-ats" \
  -H "Authorization: Bearer gai_your_key" \
  -H "Content-Type: application/json" \
  -d '{"provider":"ashby","jobs":[{"jobId":"09d9fe97","title":"Forward Deployed PM"}]}'

Returns { imported, skipped, failed }, where imported is the list of created roles ({ jobId, roleId, title }), skipped covers jobs already imported, and failed covers jobs whose detail fetch or role creation errored.

Get Role

GET /api/roles/:id

Returns a single role scoped to your organization. 404 if it does not exist or has been deleted.

Update Role

PATCH /api/roles/:id

string

New role title. Cannot be set to empty.

string

Replace the job description body.

string

Replace the job posting URL.

string

The workspace member who owns this role. Pass null to unassign.

string

The workspace member acting as recruiter for this role. Pass null to unassign. (Update-only — not accepted by Create Role.)

Extract Skills From The JD

POST /api/roles/:id/extract-skills

Returns the skills the role’s job description calls for, drawn from your organization’s skill taxonomy. The JD and the taxonomy are both read server-side from the role. The result is cached on the role and reused while the job description and the taxonomy are unchanged, so a repeat call returns immediately instead of waiting on a model. Editing either one invalidates the cache and the next call re-extracts. A fallback result is never cached.

boolean

default:"false"

Ignore any cached result and extract again.

Returns { skills, source, cached }. Each skill is { name, evidencePhrases, suggestedPriority } — name is always an exact taxonomy entry, evidencePhrases are verbatim JD substrings supporting it, and suggestedPriority marks the two to four most role-defining skills. source is "ai" for a model extraction or "fallback" for the deterministic keyword matcher, which is used automatically whenever the model is unavailable, so this endpoint does not fail on an extraction error.

curl -X POST "https://app.trygradient.ai/api/roles/role_123/extract-skills" \
  -H "Authorization: Bearer gai_your_key"

Delete Role

DELETE /api/roles/:id

Soft-deletes the role (sets deleted_at). Linked assessments are unaffected.

Overview

Endpoints

Roles

Roles

List Roles

Create Role

Import Roles from ATS

Get Role

Update Role

Extract Skills From The JD

Delete Role

​Roles

​List Roles

​Create Role

​Import Roles from ATS

​Get Role

​Update Role

​Extract Skills From The JD

​Delete Role

Roles

List Roles

Create Role

Import Roles from ATS

Get Role

Update Role

Extract Skills From The JD

Delete Role