# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Drata Frameworks API
  version: 1.0.0
extends: openapi/drata-frameworks-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 9
- target: $.paths['/workspaces/{workspaceId}/frameworks'].get
  update:
    x-apievangelist-phrasing:
      intent: List compliance frameworks
      effect: read
      questions:
      - Which compliance frameworks are enabled in my workspace?
      - Can I find frameworks that are ready by searching part of their name?
      instructions:
      - text: List frameworks in workspace {workspaceId}.
        slots:
          workspaceId: path.workspaceId
      - text: Find frameworks named like {name} in workspace {workspaceId}.
        slots:
          workspaceId: path.workspaceId
          name: query.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/workspaces/{workspaceId}/frameworks'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a custom compliance framework
      effect: write
      questions:
      - How do I add my own custom compliance framework?
      - What does a new custom framework need, like a short badge label?
      instructions:
      - text: Create custom framework {name} ({shortName}) in workspace {workspaceId} described as {description}.
        slots:
          workspaceId: path.workspaceId
          name: requestBody.name
          shortName: requestBody.shortName
          description: requestBody.description
      - text: 'Set up a new framework called {name} with badge {shortName} in workspace {workspaceId}: {description}.'
        slots:
          workspaceId: path.workspaceId
          name: requestBody.name
          shortName: requestBody.shortName
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/workspaces/{workspaceId}/framework-requirements'].get
  update:
    x-apievangelist-phrasing:
      intent: List requirements workspace-wide (legacy)
      effect: read
      questions:
      - Can I list requirements across all frameworks filtered by framework tag?
      - Does the older workspace-wide requirements endpoint filter by framework slug?
      instructions:
      - text: Using the legacy endpoint, list requirements in workspace {workspaceId} for framework slug {frameworkSlug}.
        slots:
          workspaceId: path.workspaceId
          frameworkSlug: query.frameworkSlug
      - text: Show in-scope requirements tagged {frameworkTag} across workspace {workspaceId}.
        slots:
          workspaceId: path.workspaceId
          frameworkTag: query.frameworkTag
      method: generated
      generated: '2026-09-26'
- target: $.paths['/workspaces/{workspaceId}/framework-requirements/{frameworkRequirementId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Set requirement custom fields (legacy)
      effect: write
      questions:
      - Is there an older endpoint to update requirement custom fields without the framework ID?
      - How do I set custom field values on a requirement through the legacy path?
      instructions:
      - text: Using the legacy endpoint, set custom fields {customFields} on requirement {frameworkRequirementId} in workspace {workspaceId}.
        slots:
          workspaceId: path.workspaceId
          frameworkRequirementId: path.frameworkRequirementId
          customFields: requestBody.customFields
      - text: Through the older workspace-level path, write custom field values {customFields} to requirement {frameworkRequirementId}, workspace {workspaceId}.
        slots:
          workspaceId: path.workspaceId
          frameworkRequirementId: path.frameworkRequirementId
          customFields: requestBody.customFields
      method: generated
      generated: '2026-09-26'
- target: $.paths['/workspaces/{workspaceId}/frameworks/{frameworkId}/requirements'].get
  update:
    x-apievangelist-phrasing:
      intent: List one framework's requirements
      effect: read
      questions:
      - What requirements make up one specific framework?
      - Can I list only the in-scope requirements of a single framework?
      instructions:
      - text: List requirements of framework {frameworkId} in workspace {workspaceId}.
        slots:
          workspaceId: path.workspaceId
          frameworkId: path.frameworkId
      - text: Show ready requirements of framework {frameworkId} in workspace {workspaceId} where isReady is {isReady}.
        slots:
          workspaceId: path.workspaceId
          frameworkId: path.frameworkId
          isReady: query.isReady
      method: generated
      generated: '2026-09-26'
- target: $.paths['/workspaces/{workspaceId}/frameworks/{frameworkId}/requirements'].post
  update:
    x-apievangelist-phrasing:
      intent: Add requirements to a custom framework
      effect: write
      questions:
      - How do I add requirements to my custom framework in bulk?
      - What happens if two requirements in the same batch share a code?
      instructions:
      - text: Add requirements {data} to custom framework {frameworkId} in workspace {workspaceId}.
        slots:
          workspaceId: path.workspaceId
          frameworkId: path.frameworkId
          data: requestBody.data
      - text: Bulk-load this batch of requirements {data} into framework {frameworkId}, workspace {workspaceId}.
        slots:
          workspaceId: path.workspaceId
          frameworkId: path.frameworkId
          data: requestBody.data
      method: generated
      generated: '2026-09-26'
- target: $.paths['/workspaces/{workspaceId}/frameworks/{frameworkId}/requirements/{requirementId}/controls'].get
  update:
    x-apievangelist-phrasing:
      intent: List controls mapped to a requirement
      effect: read
      questions:
      - Which controls are mapped to a specific framework requirement?
      - Can I get the full control list for a requirement beyond the capped expand?
      instructions:
      - text: List controls mapped to requirement {requirementId} of framework {frameworkId} in workspace {workspaceId}.
        slots:
          workspaceId: path.workspaceId
          frameworkId: path.frameworkId
          requirementId: path.requirementId
      - text: Page through all controls behind requirement {requirementId} (framework {frameworkId}, workspace {workspaceId}), {size} at a time.
        slots:
          workspaceId: path.workspaceId
          frameworkId: path.frameworkId
          requirementId: path.requirementId
          size: query.size
      method: generated
      generated: '2026-09-26'
- target: $.paths['/workspaces/{workspaceId}/frameworks/{frameworkId}/requirements/{requirementId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a custom framework requirement
      effect: write
      questions:
      - How do I change which controls map to a custom framework requirement?
      - Can I rename a requirement or move it to a different category?
      instructions:
      - text: Map controls {controlIds} to requirement {requirementId} in framework {frameworkId}, workspace {workspaceId}.
        slots:
          workspaceId: path.workspaceId
          frameworkId: path.frameworkId
          requirementId: path.requirementId
          controlIds: requestBody.controlIds
      - text: Rename requirement {requirementId} of framework {frameworkId} in workspace {workspaceId} to {name}.
        slots:
          workspaceId: path.workspaceId
          frameworkId: path.frameworkId
          requirementId: path.requirementId
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/workspaces/{workspaceId}/frameworks/{frameworkId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a custom framework
      effect: write
      questions:
      - Can I rename a custom framework or change its badge label?
      - Where do I edit the description of a framework I created?
      instructions:
      - text: Rename custom framework {frameworkId} in workspace {workspaceId} to {name}.
        slots:
          workspaceId: path.workspaceId
          frameworkId: path.frameworkId
          name: requestBody.name
      - text: Change the short name of framework {frameworkId} in workspace {workspaceId} to {shortName}.
        slots:
          workspaceId: path.workspaceId
          frameworkId: path.frameworkId
          shortName: requestBody.shortName
      method: generated
      generated: '2026-09-26'