# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for One Connections API
  version: 1.0.0
extends: openapi/integration-os-connections-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: 14
- target: $.paths['/v1/connections'].get
  update:
    x-apievangelist-phrasing:
      intent: List my connections
      effect: read
      questions:
      - Which connected accounts do I have in my current scope?
      - Can I list connections for an organization or project tenant by passing its ID as a header?
      instructions:
      - text: List my connections.
      - text: List connections in project tenant {project}, page {page}.
        slots:
          project: header.X-One-Project-Id
          page: query.page
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/connections/metrics'].get
  update:
    x-apievangelist-phrasing:
      intent: Get connection usage metrics
      effect: read
      questions:
      - How many connections do I have, and what do the connection metrics show?
      - Is there a summary count of connections I can pull for a dashboard?
      instructions:
      - text: Show my connection metrics.
      - text: Fetch the connection counts summary for a dashboard.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/connections/organizations/{org_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: List an organization's connections
      effect: read
      questions:
      - Which connections belong to a specific organization?
      - Can I page through all organization-level connections?
      instructions:
      - text: List the connections in organization {org_id}.
        slots:
          org_id: path.org_id
      - text: Show page {page} of organization {org_id}'s connections, {limit} at a time.
        slots:
          page: query.page
          org_id: path.org_id
          limit: query.limit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/connections/organizations/{org_id}/projects/{project_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: List a project's connections
      effect: read
      questions:
      - What connections exist inside one project of my organization?
      - Can I list a project's connections a page at a time?
      instructions:
      - text: List the connections in project {project_id} of org {org_id}.
        slots:
          project_id: path.project_id
          org_id: path.org_id
      - text: Show page {page} of project {project_id} connections in organization {org_id}.
        slots:
          page: query.page
          project_id: path.project_id
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/connections/organizations/{org_id}/projects/{project_id}/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a connection within a project
      effect: read
      questions:
      - How do I fetch one connection that belongs to a project by its ID?
      - Can I view a project connection's record through the project path?
      instructions:
      - text: Get connection {id} in project {project_id}, org {org_id}.
        slots:
          id: path.id
          project_id: path.project_id
          org_id: path.org_id
      - text: Show project {project_id}'s connection record {id} under organization {org_id}.
        slots:
          project_id: path.project_id
          id: path.id
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/connections/organizations/{org_id}/projects/{project_id}/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a connection from a project
      effect: destructive
      questions:
      - How do I remove a connected account from one project?
      - Can I delete a project's connection through the project-scoped path?
      instructions:
      - text: Delete connection {id} from project {project_id} in org {org_id}.
        slots:
          id: path.id
          project_id: path.project_id
          org_id: path.org_id
      - text: Remove project {project_id}'s connection {id} under organization {org_id}.
        slots:
          project_id: path.project_id
          id: path.id
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/connections/organizations/{org_id}/projects/{project_id}/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename or retag a project connection
      effect: write
      questions:
      - Can I change the tags on a connection that lives in a project?
      - How do I give a project connection a new display name?
      instructions:
      - text: Set tags {tags} on connection {id} in project {project_id}, org {org_id}.
        slots:
          tags: requestBody.tags
          id: path.id
          project_id: path.project_id
          org_id: path.org_id
      - text: Rename project {project_id} connection {id} to {name} in organization {org_id}.
        slots:
          project_id: path.project_id
          id: path.id
          name: requestBody.name
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/connections/organizations/{org_id}/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a connection within an organization
      effect: read
      questions:
      - How do I fetch one organization-level connection by ID?
      - Can I view an org connection's record without going through a project?
      instructions:
      - text: Get connection {id} in organization {org_id}.
        slots:
          id: path.id
          org_id: path.org_id
      - text: Show organization {org_id}'s connection record {id}.
        slots:
          org_id: path.org_id
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/connections/organizations/{org_id}/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a connection from an organization
      effect: destructive
      questions:
      - How do I remove an organization-level connection?
      - Can an admin delete a connection owned by the organization rather than a project?
      instructions:
      - text: Delete connection {id} from organization {org_id}.
        slots:
          id: path.id
          org_id: path.org_id
      - text: Remove the org-level connection {id} in {org_id}.
        slots:
          id: path.id
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/connections/organizations/{org_id}/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename or retag an organization connection
      effect: write
      questions:
      - Can I retag a connection owned by my organization?
      - Does sending an empty name clear an organization connection's display name?
      instructions:
      - text: Set tags {tags} on connection {id} in organization {org_id}.
        slots:
          tags: requestBody.tags
          id: path.id
          org_id: path.org_id
      - text: Rename org {org_id} connection {id} to {name}.
        slots:
          org_id: path.org_id
          id: path.id
          name: requestBody.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/connections/reachable'].get
  update:
    x-apievangelist-phrasing:
      intent: List connections my grant can reach
      effect: read
      questions:
      - Which connections can my grant reach, including ones I can only run custom actions on?
      - What access label does each reachable connection carry for my credential?
      instructions:
      - text: List every connection my grant can reach, with its access label.
      - text: Show page {page} of reachable connections for my credential.
        slots:
          page: query.page
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/connections/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a connection by ID
      effect: read
      questions:
      - How do I look up a single connection by its ID in my current scope?
      - Can I fetch a connection directly without specifying an organization path?
      instructions:
      - text: Get connection {id}.
        slots:
          id: path.id
      - text: Fetch connection {id} acting in organization tenant {org}.
        slots:
          id: path.id
          org: header.X-One-Organization-Id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/connections/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a connection by ID
      effect: destructive
      questions:
      - How do I delete a connection in my current scope using only its ID?
      - Can I remove a connected account without going through the organization or project paths?
      instructions:
      - text: Delete connection {id}.
        slots:
          id: path.id
      - text: Remove connection {id} acting in project tenant {project}.
        slots:
          id: path.id
          project: header.X-One-Project-Id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/connections/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename or retag a connection by ID
      effect: write
      questions:
      - Can I change a connection's tags using just its ID?
      - Are a connection's tags left alone if I only send a new name?
      instructions:
      - text: Set the tags on connection {id} to {tags}.
        slots:
          id: path.id
          tags: requestBody.tags
      - text: Rename connection {id} to {name}.
        slots:
          id: path.id
          name: requestBody.name
      method: generated
      generated: '2026-10-01'