# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Remote Companies API
  version: 1.0.0
extends: openapi/remote-com-companies-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: 6
- target: $.paths['/companies'].get
  update:
    x-apievangelist-phrasing:
      intent: List companies my token can access
      effect: read
      questions:
      - Which companies can my partner integration manage?
      - Can I page through the companies connected to my access token?
      instructions:
      - text: List all companies I have access to.
      - text: Show page {page} of my companies with {page_size} per page.
        slots:
          page: query.page
          page_size: query.page_size
      method: generated
      generated: '2026-09-26'
- target: $.paths['/companies'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new company on Remote
      effect: write
      questions:
      - How do I sign up a new customer company on Remote through the API?
      - Can a partner create a company and get a token to act on its behalf?
      instructions:
      - text: Create a company named {name} owned by {company_owner_email}.
        slots:
          name: requestBody.name
          company_owner_email: requestBody.company_owner_email
      - text: Set up company {name} for owner {company_owner_name} at {company_owner_email}, billed in {desired_currency}.
        slots:
          name: requestBody.name
          company_owner_name: requestBody.company_owner_name
          company_owner_email: requestBody.company_owner_email
          desired_currency: requestBody.desired_currency
      method: generated
      generated: '2026-09-26'
- target: $.paths['/companies/{company_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a company's details
      effect: read
      questions:
      - How do I look up a company's profile by its id?
      - What information does Remote hold about one of my companies?
      instructions:
      - text: Show company {company_id}.
        slots:
          company_id: path.company_id
      - text: Fetch the details of company {company_id}.
        slots:
          company_id: path.company_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/companies/{company_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a company's name, address or tax number
      effect: write
      questions:
      - Can I change a company's registered address or tax number?
      - How do I rename a company I already created?
      instructions:
      - text: Rename company {company_id} to {name}.
        slots:
          company_id: path.company_id
          name: requestBody.name
      - text: Set the tax number of company {company_id} to {tax_number}.
        slots:
          company_id: path.company_id
          tax_number: requestBody.tax_number
      method: generated
      generated: '2026-09-26'
- target: $.paths['/companies/{company_id}/legal_entities'].get
  update:
    x-apievangelist-phrasing:
      intent: List a company's hiring legal entities
      effect: read
      questions:
      - Which legal entities does my company hire people under?
      - What entities are registered for hiring under a given company?
      instructions:
      - text: List the legal entities for company {company_id}.
        slots:
          company_id: path.company_id
      - text: Show which entities company {company_id} hires through.
        slots:
          company_id: path.company_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/forms/{form_type}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the localized data form for a resource
      effect: read
      questions:
      - What country-specific fields does Remote require for a resource like an employment?
      - Where do I get the JSON Schema form Remote uses to collect localized data?
      instructions:
      - text: Fetch the JSON Schema form for {form_type}.
        slots:
          form_type: path.form_type
      - text: Show the localized field definitions for form type {form_type}.
        slots:
          form_type: path.form_type
      method: generated
      generated: '2026-09-26'