# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Spade Category Personalization API
  version: 1.0.0
extends: openapi/spade-category-personalization-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 16
- target: $.paths['/categories'].get
  update:
    x-apievangelist-phrasing:
      intent: List default and custom integration categories
      effect: read
      questions:
      - What spending categories does Spade use by default, plus the ones I've added?
      - Can I list only my custom integration-level categories and skip the defaults?
      - Where do I find valid category IDs to use in triggers and personalizations?
      instructions:
      - text: List all default and custom integration-level categories.
      - text: Show categories filtered to the types {include}.
        slots:
          include: query.include
      method: generated
      generated: '2026-10-01'
- target: $.paths['/categories'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a custom integration-level category
      effect: write
      questions:
      - How do I add my own spending category that every user of my integration sees?
      - Can a custom category sit underneath one of the built-in categories?
      instructions:
      - text: Create an integration-wide category named {name} under parent {parentId}.
        slots:
          name: requestBody.name
          parentId: requestBody.parentId
      - text: Add a custom category {name} for all my users, nested beneath {parentId}.
        slots:
          name: requestBody.name
          parentId: requestBody.parentId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/categories'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete all custom integration-level categories
      effect: destructive
      questions:
      - How do I remove every custom category I created for my integration at once?
      - Is there a way to reset integration categories back to only the defaults?
      instructions:
      - text: Delete all my custom integration-level categories.
      - text: Wipe every integration-wide custom category I've created.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/categories/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete one custom integration-level category
      effect: destructive
      questions:
      - How do I delete a single integration-wide custom category by its ID?
      - Can I remove one custom category without affecting my others?
      instructions:
      - text: Delete integration category {id}.
        slots:
          id: path.id
      - text: Remove the custom integration-level category with ID {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/counterparty-category-personalizations'].get
  update:
    x-apievangelist-phrasing:
      intent: List integration-wide counterparty category overrides
      effect: read
      questions:
      - Which merchants have I re-categorized for my whole integration?
      - What counterparty category overrides apply to every user?
      instructions:
      - text: List all integration-level counterparty category personalizations.
      - text: Show the merchant category overrides set for my entire integration.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/counterparty-category-personalizations'].put
  update:
    x-apievangelist-phrasing:
      intent: Override a counterparty's category for all users
      effect: write
      questions:
      - How do I force a specific merchant to always map to my chosen category for every user?
      - Can I assign a custom category to a counterparty across the whole integration?
      instructions:
      - text: Categorize counterparty {counterpartyId} as {categoryId} for my entire integration.
        slots:
          counterpartyId: requestBody.counterpartyId
          categoryId: requestBody.categoryId
      - text: Set an integration-wide category override of {categoryId} on merchant {counterpartyId}.
        slots:
          categoryId: requestBody.categoryId
          counterpartyId: requestBody.counterpartyId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/counterparty-category-personalizations'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete all integration counterparty category overrides
      effect: destructive
      questions:
      - How do I clear every integration-wide merchant category override at once?
      - Can I reset all counterparty categorizations back to the defaults for everyone?
      instructions:
      - text: Delete all integration-level counterparty category personalizations.
      - text: Remove every merchant category override set for my integration.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/counterparty-category-personalizations/{counterpartyId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove an integration override for one counterparty
      effect: destructive
      questions:
      - How do I undo the integration-wide category override on a single merchant?
      - Can I delete the category personalization for just one counterparty?
      instructions:
      - text: Delete the integration category override for counterparty {counterpartyId}.
        slots:
          counterpartyId: path.counterpartyId
      - text: Stop re-categorizing merchant {counterpartyId} for all users.
        slots:
          counterpartyId: path.counterpartyId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{userId}/categories'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's custom categories
      effect: read
      questions:
      - What custom categories has one of my end users created?
      - Can I see the personal categories belonging to a single user?
      instructions:
      - text: List the custom categories for user {userId}.
        slots:
          userId: path.userId
      - text: Show every personal category user {userId} has made.
        slots:
          userId: path.userId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{userId}/categories'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a custom category for one user
      effect: write
      questions:
      - How do I let an individual user add their own spending category?
      - Must a user's custom category name be unique for that user?
      instructions:
      - text: Create category {name} under {parentId} for user {userId}.
        slots:
          name: requestBody.name
          parentId: requestBody.parentId
          userId: path.userId
      - text: Add a personal category {name} nested beneath {parentId} for user {userId} only.
        slots:
          name: requestBody.name
          parentId: requestBody.parentId
          userId: path.userId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{userId}/categories'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete all of a user's custom categories
      effect: destructive
      questions:
      - How do I wipe all the personal categories a single user created?
      - Can I reset one user's categories without touching integration-level ones?
      instructions:
      - text: Delete every custom category for user {userId}.
        slots:
          userId: path.userId
      - text: Clear all personal categories belonging to {userId}.
        slots:
          userId: path.userId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{userId}/categories/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete one of a user's custom categories
      effect: destructive
      questions:
      - How do I delete a single personal category for a specific user?
      - Can I remove one user-level category by its ID?
      instructions:
      - text: Delete category {id} for user {userId}.
        slots:
          id: path.id
          userId: path.userId
      - text: Remove user {userId}'s personal category {id}.
        slots:
          userId: path.userId
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{userId}/counterparty-category-personalizations'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's counterparty category overrides
      effect: read
      questions:
      - Which merchants has a particular user re-categorized for themselves?
      - What counterparty category overrides apply to just one user?
      instructions:
      - text: List the counterparty category personalizations for user {userId}.
        slots:
          userId: path.userId
      - text: Show the merchant category overrides user {userId} has set.
        slots:
          userId: path.userId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{userId}/counterparty-category-personalizations'].put
  update:
    x-apievangelist-phrasing:
      intent: Override a counterparty's category for one user
      effect: write
      questions:
      - How can a single user always see a certain merchant under their own category?
      - Can one user's merchant categorization differ from the rest of my integration?
      instructions:
      - text: For user {userId}, categorize counterparty {counterpartyId} as {categoryId}.
        slots:
          userId: path.userId
          counterpartyId: requestBody.counterpartyId
          categoryId: requestBody.categoryId
      - text: Set user {userId}'s category for merchant {counterpartyId} to {categoryId}.
        slots:
          userId: path.userId
          counterpartyId: requestBody.counterpartyId
          categoryId: requestBody.categoryId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{userId}/counterparty-category-personalizations'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete all of a user's counterparty overrides
      effect: destructive
      questions:
      - How do I clear every merchant category override for a single user?
      - Can I reset one user's counterparty categorizations in one call?
      instructions:
      - text: Delete all counterparty category personalizations for user {userId}.
        slots:
          userId: path.userId
      - text: Remove every merchant category override belonging to {userId}.
        slots:
          userId: path.userId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{userId}/counterparty-category-personalizations/{counterpartyId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a user's override for one counterparty
      effect: destructive
      questions:
      - How do I undo one user's custom category on a single merchant?
      - Can I delete a user-level personalization for just one counterparty?
      instructions:
      - text: Delete user {userId}'s category override for counterparty {counterpartyId}.
        slots:
          userId: path.userId
          counterpartyId: path.counterpartyId
      - text: Stop re-categorizing merchant {counterpartyId} for user {userId}.
        slots:
          counterpartyId: path.counterpartyId
          userId: path.userId
      method: generated
      generated: '2026-10-01'