# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Authorization API v1.1 Resource Info and Management API
  version: 1.0.0
extends: openapi/here-resource-info-and-management-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: 13
- target: $.paths['/resources'].get
  update:
    x-apievangelist-phrasing:
      intent: List resources of a type I can see
      effect: read
      questions:
      - Which catalogs or pipelines am I allowed to see on the platform?
      - Can I list only resources that are linkable or referenceable?
      instructions:
      - text: List resources of type {type} that I can see.
        slots:
          type: query.type
      - text: Show linkable resources of type {type}.
        slots:
          type: query.type
      - text: List {type} resources I can access with {access} access.
        slots:
          type: query.type
          access: query.access
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realm/resources'].get
  update:
    x-apievangelist-phrasing:
      intent: List every resource in my realm
      effect: read
      questions:
      - How do I see all resources across my whole realm?
      - What permission do I need to list realm-wide resources?
      instructions:
      - text: List all resources in my realm.
      - text: Show every {type} resource in my realm.
        slots:
          type: query.type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/realm/externalResources'].get
  update:
    x-apievangelist-phrasing:
      intent: List external resources shared into my realm
      effect: read
      questions:
      - Which resources were made available to my realm through plans or policies?
      - Can I find external resources I'm allowed to take a given action on?
      instructions:
      - text: List external {type} resources in my realm that allow action {action}.
        slots:
          type: query.type
          action: query.action
      - text: Show resources shared into my realm of type {type} where I can {action}.
        slots:
          type: query.type
          action: query.action
      method: generated
      generated: '2026-09-26'
- target: $.paths['/resourceTypes/{resourceType}/actions'].get
  update:
    x-apievangelist-phrasing:
      intent: List the actions for a resource type
      effect: read
      questions:
      - What actions can be granted on a catalog resource type?
      - Where do I find the permission actions supported by a resource type?
      instructions:
      - text: List the actions available for resource type {resource_type}.
        slots:
          resource_type: path.resourceType
      - text: Show {type} actions for resource type {resource_type}.
        slots:
          resource_type: path.resourceType
          type: query.type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/resources/{resource}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a single resource
      effect: read
      questions:
      - How can I look up one resource by its HRN?
      - Does fetching a resource behave differently with a project-scoped token?
      instructions:
      - text: Get resource {resource} with referenceable set to {referenceable}.
        slots:
          resource: path.resource
          referenceable: query.referenceable
      - text: Show the details of resource {resource}.
        slots:
          resource: path.resource
      method: generated
      generated: '2026-09-26'
- target: $.paths['/resources/{resource}/settings'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a resource's policy settings
      effect: read
      questions:
      - Is my resource available to be added to resource policies?
      - What are the current settings on a resource?
      instructions:
      - text: Show the settings of resource {resource}.
        slots:
          resource: path.resource
      - text: Check the resource policy availability of {resource}.
        slots:
          resource: path.resource
      method: generated
      generated: '2026-09-26'
- target: $.paths['/resources/{resource}/settings'].put
  update:
    x-apievangelist-phrasing:
      intent: Set a resource's policy availability
      effect: write
      questions:
      - Can I stop a resource from being added to resource policies?
      - How do I change a resource's policy availability setting?
      instructions:
      - text: Set the resource policy availability of {resource} to {availability}.
        slots:
          resource: path.resource
          availability: requestBody.resourcePolicyAvailability
      - text: Update the settings on resource {resource} with availability {availability}.
        slots:
          resource: path.resource
          availability: requestBody.resourcePolicyAvailability
      method: generated
      generated: '2026-09-26'
- target: $.paths['/resources/{resource}/projects'].get
  update:
    x-apievangelist-phrasing:
      intent: List projects a resource belongs to or is linked in
      effect: read
      questions:
      - Which projects is this resource home to or linked into?
      - Can I include cross-realm projects when listing where a resource is used?
      instructions:
      - text: List the projects resource {resource} belongs to or is linked in.
        slots:
          resource: path.resource
      - text: Show projects for resource {resource} with relation {relation}.
        slots:
          resource: path.resource
          relation: query.relation
      - text: List projects using {resource} including cross-realm projects {cross_realm}.
        slots:
          resource: path.resource
          cross_realm: query.includeCrossRealmProjects
      method: generated
      generated: '2026-09-26'
- target: $.paths['/resources/{resource}/linkable'].get
  update:
    x-apievangelist-phrasing:
      intent: List ways a resource has been made linkable
      effect: read
      questions:
      - In which projects or realms has my resource been made linkable?
      - How do I review all linkability listings on a resource?
      instructions:
      - text: List all the ways resource {resource} has been made linkable.
        slots:
          resource: path.resource
      - text: Show every linkability listing for {resource}.
        slots:
          resource: path.resource
      method: generated
      generated: '2026-09-26'
- target: $.paths['/resources/{resource}/linkable'].post
  update:
    x-apievangelist-phrasing:
      intent: Make a resource linkable to a project or realm
      effect: write
      questions:
      - How do I let another project link to my resource?
      - Can I make a resource linkable to my whole realm with limited actions?
      instructions:
      - text: Make resource {resource} linkable to project {project_hrn} with actions {allowed_actions}.
        slots:
          resource: path.resource
          project_hrn: requestBody.projectHrn
          allowed_actions: requestBody.allowedActions
      - text: Make {resource} linkable to realm {realm_hrn} allowing {allowed_actions}.
        slots:
          resource: path.resource
          realm_hrn: requestBody.realmHrn
          allowed_actions: requestBody.allowedActions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/resources/{resource}/linkable/{linkableToHrn}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a resource's linkability to one project or realm
      effect: read
      questions:
      - Is my resource currently linkable to a specific project?
      - What actions are allowed when linking this resource to a given realm?
      instructions:
      - text: Get the linkability of resource {resource} to {linkable_to_hrn}.
        slots:
          resource: path.resource
          linkable_to_hrn: path.linkableToHrn
      - text: Check whether {resource} can be linked from {linkable_to_hrn}.
        slots:
          resource: path.resource
          linkable_to_hrn: path.linkableToHrn
      method: generated
      generated: '2026-09-26'
- target: $.paths['/resources/{resource}/linkable/{linkableToHrn}'].put
  update:
    x-apievangelist-phrasing:
      intent: Change the allowed actions on a linkability
      effect: write
      questions:
      - Can I change which actions a project gets when linking my resource?
      - How do I update an existing linkability listing?
      instructions:
      - text: Update the linkability of {resource} to {linkable_to_hrn} with actions {allowed_actions}.
        slots:
          resource: path.resource
          linkable_to_hrn: path.linkableToHrn
          allowed_actions: requestBody.allowedActions
      - text: Change allowed actions for linking {resource} from {linkable_to_hrn} to {allowed_actions}.
        slots:
          resource: path.resource
          linkable_to_hrn: path.linkableToHrn
          allowed_actions: requestBody.allowedActions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/resources/{resource}/linkable/{linkableToHrn}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Stop a resource being linkable to a project or realm
      effect: destructive
      questions:
      - Does removing linkability break links that already exist?
      - How do I stop a project from linking my resource going forward?
      instructions:
      - text: Remove the linkability of {resource} to {linkable_to_hrn}.
        slots:
          resource: path.resource
          linkable_to_hrn: path.linkableToHrn
      - text: Stop {linkable_to_hrn} from being able to link resource {resource}.
        slots:
          resource: path.resource
          linkable_to_hrn: path.linkableToHrn
      method: generated
      generated: '2026-09-26'