# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Atlassian The Confluence Cloud REST Relation API
  version: 1.0.0
extends: openapi/atlassian-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 entities a source is related to
      effect: read
      questions:
      - Which pages has a user marked as favourite in Confluence?
      - Can I list every space or page a user has a given relationship with?
      instructions:
      - text: Find all {targetType} entities that {sourceType} {sourceKey} has a {relationName} relationship with.
        slots:
          targetType: path.targetType
          sourceType: path.sourceType
          sourceKey: path.sourceKey
          relationName: path.relationName
      - text: List up to {limit} {targetType} items user {sourceKey} has marked {relationName}.
        slots:
          limit: query.limit
          targetType: path.targetType
          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}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check whether a relationship exists between two entities
      effect: read
      questions:
      - Has this user already favourited a specific Confluence page?
      - How do I test if one entity has a relationship to another?
      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 user {sourceKey} has {relationName} on {targetType} {targetKey}.
        slots:
          sourceKey: path.sourceKey
          relationName: path.relationName
          targetType: path.targetType
          targetKey: path.targetKey
      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 between two entities
      effect: write
      questions:
      - How do I favourite a Confluence page on behalf of a user?
      - 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: Mark {targetType} {targetKey} as {relationName} for user {sourceKey}.
        slots:
          targetType: path.targetType
          targetKey: path.targetKey
          relationName: path.relationName
          sourceKey: path.sourceKey
      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 Confluence user?
      - Can I delete a custom relationship between two entities?
      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: Remove {relationName} on {targetType} {targetKey} for user {sourceKey}.
        slots:
          relationName: path.relationName
          targetType: path.targetType
          targetKey: path.targetKey
          sourceKey: path.sourceKey
      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 entities related to a target entity
      effect: read
      questions:
      - Which users have favourited this Confluence page?
      - Who are the collaborators related to a piece of content?
      instructions:
      - text: Find all {sourceType} entities with a {relationName} relationship to {targetType} {targetKey}.
        slots:
          sourceType: path.sourceType
          relationName: path.relationName
          targetType: path.targetType
          targetKey: path.targetKey
      - text: List the users who marked {targetType} {targetKey} as {relationName}, up to {limit}.
        slots:
          targetType: path.targetType
          targetKey: path.targetKey
          relationName: path.relationName
          limit: query.limit
      method: generated
      generated: '2026-10-01'