> ## Documentation Index
> Fetch the complete documentation index at: https://help.skillsdb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get a career's full definition

> One call returning the career, its settings, the grading scale, its levels, sections, skill groups, every skill with its full configuration and per-level activation, and its learnings.

**Requires scope:** `careers:read`.



## OpenAPI

````yaml /api-docs/openapi.v1.json get /api/v1/careers/{id}/definition
openapi: 3.0.0
info:
  title: SkillsDB Public API
  description: >-
    The SkillsDB public REST API. Authenticate every request with an API key
    created in Settings → API Credentials, sent as `Authorization: Bearer
    sdb_live_…`. Errors follow RFC 9457 problem details; every `type` URI
    resolves under https://help.skillsdb.com/api-docs/errors/.
  version: '1'
  contact: {}
servers:
  - url: https://prod.skillsdbnext.com
    description: Production
  - url: https://staging.skillsdbnext.com
    description: Staging
security: []
tags: []
paths:
  /api/v1/careers/{id}/definition:
    get:
      tags:
        - Career
      summary: Get a career's full definition
      description: >-
        One call returning the career, its settings, the grading scale, its
        levels, sections, skill groups, every skill with its full configuration
        and per-level activation, and its learnings.


        **Requires scope:** `careers:read`.
      operationId: getCareerDefinition
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
          description: Opaque resource id.
      responses:
        '200':
          description: The resource, enveloped.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    $ref: '#/components/schemas/CareerDefinitionDto'
          headers:
            X-Request-Id:
              description: Unique id for this request — quote it when contacting support.
              schema:
                type: string
            RateLimit-Limit:
              description: The bucket's hourly allowance.
              schema:
                type: integer
            RateLimit-Remaining:
              description: Requests left in the current window.
              schema:
                type: integer
            RateLimit-Reset:
              description: Seconds until the window resets.
              schema:
                type: integer
        '400':
          description: >-
            Validation failed
            (`https://help.skillsdb.com/api-docs/errors/validation-error`)
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetailsDto'
          headers:
            X-Request-Id:
              description: Unique id for this request — quote it when contacting support.
              schema:
                type: string
            RateLimit-Limit:
              description: The bucket's hourly allowance.
              schema:
                type: integer
            RateLimit-Remaining:
              description: Requests left in the current window.
              schema:
                type: integer
            RateLimit-Reset:
              description: Seconds until the window resets.
              schema:
                type: integer
        '401':
          description: >-
            Invalid credential
            (`https://help.skillsdb.com/api-docs/errors/invalid-credential`)
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetailsDto'
          headers:
            X-Request-Id:
              description: Unique id for this request — quote it when contacting support.
              schema:
                type: string
            RateLimit-Limit:
              description: The bucket's hourly allowance.
              schema:
                type: integer
            RateLimit-Remaining:
              description: Requests left in the current window.
              schema:
                type: integer
            RateLimit-Reset:
              description: Seconds until the window resets.
              schema:
                type: integer
        '403':
          description: >-
            Insufficient scope
            (`https://help.skillsdb.com/api-docs/errors/insufficient-scope`) ·
            Insufficient permissions
            (`https://help.skillsdb.com/api-docs/errors/insufficient-permissions`)
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetailsDto'
          headers:
            X-Request-Id:
              description: Unique id for this request — quote it when contacting support.
              schema:
                type: string
            RateLimit-Limit:
              description: The bucket's hourly allowance.
              schema:
                type: integer
            RateLimit-Remaining:
              description: Requests left in the current window.
              schema:
                type: integer
            RateLimit-Reset:
              description: Seconds until the window resets.
              schema:
                type: integer
        '404':
          description: Not found (`https://help.skillsdb.com/api-docs/errors/not-found`)
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetailsDto'
          headers:
            X-Request-Id:
              description: Unique id for this request — quote it when contacting support.
              schema:
                type: string
            RateLimit-Limit:
              description: The bucket's hourly allowance.
              schema:
                type: integer
            RateLimit-Remaining:
              description: Requests left in the current window.
              schema:
                type: integer
            RateLimit-Reset:
              description: Seconds until the window resets.
              schema:
                type: integer
        '429':
          description: >-
            Rate limit exceeded
            (`https://help.skillsdb.com/api-docs/errors/rate-limit-exceeded`)
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetailsDto'
          headers:
            X-Request-Id:
              description: Unique id for this request — quote it when contacting support.
              schema:
                type: string
            RateLimit-Limit:
              description: The bucket's hourly allowance.
              schema:
                type: integer
            RateLimit-Remaining:
              description: Requests left in the current window.
              schema:
                type: integer
            RateLimit-Reset:
              description: Seconds until the window resets.
              schema:
                type: integer
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
        '500':
          description: >-
            Internal error
            (`https://help.skillsdb.com/api-docs/errors/internal-error`)
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetailsDto'
          headers:
            X-Request-Id:
              description: Unique id for this request — quote it when contacting support.
              schema:
                type: string
            RateLimit-Limit:
              description: The bucket's hourly allowance.
              schema:
                type: integer
            RateLimit-Remaining:
              description: Requests left in the current window.
              schema:
                type: integer
            RateLimit-Reset:
              description: Seconds until the window resets.
              schema:
                type: integer
      security:
        - apiKey:
            - careers:read
components:
  schemas:
    CareerDefinitionDto:
      type: object
      properties:
        id:
          type: string
          example: '18'
          description: Opaque career id.
        name:
          type: string
          example: Maintenance Technician
          description: Career name.
        description:
          type: string
          example: Keeps the line running.
          nullable: true
          description: Career description.
        icon:
          type: string
          example: wrench
          nullable: true
          description: Icon identifier.
        careerType:
          nullable: true
          description: The family this career is grouped under.
          allOf:
            - $ref: '#/components/schemas/ReferenceDto'
        levelCount:
          type: number
          example: 3
          description: Number of levels defined on the career.
        isCompleted:
          type: boolean
          example: false
          description: >-
            Informational flag set by the product's career builder; nothing
            depends on it. Skills reach a career's assignees through the levels
            they are active on, not through this flag.
        isApproved:
          type: boolean
          example: true
          description: >-
            Informational flag set by the product's career builder and imports;
            nothing in this API depends on it.
        createdAt:
          type: string
          example: '2026-01-12T08:30:00.000Z'
          description: Creation time (UTC).
        updatedAt:
          type: string
          example: '2026-03-02T14:00:00.000Z'
          nullable: true
          description: Last update time (UTC).
        settings:
          $ref: '#/components/schemas/CareerSettingsDto'
        gradingScale:
          description: The company grading scale every benchmark points at.
          type: array
          items:
            $ref: '#/components/schemas/GradingScaleRungDto'
        levels:
          type: array
          items:
            $ref: '#/components/schemas/CareerLevelDto'
        sections:
          type: array
          items:
            $ref: '#/components/schemas/CareerSectionDto'
        skillGroups:
          type: array
          items:
            $ref: '#/components/schemas/CareerSkillGroupDto'
        skills:
          type: array
          items:
            $ref: '#/components/schemas/CareerSkillDto'
        learnings:
          type: array
          items:
            $ref: '#/components/schemas/CareerLearningDto'
      required:
        - id
        - name
        - description
        - icon
        - careerType
        - levelCount
        - isCompleted
        - isApproved
        - createdAt
        - updatedAt
        - settings
        - gradingScale
        - levels
        - sections
        - skillGroups
        - skills
        - learnings
    ProblemDetailsDto:
      type: object
      properties:
        type:
          type: string
          example: https://help.skillsdb.com/api-docs/errors/validation-error
          description: >-
            A URI identifying the problem type — always resolves to a
            documentation page.
        title:
          type: string
          example: Validation failed
        status:
          type: number
          example: 400
        detail:
          type: string
          example: limit must be between 1 and 200
          description: Human-readable explanation specific to this occurrence.
        instance:
          type: string
          example: /api/v1/people
        requestId:
          type: string
          example: 0192c2f1-6f4e-7ab3-b1c4-5f6a7b8c9d0e
          description: >-
            Matches the X-Request-Id response header — quote it when contacting
            support.
        errors:
          description: Field-level failures, present on validation-error problems.
          type: array
          items:
            $ref: '#/components/schemas/ProblemFieldErrorDto'
        error:
          type: string
          example: trial_expired
          enum:
            - trial_expired
          description: >-
            Present only on a 403 when the workspace's trial has expired, so API
            access is suspended.
        upgrade_url:
          type: string
          example: https://app.skillsdb.com/settings/billing
          description: >-
            Present only alongside `error: trial_expired`: where a workspace
            admin upgrades to restore API access.
      required:
        - type
        - title
        - status
        - detail
        - instance
        - requestId
    ReferenceDto:
      type: object
      properties:
        id:
          type: string
          example: '42'
          description: Opaque resource id.
        name:
          type: string
          example: Welding
          description: Display name.
      required:
        - id
        - name
    CareerSettingsDto:
      type: object
      properties:
        proficiencyGrading:
          $ref: '#/components/schemas/ProficiencyGradingSettingDto'
        trainingDates:
          $ref: '#/components/schemas/TrainingDatesSettingDto'
        hideNonRequiredSkills:
          $ref: '#/components/schemas/HideNonRequiredSkillsSettingDto'
        assessments:
          $ref: '#/components/schemas/AssessmentsSettingDto'
        dashboard:
          $ref: '#/components/schemas/DashboardSettingDto'
      required:
        - proficiencyGrading
        - trainingDates
        - hideNonRequiredSkills
        - assessments
        - dashboard
    GradingScaleRungDto:
      type: object
      properties:
        id:
          type: string
          example: '7'
          description: Opaque rung id — what benchmarks reference.
        grade:
          type: number
          example: 3
          description: Numeric grade value used in gap computation.
        label:
          type: string
          example: Proficient
          description: Short label shown next to grades.
        description:
          type: string
          example: Performs the skill independently in routine situations.
          nullable: true
          description: Long description of what the rung means.
        isActive:
          type: boolean
          example: true
          description: Inactive rungs stay resolvable but are not offered for new grades.
      required:
        - id
        - grade
        - label
        - description
        - isActive
    CareerLevelDto:
      type: object
      properties:
        id:
          type: string
          example: '31'
          description: Opaque level id.
        name:
          type: string
          example: Senior
          nullable: true
          description: Level name.
        position:
          type: number
          example: 2
          nullable: true
          description: Position in the career's level order (1-based).
      required:
        - id
        - name
        - position
    CareerSectionDto:
      type: object
      properties:
        id:
          type: string
          example: '77'
          description: Opaque id of the career–section attachment.
        sectionLibraryId:
          type: string
          example: '12'
          description: Id of the shared library section this attaches.
        name:
          type: string
          example: Safety
          description: Section name from the shared library.
        description:
          type: string
          example: Plant safety fundamentals.
          nullable: true
          description: Section description from the shared library.
        position:
          type: number
          example: 1
          nullable: true
          description: Position in the career's section order (1-based).
        minimumRequiredSkills:
          type: number
          example: 3
          nullable: true
          description: >-
            Minimum approved skills required from this section, or null when
            unset.
      required:
        - id
        - sectionLibraryId
        - name
        - description
        - position
        - minimumRequiredSkills
    CareerSkillGroupDto:
      type: object
      properties:
        id:
          type: string
          example: '9'
          description: Opaque skill group id.
        name:
          type: string
          example: Core
          nullable: true
          description: Skill group name.
        position:
          type: number
          example: 1
          nullable: true
          description: Position in the career's group order (1-based).
      required:
        - id
        - name
        - position
    CareerSkillDto:
      type: object
      properties:
        id:
          type: string
          example: '205'
          description: Opaque id of the career–skill attachment.
        skill:
          description: The skill itself.
          allOf:
            - $ref: '#/components/schemas/ReferenceDto'
        skillDescription:
          type: string
          example: MIG and TIG welding.
          nullable: true
          description: The skill's full description text.
        sectionId:
          type: string
          example: '77'
          nullable: true
          description: Career-section id the skill sits under, or null when unsectioned.
        skillGroupIds:
          example:
            - '9'
          description: Skill group ids the skill is assigned to.
          type: array
          items:
            type: string
        position:
          type: number
          example: 2
          nullable: true
          description: Ordering within its section.
        benchmark:
          nullable: true
          description: Career-wide required rung — always resolved, never a bare integer.
          allOf:
            - $ref: '#/components/schemas/BenchmarkDto'
        requirement:
          description: >-
            The stored requirement configuration — never a per-person resolution
            (ENG-4066 decided model).
          allOf:
            - $ref: '#/components/schemas/RequirementConfigDto'
        trainingEvidence:
          description: What evidence completing training requires.
          allOf:
            - $ref: '#/components/schemas/TrainingEvidenceDto'
        trainingExpiry:
          nullable: true
          description: How long completed training stays valid; null when it never expires.
          allOf:
            - $ref: '#/components/schemas/TrainingExpiryDto'
        levels:
          description: Per-level activation for every level of the career.
          type: array
          items:
            $ref: '#/components/schemas/CareerSkillLevelDto'
      required:
        - id
        - skill
        - skillDescription
        - sectionId
        - skillGroupIds
        - position
        - benchmark
        - requirement
        - trainingEvidence
        - trainingExpiry
        - levels
    CareerLearningDto:
      type: object
      properties:
        id:
          type: string
          example: '301'
          description: Opaque id of the career–learning attachment.
        learning:
          description: The learning item.
          allOf:
            - $ref: '#/components/schemas/ReferenceDto'
        sectionId:
          type: string
          example: '77'
          nullable: true
          description: Career-section id it sits under, or null.
        position:
          type: number
          example: 1
          nullable: true
          description: Position in order.
        isRequired:
          type: boolean
          example: true
          description: Whether the learning is required.
        requiredAtLevelIds:
          example:
            - '31'
          description: Level ids that require this learning.
          type: array
          items:
            type: string
      required:
        - id
        - learning
        - sectionId
        - position
        - isRequired
        - requiredAtLevelIds
    ProblemFieldErrorDto:
      type: object
      properties:
        field:
          type: string
          example: email
        code:
          type: string
          example: max_length
        message:
          type: string
          example: email must be shorter than or equal to 75 characters
      required:
        - field
        - code
        - message
    ProficiencyGradingSettingDto:
      type: object
      properties:
        isEnabled:
          type: boolean
          example: true
      required:
        - isEnabled
    TrainingDatesSettingDto:
      type: object
      properties:
        isEnabled:
          type: boolean
          example: false
        timeline:
          $ref: '#/components/schemas/TrainingTimelineDto'
      required:
        - isEnabled
        - timeline
    HideNonRequiredSkillsSettingDto:
      type: object
      properties:
        isEnabled:
          type: boolean
          example: false
      required:
        - isEnabled
    AssessmentsSettingDto:
      type: object
      properties:
        isEnabled:
          type: boolean
          example: true
          description: Cannot be enabled unless proficiency grading is enabled.
      required:
        - isEnabled
    DashboardSettingDto:
      type: object
      properties:
        isEnabled:
          type: boolean
          example: false
        showCareerDescription:
          type: boolean
          example: true
        showTrainingDatesSummary:
          type: boolean
          example: true
        showProficiencySummary:
          type: boolean
          example: true
        showPinnedPages:
          type: boolean
          example: true
      required:
        - isEnabled
        - showCareerDescription
        - showTrainingDatesSummary
        - showProficiencySummary
        - showPinnedPages
    BenchmarkDto:
      type: object
      properties:
        id:
          type: string
          example: '7'
          description: Opaque rung id on the company grading scale.
        grade:
          type: number
          example: 3
          description: The rung's numeric grade value.
        label:
          type: string
          example: Proficient
          description: The rung's short label.
      required:
        - id
        - grade
        - label
    RequirementConfigDto:
      type: object
      properties:
        isRequired:
          type: boolean
          example: true
          description: >-
            The stored flag, with null resolved: only an explicit false turns
            the requirement off.
        scope:
          type: string
          enum:
            - all
            - going_forward
          example: all
          description: >-
            Whether the requirement binds everyone holding the career, or only
            people assigned from the effective date forward.
        effectiveFrom:
          type: string
          example: '2026-03-01T00:00:00.000Z'
          nullable: true
          description: When the requirement takes effect (not a due date).
        setBy:
          nullable: true
          description: Who set the requirement.
          allOf:
            - $ref: '#/components/schemas/ReferenceDto'
      required:
        - isRequired
        - scope
        - effectiveFrom
        - setBy
    TrainingEvidenceDto:
      type: object
      properties:
        requiresNote:
          type: boolean
          example: false
          description: Whether completing training requires a text note.
        requiresAttachment:
          type: boolean
          example: true
          description: Whether completing training requires an attachment.
      required:
        - requiresNote
        - requiresAttachment
    TrainingExpiryDto:
      type: object
      properties:
        days:
          type: number
          example: 0
          nullable: true
        months:
          type: number
          example: 6
          nullable: true
        years:
          type: number
          example: 0
          nullable: true
      required:
        - days
        - months
        - years
    CareerSkillLevelDto:
      type: object
      properties:
        levelId:
          type: string
          example: '31'
          description: The career level this activation refers to.
        isActive:
          type: boolean
          example: true
          description: Whether the skill is active at this level.
        benchmark:
          nullable: true
          description: >-
            The rung required at this level; refines the skill's career-wide
            benchmark.
          allOf:
            - $ref: '#/components/schemas/BenchmarkDto'
      required:
        - levelId
        - isActive
        - benchmark
    TrainingTimelineDto:
      type: object
      properties:
        days:
          type: number
          example: 0
          nullable: true
        months:
          type: number
          example: 6
          nullable: true
        years:
          type: number
          example: 0
          nullable: true
      required:
        - days
        - months
        - years
  securitySchemes:
    apiKey:
      scheme: bearer
      type: http
      description: >-
        An API key issued by a company administrator — an environment prefix
        (production: `sdb_live_`) followed by 32 characters. The prefix
        identifies the environment and MUST NOT be hard-coded or validated by
        clients; treat the whole key as opaque. Shown exactly once at creation;
        only a one-way hash is stored.


        **Scopes** (granted per key on the create screen; `:write` never implies
        `:read`):


        - `skills:read`

        - `skills:write`

        - `people:read`

        - `people:write`

        - `careers:read`

        - `careers:write`

        - `training:read`

        - `training:write`

        - `flags:read`

        - `flags:write`

        - `org:read`

        - `org:write`

        - `assessments:read`

        - `learning:read`

        - `learning:write`

        - `certifications:read`

        - `certifications:write`

        - `assessments:write`

        - `proficiency:read`

        - `proficiency:write`

        - `surveys:read`

        - `surveys:write`

        - `labels:read`

        - `labels:write`

````