# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Service Management Public REST Organization API
  version: 1.0.0
extends: openapi/jira-organization-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: 14
- target: $.paths['/rest/servicedeskapi/organization'].get
  update:
    x-apievangelist-phrasing:
      intent: List all organizations in Service Management
      effect: read
      questions:
      - What customer organizations exist across my whole Jira Service Management instance?
      - Can I find which organizations a particular customer account belongs to?
      - How do I look up an organization by name across the entire instance?
      instructions:
      - text: List every organization in the Service Management instance.
      - text: Show the organizations that user {accountId} belongs to, instance-wide.
        slots:
          accountId: query.accountId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/organization'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a customer organization
      effect: write
      questions:
      - How do I create a new customer organization in the service desk?
      - Is there a length limit on an organization's name?
      instructions:
      - text: Create an organization called {name}.
        slots:
          name: requestBody.name
      - text: Set up a new customer organization named {name}.
        slots:
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/organization/{organizationId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an organization's details
      effect: read
      questions:
      - What are the details of a specific customer organization?
      - Can I look up an organization's name from its ID?
      instructions:
      - text: Show the details of organization {organizationId}.
        slots:
          organizationId: path.organizationId
      - text: Get the name of organization {organizationId}.
        slots:
          organizationId: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/organization/{organizationId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a customer organization
      effect: destructive
      questions:
      - How do I delete a customer organization entirely?
      - Does deleting an organization also remove its links to service desks?
      instructions:
      - text: Delete organization {organizationId}.
        slots:
          organizationId: path.organizationId
      - text: Permanently remove customer organization {organizationId} from the instance.
        slots:
          organizationId: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/organization/{organizationId}/property'].get
  update:
    x-apievangelist-phrasing:
      intent: List an organization's property keys
      effect: read
      questions:
      - What custom properties has my app stored against an organization?
      - Can I list the property keys set on an organization?
      instructions:
      - text: List the property keys on organization {organizationId}.
        slots:
          organizationId: path.organizationId
      - text: Show which entity properties are stored for organization {organizationId}.
        slots:
          organizationId: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/organization/{organizationId}/property/{propertyKey}'].get
  update:
    x-apievangelist-phrasing:
      intent: Read an organization property value
      effect: read
      questions:
      - How do I read the JSON stored in one organization property?
      - What value does a given property key hold for an organization?
      instructions:
      - text: Get property {propertyKey} of organization {organizationId}.
        slots:
          propertyKey: path.propertyKey
          organizationId: path.organizationId
      - text: Show the JSON value of {propertyKey} on organization {organizationId}.
        slots:
          propertyKey: path.propertyKey
          organizationId: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/organization/{organizationId}/property/{propertyKey}'].put
  update:
    x-apievangelist-phrasing:
      intent: Store custom data on an organization
      effect: write
      questions:
      - How can my app store custom data against a customer organization?
      - What's the maximum length of an organization property key?
      instructions:
      - text: Set property {propertyKey} on organization {organizationId}.
        slots:
          propertyKey: path.propertyKey
          organizationId: path.organizationId
      - text: Save custom data under key {propertyKey} for organization {organizationId}.
        slots:
          propertyKey: path.propertyKey
          organizationId: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/organization/{organizationId}/property/{propertyKey}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove an organization property
      effect: destructive
      questions:
      - How do I delete custom data stored on an organization?
      - Can I remove one property key from an organization?
      instructions:
      - text: Delete property {propertyKey} from organization {organizationId}.
        slots:
          propertyKey: path.propertyKey
          organizationId: path.organizationId
      - text: Remove the {propertyKey} entity property on organization {organizationId}.
        slots:
          propertyKey: path.propertyKey
          organizationId: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/organization/{organizationId}/user'].get
  update:
    x-apievangelist-phrasing:
      intent: List users in an organization
      effect: read
      questions:
      - Which customers belong to a given organization?
      - Can I check whether a user is part of an organization?
      instructions:
      - text: List the users in organization {organizationId}.
        slots:
          organizationId: path.organizationId
      - text: Show up to {limit} members of organization {organizationId}.
        slots:
          limit: query.limit
          organizationId: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/organization/{organizationId}/user'].post
  update:
    x-apievangelist-phrasing:
      intent: Add customers to an organization
      effect: write
      questions:
      - How do I add customers to an organization?
      - Can I add several users to an organization by account ID in one go?
      instructions:
      - text: Add users {accountIds} to organization {organizationId}.
        slots:
          accountIds: requestBody.accountIds
          organizationId: path.organizationId
      - text: Put customer {accountIds} into organization {organizationId}.
        slots:
          accountIds: requestBody.accountIds
          organizationId: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/organization/{organizationId}/user'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove customers from an organization
      effect: destructive
      questions:
      - How do I take a customer out of an organization?
      - Can I remove multiple users from an organization at once?
      instructions:
      - text: Remove users {accountIds} from organization {organizationId}.
        slots:
          accountIds: requestBody.accountIds
          organizationId: path.organizationId
      - text: Take customer {accountIds} out of organization {organizationId}.
        slots:
          accountIds: requestBody.accountIds
          organizationId: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/servicedesk/{serviceDeskId}/organization'].get
  update:
    x-apievangelist-phrasing:
      intent: List organizations linked to a service desk
      effect: read
      questions:
      - Which organizations are associated with one particular service desk?
      - Can I see which of a service desk's organizations a user belongs to?
      instructions:
      - text: List the organizations on service desk {serviceDeskId}.
        slots:
          serviceDeskId: path.serviceDeskId
      - text: Show organizations on service desk {serviceDeskId} that include user {accountId}.
        slots:
          serviceDeskId: path.serviceDeskId
          accountId: query.accountId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/servicedesk/{serviceDeskId}/organization'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an organization to a service desk
      effect: write
      questions:
      - How do I give an organization access to a service desk?
      - What happens if the organization is already on that service desk?
      instructions:
      - text: Add organization {organizationId} to service desk {serviceDeskId}.
        slots:
          organizationId: requestBody.organizationId
          serviceDeskId: path.serviceDeskId
      - text: Link service desk {serviceDeskId} with customer organization {organizationId}.
        slots:
          serviceDeskId: path.serviceDeskId
          organizationId: requestBody.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/servicedeskapi/servicedesk/{serviceDeskId}/organization'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove an organization from a service desk
      effect: destructive
      questions:
      - How do I detach an organization from a service desk without deleting it?
      - Does removing an unlinked organization from a service desk cause an error?
      instructions:
      - text: Remove organization {organizationId} from service desk {serviceDeskId}.
        slots:
          organizationId: requestBody.organizationId
          serviceDeskId: path.serviceDeskId
      - text: Unlink customer organization {organizationId} from service desk {serviceDeskId}.
        slots:
          organizationId: requestBody.organizationId
          serviceDeskId: path.serviceDeskId
      method: generated
      generated: '2026-09-26'