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, and an optional job description (markdown) and/or posting URL.

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

Delete Role

DELETE /api/roles/:id

Soft-deletes the role (sets deleted_at), open to any org member. Refused with a 409 if the role is still linked to any assessment that has not itself been deleted — archive or reassign those assessments first, or link them to a different role. Restore the role from the trash to undo.

Restore Role

POST /api/roles/:id/restore

Restores a soft-deleted role from the trash back to the active list (clears deleted_at). Open to any org member.

Response

{
  "role": {
    "id": "...",
    "title": "..."
  }
}

Overview

Endpoints

Roles API

Roles

List Roles

Create Role

Import Roles from ATS

Get Role

Update Role

Delete Role

Restore Role

​Roles

​List Roles

​Create Role

​Import Roles from ATS

​Get Role

​Update Role

​Delete Role

​Restore Role

Roles

List Roles

Create Role

Import Roles from ATS

Get Role

Update Role

Delete Role

Restore Role