# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Confluence Cloud REST Relation API
  version: 1.0.0
extends: openapi/confluence-relation-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: 5
- target: $.paths['/wiki/rest/api/relation/{relationName}/from/{sourceType}/{sourceKey}/to/{targetType}'].get
  update:
    x-apievangelist-phrasing:
      intent: Find what an entity is related to
      effect: read
      questions:
      - How do I list all the pages a user has marked as favourite?
      - Which content does a given user have an 'ignore' relationship with?
      instructions:
      - text: Find all {targetType} that {sourceType} {sourceKey} has a {relationName} relationship to.
        slots:
          targetType: path.targetType
          sourceType: path.sourceType
          sourceKey: path.sourceKey
          relationName: path.relationName
      - text: List the {targetType} items user {sourceKey} marked as {relationName}, source type {sourceType}.
        slots:
          targetType: path.targetType
          sourceKey: path.sourceKey
          relationName: path.relationName
          sourceType: path.sourceType
      method: generated
      generated: '2026-10-01'
- target: $.paths['/wiki/rest/api/relation/{relationName}/from/{sourceType}/{sourceKey}/to/{targetType}/{targetKey}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check if a relationship exists between two entities
      effect: read
      questions:
      - Has a user favourited a specific page?
      - Can I check whether one particular relationship exists from a source to a target?
      instructions:
      - text: Check whether {sourceType} {sourceKey} has a {relationName} relationship to {targetType} {targetKey}.
        slots:
          sourceType: path.sourceType
          sourceKey: path.sourceKey
          relationName: path.relationName
          targetType: path.targetType
          targetKey: path.targetKey
      - text: Tell me if {sourceType} {sourceKey} has favourited {targetType} {targetKey} via relation {relationName}.
        slots:
          sourceType: path.sourceType
          sourceKey: path.sourceKey
          targetType: path.targetType
          targetKey: path.targetKey
          relationName: path.relationName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/wiki/rest/api/relation/{relationName}/from/{sourceType}/{sourceKey}/to/{targetType}/{targetKey}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create a relationship such as a favourite
      effect: write
      questions:
      - How do I mark a page as a favourite for a user through the API?
      - Can I define my own custom relationship type between a user and a space?
      instructions:
      - text: Create a {relationName} relationship from {sourceType} {sourceKey} to {targetType} {targetKey}.
        slots:
          relationName: path.relationName
          sourceType: path.sourceType
          sourceKey: path.sourceKey
          targetType: path.targetType
          targetKey: path.targetKey
      - text: Favourite {targetType} {targetKey} for {sourceType} {sourceKey} using relation {relationName}.
        slots:
          targetType: path.targetType
          targetKey: path.targetKey
          sourceType: path.sourceType
          sourceKey: path.sourceKey
          relationName: path.relationName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/wiki/rest/api/relation/{relationName}/from/{sourceType}/{sourceKey}/to/{targetType}/{targetKey}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a relationship between two entities
      effect: destructive
      questions:
      - How do I unfavourite a page for a user?
      - Can I delete a custom relationship between a user and content?
      instructions:
      - text: Delete the {relationName} relationship from {sourceType} {sourceKey} to {targetType} {targetKey}.
        slots:
          relationName: path.relationName
          sourceType: path.sourceType
          sourceKey: path.sourceKey
          targetType: path.targetType
          targetKey: path.targetKey
      - text: Unfavourite {targetType} {targetKey} for {sourceType} {sourceKey}, relation {relationName}.
        slots:
          targetType: path.targetType
          targetKey: path.targetKey
          sourceType: path.sourceType
          sourceKey: path.sourceKey
          relationName: path.relationName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/wiki/rest/api/relation/{relationName}/to/{targetType}/{targetKey}/from/{sourceType}'].get
  update:
    x-apievangelist-phrasing:
      intent: Find who is related to a target entity
      effect: read
      questions:
      - Which users have a 'collaborator' relationship to a page?
      - Who has favourited a particular piece of content?
      instructions:
      - text: Find all {sourceType} with a {relationName} relationship to {targetType} {targetKey}.
        slots:
          sourceType: path.sourceType
          relationName: path.relationName
          targetType: path.targetType
          targetKey: path.targetKey
      - text: List the {sourceType} who marked {targetType} {targetKey} as {relationName}.
        slots:
          sourceType: path.sourceType
          targetType: path.targetType
          targetKey: path.targetKey
          relationName: path.relationName
      method: generated
      generated: '2026-10-01'