API Evangelist conversational phrasing for Knock App Objects API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Knock App Objects API
  version: 1.0.0
extends: openapi/knock-app-objects-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: 19
- target: $.paths['/v1/objects/{collection}/{object_id}/preferences/{id}/workflows'].put
  update:
    x-apievangelist-phrasing:
      intent: Update all workflow settings in an object's preferences
      effect: write
      questions:
      - How do I replace the workflow opt-ins for an object's preference set?
      - Can an object opt out of several workflows in one update?
      instructions:
      - text: Replace the workflows section of preference set {id} for object {object_id} in {collection}.
        slots:
          collection: path.collection
          object_id: path.object_id
          id: path.id
      - text: Update every workflow opt-in at once on {collection}/{object_id}'s preference set {id}.
        slots:
          collection: path.collection
          object_id: path.object_id
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/objects/{collection}/{object_id}/preferences/{id}/channel_types/{type}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update one channel type in an object's preferences
      effect: write
      questions:
      - How do I turn off just email for an object's preference set?
      - Can I toggle a single channel type on an object without touching the others?
      instructions:
      - text: Disable channel type {type} in preference set {id} for object {object_id} in {collection}.
        slots:
          collection: path.collection
          object_id: path.object_id
          id: path.id
          type: path.type
      - text: Update only the {type} channel type setting on {collection}/{object_id}'s preference set {id}.
        slots:
          collection: path.collection
          object_id: path.object_id
          id: path.id
          type: path.type
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/objects/{collection}/bulk/delete'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete many objects in a collection
      effect: destructive
      questions:
      - How do I delete a list of objects from one collection at once?
      - Can I bulk remove objects by their IDs?
      instructions:
      - text: Bulk delete objects {object_ids} from collection {collection}.
        slots:
          object_ids: requestBody.object_ids
          collection: path.collection
      - text: 'Remove these objects from {collection} in one go: {object_ids}.'
        slots:
          collection: path.collection
          object_ids: requestBody.object_ids
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/objects/{collection}/{object_id}/preferences/{id}/categories/{key}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update one category in an object's preferences (deprecated)
      effect: write
      questions:
      - Can I still change a single category preference on an object with the deprecated endpoint?
      - How do I opt an object out of one notification category?
      instructions:
      - text: Turn off category {key} in preference set {id} for object {object_id} in {collection} using the deprecated single-category endpoint.
        slots:
          collection: path.collection
          object_id: path.object_id
          id: path.id
          key: path.key
      - text: Update the single category {key} on {collection}/{object_id}'s preference set {id}.
        slots:
          collection: path.collection
          object_id: path.object_id
          id: path.id
          key: path.key
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/objects/{collection}/{object_id}/preferences'].get
  update:
    x-apievangelist-phrasing:
      intent: List an object's preference sets
      effect: read
      questions:
      - Which preference sets does an object have?
      - Can I see every per-tenant preference set stored on an object?
      instructions:
      - text: List preference sets for object {object_id} in {collection}.
        slots:
          object_id: path.object_id
          collection: path.collection
      - text: Show all of {collection}/{object_id}'s preference sets.
        slots:
          object_id: path.object_id
          collection: path.collection
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/objects/{collection}/{object_id}/preferences/{id}/workflows/{key}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update one workflow in an object's preferences
      effect: write
      questions:
      - How do I opt an object out of a single workflow?
      - Can I change one workflow's preference on an object and leave the rest?
      instructions:
      - text: Turn off workflow {key} in preference set {id} for object {object_id} in {collection}.
        slots:
          collection: path.collection
          object_id: path.object_id
          id: path.id
          key: path.key
      - text: Update just the {key} workflow preference on {collection}/{object_id}'s preference set {id}.
        slots:
          collection: path.collection
          object_id: path.object_id
          id: path.id
          key: path.key
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/objects/{collection}/bulk/subscriptions/add'].post
  update:
    x-apievangelist-phrasing:
      intent: Add subscriptions to many objects
      effect: write
      questions:
      - How do I subscribe recipients to lots of objects in one collection at once?
      - What happens if a subscription already exists during a bulk add?
      instructions:
      - text: Bulk add subscriptions {subscriptions} in collection {collection}.
        slots:
          subscriptions: requestBody.subscriptions
          collection: path.collection
      - text: Subscribe recipients across {collection} objects using {subscriptions}.
        slots:
          collection: path.collection
          subscriptions: requestBody.subscriptions
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/objects/{collection}/{object_id}/preferences/{id}/categories'].put
  update:
    x-apievangelist-phrasing:
      intent: Update all category settings in an object's preferences
      effect: write
      questions:
      - How do I replace every category preference on an object at once?
      - Can I set an object's category opt-ins in one call?
      instructions:
      - text: Replace the categories section of preference set {id} for object {object_id} in {collection}.
        slots:
          collection: path.collection
          object_id: path.object_id
          id: path.id
      - text: Update every category opt-in at once on {collection}/{object_id}'s preference set {id}.
        slots:
          collection: path.collection
          object_id: path.object_id
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/objects/{collection}/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an object
      effect: read
      questions:
      - How do I look up an object and its properties?
      - Can I fetch one object from a collection by its ID?
      instructions:
      - text: Get object {id} from collection {collection}.
        slots:
          id: path.id
          collection: path.collection
      - text: Show the properties of {collection}/{id}.
        slots:
          collection: path.collection
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/objects/{collection}/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or update an object
      effect: write
      questions:
      - How do I create an object, like a project or team, to notify?
      - Can I set an object's locale and timezone when I identify it?
      instructions:
      - text: Set object {id} in {collection} with name {name}.
        slots:
          id: path.id
          collection: path.collection
          name: requestBody.name
      - text: Create or update {collection}/{id} with timezone {timezone}.
        slots:
          collection: path.collection
          id: path.id
          timezone: requestBody.timezone
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/objects/{collection}/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an object permanently
      effect: destructive
      questions:
      - How do I permanently remove an object from a collection?
      - Can a deleted object be recovered?
      instructions:
      - text: Delete object {id} from collection {collection}.
        slots:
          id: path.id
          collection: path.collection
      - text: Permanently remove {collection}/{id}.
        slots:
          collection: path.collection
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/objects/{collection}'].get
  update:
    x-apievangelist-phrasing:
      intent: List objects in a collection
      effect: read
      questions:
      - Which objects exist in a given collection?
      - Can I include preferences when listing a collection's objects?
      instructions:
      - text: List objects in collection {collection}.
        slots:
          collection: path.collection
      - text: List {collection} objects including {include}.
        slots:
          collection: path.collection
          include: query.include[]
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/objects/{collection}/{object_id}/preferences/{id}/channel_types'].put
  update:
    x-apievangelist-phrasing:
      intent: Update all channel types in an object's preferences
      effect: write
      questions:
      - How do I set every channel type preference on an object at once?
      - Can I replace an object's email, SMS and push settings together?
      instructions:
      - text: Replace the channel types section of preference set {id} for object {object_id} in {collection}.
        slots:
          collection: path.collection
          object_id: path.object_id
          id: path.id
      - text: Update every channel type setting at once on {collection}/{object_id}'s preference set {id}.
        slots:
          collection: path.collection
          object_id: path.object_id
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/objects/{collection}/bulk/subscriptions/delete'].post
  update:
    x-apievangelist-phrasing:
      intent: Remove subscriptions from many objects
      effect: destructive
      questions:
      - How do I unsubscribe recipients from many objects in one collection?
      - Are missing subscriptions skipped during a bulk delete?
      instructions:
      - text: Bulk delete subscriptions {subscriptions} in collection {collection}.
        slots:
          subscriptions: requestBody.subscriptions
          collection: path.collection
      - text: Unsubscribe recipients across {collection} objects using {subscriptions}.
        slots:
          collection: path.collection
          subscriptions: requestBody.subscriptions
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/objects/{collection}/{object_id}/preferences/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one of an object's preference sets
      effect: read
      questions:
      - How do I see an object's default preference set?
      - Can I read one specific preference set on an object?
      instructions:
      - text: Get preference set {id} for object {object_id} in {collection}.
        slots:
          object_id: path.object_id
          collection: path.collection
          id: path.id
      - text: Show the {id} preferences of {collection}/{object_id}.
        slots:
          object_id: path.object_id
          collection: path.collection
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/objects/{collection}/{object_id}/preferences/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace or merge an object's preference set
      effect: write
      questions:
      - How do I set all of an object's preferences in one call?
      - Can I merge new preferences instead of replacing the whole set?
      instructions:
      - text: Update preference set {id} for object {object_id} in {collection}.
        slots:
          object_id: path.object_id
          collection: path.collection
          id: path.id
      - text: Set {collection}/{object_id}'s {id} preferences with workflows {workflows}.
        slots:
          object_id: path.object_id
          collection: path.collection
          id: path.id
          workflows: requestBody.workflows
      - text: Merge into preference set {id} for {collection}/{object_id} using strategy {strategy}.
        slots:
          object_id: path.object_id
          collection: path.collection
          id: path.id
          strategy: requestBody.__persistence_strategy__
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/objects/{collection}/{object_id}/preferences/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an object's preference set
      effect: destructive
      questions:
      - How do I remove a preference set from an object entirely?
      - Can I unset an object's per-tenant preferences?
      instructions:
      - text: Delete preference set {id} for object {object_id} in {collection}.
        slots:
          object_id: path.object_id
          collection: path.collection
          id: path.id
      - text: Unset the {id} preferences on {collection}/{object_id}.
        slots:
          object_id: path.object_id
          collection: path.collection
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/objects/{collection}/bulk/set'].post
  update:
    x-apievangelist-phrasing:
      intent: Create or update many objects
      effect: write
      questions:
      - How do I upsert up to 1,000 objects into a collection at once?
      - Can I sync a whole collection of objects in one batch?
      instructions:
      - text: Bulk set objects {objects} in collection {collection}.
        slots:
          objects: requestBody.objects
          collection: path.collection
      - text: 'Create or update these {collection} objects in one go: {objects}.'
        slots:
          collection: path.collection
          objects: requestBody.objects
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/schedules/bulk/create'].post
  update:
    x-apievangelist-phrasing:
      intent: Create many schedules at once
      effect: write
      questions:
      - How do I create a large number of workflow schedules in one request?
      - Is there a cap on schedules per bulk create?
      instructions:
      - text: Bulk create schedules {schedules}.
        slots:
          schedules: requestBody.schedules
      - text: Create up to 1,000 schedules from {schedules} in one batch.
        slots:
          schedules: requestBody.schedules
      method: generated
      generated: '2026-10-01'