# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Boom CDP Relationships API
  version: 1.0.0
extends: openapi/boom-ai-cdp-relationships-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: 7
- target: $.paths['/api/v1/cdp/relationship-types'].get
  update:
    x-apievangelist-phrasing:
      intent: List relationship types
      effect: read
      questions:
      - Which relationship types are defined, so I know how people and objects can be linked?
      - What link shapes are valid before I connect a person to an order?
      instructions:
      - text: List my relationship types.
      - text: Show every valid relationship type in the CDP.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/cdp/relationship-types'].post
  update:
    x-apievangelist-phrasing:
      intent: Register a relationship type
      effect: write
      questions:
      - How do I define that a person places orders, or that an order has line items?
      - Can I set the cardinality of a relationship, such as one-to-many?
      - What happens if I register a relationship type that already exists?
      instructions:
      - text: Register a {kind} relationship type with role {role} to object type {customObjectType}.
        slots:
          kind: requestBody.kind
          role: requestBody.role
          customObjectType: requestBody.customObjectType
      - text: Register role {role} linking parent {parentCustomObjectType} to child {childCustomObjectType} as {kind} with cardinality {cardinality}.
        slots:
          kind: requestBody.kind
          role: requestBody.role
          parentCustomObjectType: requestBody.parentCustomObjectType
          childCustomObjectType: requestBody.childCustomObjectType
          cardinality: requestBody.cardinality
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/cdp/relationship-types/{relationshipTypeId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Read one relationship type
      effect: read
      questions:
      - What role and object types does a specific relationship type connect?
      - Can I check the cardinality of one relationship type by its id?
      instructions:
      - text: Get relationship type {relationshipTypeId}.
        slots:
          relationshipTypeId: path.relationshipTypeId
      - text: Show the definition of relationship type {relationshipTypeId}.
        slots:
          relationshipTypeId: path.relationshipTypeId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/cdp/relationships'].get
  update:
    x-apievangelist-phrasing:
      intent: List relationship links for a person or object
      effect: read
      questions:
      - Which orders or other objects is a given person linked to?
      - Can I include links that were removed when listing relationships?
      instructions:
      - text: List the {kind} links for person {personExternalId}.
        slots:
          kind: query.kind
          personExternalId: query.personExternalId
      - text: Show {kind} relationships anchored on {customObjectType} {customObjectExternalId}.
        slots:
          kind: query.kind
          customObjectType: query.customObjectType
          customObjectExternalId: query.customObjectExternalId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/cdp/relationships'].post
  update:
    x-apievangelist-phrasing:
      intent: Link a person or object to an object
      effect: write
      questions:
      - How do I connect a single person to an order they placed?
      - Can I link a parent custom object to a child one, such as an order to a line item?
      instructions:
      - text: Link person {personExternalId} to object {customObjectExternalId} via relationship type {relationshipTypeId}.
        slots:
          relationshipTypeId: requestBody.relationshipTypeId
          personExternalId: requestBody.personExternalId
          customObjectExternalId: requestBody.customObjectExternalId
      - text: Connect parent {parentExternalId} to child {childExternalId} using relationship type {relationshipTypeId}.
        slots:
          relationshipTypeId: requestBody.relationshipTypeId
          parentExternalId: requestBody.parentExternalId
          childExternalId: requestBody.childExternalId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/cdp/relationships'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unlink a relationship
      effect: destructive
      questions:
      - How do I remove the link between one person and a custom object?
      - Is unlinking a relationship permanent or a soft delete?
      instructions:
      - text: Unlink person {personExternalId} from object {customObjectExternalId} for relationship type {relationshipTypeId}.
        slots:
          relationshipTypeId: query.relationshipTypeId
          personExternalId: query.personExternalId
          customObjectExternalId: query.customObjectExternalId
      - text: Remove the {relationshipTypeId} link between parent {parentExternalId} and child {childExternalId}.
        slots:
          relationshipTypeId: query.relationshipTypeId
          parentExternalId: query.parentExternalId
          childExternalId: query.childExternalId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/cdp/relationships/batch'].post
  update:
    x-apievangelist-phrasing:
      intent: Bulk link or unlink relationships
      effect: write
      questions:
      - Can I link and unlink many relationships in one request?
      - What is the maximum number of relationship changes per bulk call?
      instructions:
      - text: 'Apply these relationship links and unlinks in bulk: {items}.'
        slots:
          items: requestBody.items
      - text: 'Batch-process up to 1000 relationship changes: {items}.'
        slots:
          items: requestBody.items
      method: generated
      generated: '2026-09-26'