# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Drip Entitlements API
  version: 1.0.0
extends: openapi/drippay-entitlements-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: 14
- target: $.paths['/v1/entitlement-plans'].get
  update:
    x-apievangelist-phrasing:
      intent: List entitlement plans
      effect: read
      questions:
      - Which entitlement tiers have I set up for my product?
      - Can I see all my feature-access plans in one list?
      instructions:
      - text: List all my entitlement plans.
      - text: Show every feature tier I've defined.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/entitlement-plans'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an entitlement plan
      effect: write
      questions:
      - How do I set up a new feature tier like Free or Pro?
      - Can I make a new entitlement plan the default for new customers?
      instructions:
      - text: Create an entitlement plan called {name} with slug {slug}.
        slots:
          name: requestBody.name
          slug: requestBody.slug
      - text: 'Add a tier {name} ({slug}) and make it the default plan: {isDefault}.'
        slots:
          name: requestBody.name
          slug: requestBody.slug
          isDefault: requestBody.isDefault
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/entitlement-plans/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an entitlement plan
      effect: read
      questions:
      - What does one particular entitlement tier contain?
      - Can I fetch a single feature plan by its ID?
      instructions:
      - text: Show entitlement plan {id}.
        slots:
          id: path.id
      - text: Get the details of feature tier {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/entitlement-plans/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Deactivate an entitlement plan
      effect: destructive
      questions:
      - How do I retire a feature tier I no longer offer?
      - Is deleting an entitlement plan permanent or just a deactivation?
      instructions:
      - text: Delete entitlement plan {id}.
        slots:
          id: path.id
      - text: Deactivate the feature tier {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/entitlement-plans/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update an entitlement plan
      effect: write
      questions:
      - Can I rename a feature tier or change its description?
      - How do I switch which entitlement plan is the default?
      instructions:
      - text: Rename entitlement plan {id} to {name}.
        slots:
          id: path.id
          name: requestBody.name
      - text: Set entitlement plan {id} active status to {isActive}.
        slots:
          id: path.id
          isActive: requestBody.isActive
      - text: Make tier {id} the default plan ({isDefault}).
        slots:
          id: path.id
          isDefault: requestBody.isDefault
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/entitlement-plans/{id}/versions'].get
  update:
    x-apievangelist-phrasing:
      intent: List versions of an entitlement plan
      effect: read
      questions:
      - Can I see how a feature tier's rules changed over time?
      - Which rule set was live in each earlier version of a plan?
      instructions:
      - text: List every version of entitlement plan {id}.
        slots:
          id: path.id
      - text: Show the version history and rules for tier {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/entitlement-plans/{id}/rules'].get
  update:
    x-apievangelist-phrasing:
      intent: List the feature rules on a plan
      effect: read
      questions:
      - What feature limits are configured on a tier?
      - Which features does an entitlement plan currently restrict?
      instructions:
      - text: List the rules on entitlement plan {id}.
        slots:
          id: path.id
      - text: Show the feature limits for tier {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/entitlement-plans/{id}/rules'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a feature limit rule to a plan
      effect: write
      questions:
      - How do I cap how many times a feature can be used per month on a tier?
      - Can I mark a feature as unlimited on one plan?
      instructions:
      - text: Add a rule to plan {id} limiting {featureKey} to {limitValue} per {period} as a {limitType} limit.
        slots:
          id: path.id
          featureKey: requestBody.featureKey
          limitValue: requestBody.limitValue
          period: requestBody.period
          limitType: requestBody.limitType
      - text: Give plan {id} unlimited {featureKey} ({unlimited}) with a {limitType} rule of {limitValue} per {period}.
        slots:
          id: path.id
          featureKey: requestBody.featureKey
          unlimited: requestBody.unlimited
          limitType: requestBody.limitType
          limitValue: requestBody.limitValue
          period: requestBody.period
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/entitlement-rules/{ruleId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an entitlement rule
      effect: destructive
      questions:
      - How do I remove a single feature limit from a tier?
      - Can I drop one rule without deleting the whole entitlement plan?
      instructions:
      - text: Delete entitlement rule {ruleId}.
        slots:
          ruleId: path.ruleId
      - text: Remove feature limit rule {ruleId}.
        slots:
          ruleId: path.ruleId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/entitlement-rules/{ruleId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change an entitlement rule's limit
      effect: write
      questions:
      - Can I raise the limit on an existing feature rule?
      - How do I make an existing rule unlimited?
      instructions:
      - text: Change the limit on rule {ruleId} to {limitValue}.
        slots:
          ruleId: path.ruleId
          limitValue: requestBody.limitValue
      - text: Set rule {ruleId} unlimited to {unlimited}.
        slots:
          ruleId: path.ruleId
          unlimited: requestBody.unlimited
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/customers/{customerId}/entitlement'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a customer's entitlement plan
      effect: read
      questions:
      - Which feature tier is a customer on?
      - What entitlement plan has been assigned to a given customer?
      instructions:
      - text: Show the entitlement plan assigned to customer {customerId}.
        slots:
          customerId: path.customerId
      - text: Tell me which tier customer {customerId} is on.
        slots:
          customerId: path.customerId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/customers/{customerId}/entitlement'].put
  update:
    x-apievangelist-phrasing:
      intent: Assign an entitlement plan to a customer
      effect: write
      questions:
      - How do I move a customer onto a different feature tier?
      - Can I give one customer overrides on top of their assigned plan?
      instructions:
      - text: Assign entitlement plan {planId} to customer {customerId}.
        slots:
          planId: requestBody.planId
          customerId: path.customerId
      - text: Put {customerId} on tier {planId} with overrides {overrides}.
        slots:
          customerId: path.customerId
          planId: requestBody.planId
          overrides: requestBody.overrides
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/entitlements/check'].post
  update:
    x-apievangelist-phrasing:
      intent: Check if a customer may use a feature
      effect: read
      questions:
      - Before running an expensive request, can I check whether the customer is still within quota?
      - Is a customer allowed to use a feature, and how much quota do they have left?
      instructions:
      - text: Check whether customer {customerId} can use {featureKey}.
        slots:
          customerId: requestBody.customerId
          featureKey: requestBody.featureKey
      - text: Can {customerId} consume {quantity} units of {featureKey} right now — check it.
        slots:
          customerId: requestBody.customerId
          quantity: requestBody.quantity
          featureKey: requestBody.featureKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/customers/{customerId}/entitlement/usage'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a customer's usage against plan limits
      effect: read
      questions:
      - How much of each feature limit has a customer used this period?
      - Which features is a customer closest to running out of?
      instructions:
      - text: Show current-period entitlement usage for customer {customerId}.
        slots:
          customerId: path.customerId
      - text: Compare usage to limits for every feature on {customerId}'s plan.
        slots:
          customerId: path.customerId
      method: generated
      generated: '2026-09-26'