openapi: 3.0.3
info:
  title: Exec Collections Skills API
  version: '1.0'
  description: 'REST API for programmatic access to your Exec workspace.


    Use the Exec API to read workspace data, list members, retrieve group information,

    and create interactive scenario creation sessions.


    ## Authentication

    All requests require a valid API key passed in the Authorization header:

    ```

    Authorization: Bearer exec_live_...

    ```


    Create API keys in your workspace settings under **Settings > API**.

    '
servers:
- url: https://api.exec.com/rest/v1
  description: Production
security:
- bearerAuth: []
tags:
- name: Skills
paths:
  /skills:
    get:
      operationId: listSkills
      summary: List skills
      description: 'Returns a paginated list of skills in the workspace, ordered alphabetically by name.


        Skills represent competencies that are evaluated during roleplay sessions and calls

        (e.g. "Discovery Questions", "Objection Handling", "Procurement Selling"). Each skill

        can be linked to evaluation criteria across multiple scenarios.


        Use `?include=proficiency` to add aggregate proficiency stats per skill (participant

        count, scored participant count, percentage proficient+, and average score). This is

        computed across all workspace members who have practiced each skill.

        '
      tags:
      - Skills
      parameters:
      - name: include
        in: query
        description: 'Comma-separated list of optional data to include.

          Available values: `proficiency` (aggregate proficiency stats per skill).

          '
        schema:
          type: string
          example: proficiency
      - name: page
        in: query
        description: Page number (1-indexed)
        schema:
          type: integer
          default: 1
          minimum: 1
      - name: page_size
        in: query
        description: Number of results per page (max 100)
        schema:
          type: integer
          default: 50
          minimum: 1
          maximum: 100
      responses:
        '200':
          description: Paginated list of skills
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Skill'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
              example:
                data:
                - id: sk1a2b3c4d5e
                  name: Procurement Selling
                  slug: procurement-selling
                  description: Ability to identify and sell procurement solutions effectively.
                  created_at: '2026-01-10T09:00:00Z'
                  proficiency_summary:
                    participant_count: 25
                    scored_participant_count: 20
                    pct_proficient_plus: 60
                    avg_score: 72.5
                - id: sk6f7g8h9i0j
                  name: Objection Handling
                  slug: objection-handling
                  description: Skill in addressing and overcoming prospect objections.
                  created_at: '2026-01-15T14:30:00Z'
                  proficiency_summary:
                    participant_count: 18
                    scored_participant_count: 15
                    pct_proficient_plus: 40
                    avg_score: 65.3
                pagination:
                  page: 1
                  page_size: 50
                  total_count: 2
                  total_pages: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
  /skills/{skill_id}/proficiency:
    get:
      operationId: getSkillProficiency
      summary: Get skill proficiency by user
      description: 'Returns per-user proficiency data for a specific skill.


        Proficiency uses time-decay weighted scoring across all observations (roleplay sessions

        and calls combined). Recent observations count more than older ones (30-day half-life).

        A minimum of 3 observations is required before a proficiency score is calculated.


        Proficiency tiers: `excellent` (≥90), `proficient` (≥75), `developing` (≥50),

        `needs_work` (<50), `insufficient_data` (<3 observations).


        Only users with at least one observation are included in the response. If no user

        filters are provided, returns proficiency for all workspace members who have practiced

        this skill.

        '
      tags:
      - Skills
      parameters:
      - name: skill_id
        in: path
        required: true
        description: The skill's unique identifier (UUID)
        schema:
          type: string
      - name: user_ids
        in: query
        description: Comma-separated user IDs to filter by. When combined with user_emails, results are unioned (all matching users from either list are included).
        schema:
          type: string
      - name: user_emails
        in: query
        description: Comma-separated user email addresses to filter by. When combined with user_ids, results are unioned (all matching users from either list are included).
        schema:
          type: string
          example: jane@acme.com,bob@acme.com
      - name: group_ids
        in: query
        description: Comma-separated workspace group IDs to filter by
        schema:
          type: string
      - name: end_date
        in: query
        description: Calculate proficiency as of this date (ISO 8601). Defaults to now.
        schema:
          type: string
          format: date-time
      - name: exclude_system_users
        in: query
        description: Exclude sessions from system users (emails ending in @exec.com). Default false.
        schema:
          type: boolean
          default: false
      - name: page
        in: query
        description: Page number (1-indexed)
        schema:
          type: integer
          default: 1
          minimum: 1
      - name: page_size
        in: query
        description: Number of results per page (max 100)
        schema:
          type: integer
          default: 50
          minimum: 1
          maximum: 100
      responses:
        '200':
          description: Per-user proficiency data for the skill
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SkillProficiencyEntry'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
              example:
                data:
                - user:
                    id: u1a2b3c4d5e6
                    email: jane@acme.com
                    first_name: Jane
                    last_name: Smith
                  score: 82
                  tier: proficient
                  observation_count: 14
                  last_practiced_at: '2026-03-12T10:00:00Z'
                - user:
                    id: u7v8w9x0y1z2
                    email: bob@acme.com
                    first_name: Bob
                    last_name: Jones
                  score: null
                  tier: insufficient_data
                  observation_count: 2
                  last_practiced_at: '2026-03-10T15:30:00Z'
                pagination:
                  page: 1
                  page_size: 50
                  total_count: 2
                  total_pages: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          description: Unique user identifier
        email:
          type: string
          format: email
          description: User's email address
        first_name:
          type: string
          description: User's first name
        last_name:
          type: string
          description: User's last name
    ValidationErrorDetail:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              description: Error category (e.g., "invalid_request")
            code:
              type: string
              description: Specific error code (e.g., "user_not_found")
            message:
              type: string
              description: Human-readable error message
    Skill:
      type: object
      description: A competency that is evaluated during roleplay sessions and calls.
      properties:
        id:
          type: string
          description: Unique skill identifier
        name:
          type: string
          description: Skill name
        slug:
          type: string
          description: URL-friendly skill identifier
        description:
          type: string
          description: Description of the skill
        created_at:
          type: string
          format: date-time
          description: When the skill was created
        proficiency_summary:
          $ref: '#/components/schemas/SkillProficiencySummary'
          nullable: true
          description: Aggregate proficiency stats (only included when requested via `?include=proficiency`)
    SkillProficiencyEntry:
      type: object
      description: Proficiency data for a single user on a skill.
      properties:
        user:
          $ref: '#/components/schemas/User'
        score:
          type: number
          nullable: true
          description: Proficiency score (0-100). Null if fewer than 3 observations.
        tier:
          type: string
          enum:
          - excellent
          - proficient
          - developing
          - needs_work
          - insufficient_data
          description: Proficiency tier based on score thresholds
        observation_count:
          type: integer
          description: Total observations (roleplay sessions + calls) within the lookback window
        last_practiced_at:
          type: string
          format: date-time
          nullable: true
          description: When the most recent observation occurred
    SkillProficiencySummary:
      type: object
      description: Aggregate proficiency stats for a skill across all workspace members.
      properties:
        participant_count:
          type: integer
          description: Number of users with at least one observation on this skill
        scored_participant_count:
          type: integer
          description: Number of users with enough observations (3+) for a proficiency score
        pct_proficient_plus:
          type: integer
          description: Percentage of scored users at Proficient or Excellent tier
        avg_score:
          type: number
          nullable: true
          description: Average proficiency score across scored users (0-100)
    Pagination:
      type: object
      properties:
        page:
          type: integer
          description: Current page number
        page_size:
          type: integer
          description: Number of items per page
        total_count:
          type: integer
          description: Total number of items
        total_pages:
          type: integer
          description: Total number of pages
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationErrorDetail'
          example:
            error:
              type: authentication_error
              code: invalid_api_key
              message: Invalid or inactive API key
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationErrorDetail'
          example:
            error:
              type: not_found
              message: 'Scenario not found: abc123'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key created in Settings > API.


        Format: `exec_live_` followed by 40 alphanumeric characters.

        '