# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for One Vault API
  version: 1.0.0
extends: openapi/integration-os-vault-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: 8
- target: $.paths['/v1/vault/connections'].get
  update:
    x-apievangelist-phrasing:
      intent: List the connections I can access
      effect: read
      questions:
      - Which connected accounts can my current key see in the vault?
      - Can I filter my vault connections by platform or by the end user's email?
      - How do I find connections carrying a particular tag?
      instructions:
      - text: List page {page} of the vault connections my key can see.
        slots:
          page: query.page
      - text: Find vault connections for identity {identity} on platform {platform}, page {page}.
        slots:
          identity: query.identity
          platform: query.platform
          page: query.page
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/vault/connections/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one connection from the vault
      effect: read
      questions:
      - What are the details of a single connection stored in the vault?
      - Can I look up a vault connection by ID using whatever scope my key has?
      instructions:
      - text: Get vault connection {id}.
        slots:
          id: path.id
      - text: Show the stored details for connection {id} within my key's scope.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/vault/connections/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a connection and its credentials
      effect: destructive
      questions:
      - How do I permanently remove a connected account and its stored credentials?
      - What happens to actions and passthrough calls after a vault connection is deleted?
      instructions:
      - text: Delete vault connection {id} and its stored credentials.
        slots:
          id: path.id
      - text: Permanently remove connection {id} from the vault.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/vault/connections/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename or retag a vault connection
      effect: write
      questions:
      - Can I replace the tags on a vault connection, and are tags I leave out removed?
      - How do I give a stored connection a friendlier display name?
      instructions:
      - text: Set the tags on vault connection {id} to {tags}.
        slots:
          id: path.id
          tags: requestBody.tags
      - text: Rename vault connection {id} to {name}.
        slots:
          id: path.id
          name: requestBody.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/vault/organizations/{org_id}/connections'].get
  update:
    x-apievangelist-phrasing:
      intent: List every connection in an organization
      effect: read
      questions:
      - As an admin, how do I see every connection across my organization regardless of project?
      - Can I filter an organization's vault connections by identity type?
      instructions:
      - text: List page {page} of vault connections across organization {org_id}.
        slots:
          page: query.page
          org_id: path.org_id
      - text: Show organization {org_id} connections tagged {tags}, page {page}.
        slots:
          org_id: path.org_id
          tags: query.tags
          page: query.page
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/vault/organizations/{org_id}/connections/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one connection in an organization
      effect: read
      questions:
      - What platform, identity and status does a particular organization connection have?
      - Can I fetch a single org-level connection by ID?
      instructions:
      - text: Get connection {id} in organization {org_id}'s vault.
        slots:
          id: path.id
          org_id: path.org_id
      - text: Show the status and tags of org {org_id} vault connection {id}.
        slots:
          org_id: path.org_id
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/vault/organizations/{org_id}/projects/{project_id}/connections'].get
  update:
    x-apievangelist-phrasing:
      intent: List the connections inside one project
      effect: read
      questions:
      - How do I narrow the vault to the connections of just one project?
      - Can I filter a project's connections by platform or connection key?
      instructions:
      - text: List page {page} of vault connections in project {project_id}, org {org_id}.
        slots:
          page: query.page
          project_id: path.project_id
          org_id: path.org_id
      - text: Show project {project_id} connections on platform {platform} in org {org_id}, page {page}.
        slots:
          project_id: path.project_id
          platform: query.platform
          org_id: path.org_id
          page: query.page
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/vault/organizations/{org_id}/projects/{project_id}/connections/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one connection inside a project
      effect: read
      questions:
      - What are the details of a specific connection that lives in a project?
      - Can I fetch a project-level vault connection by its ID?
      instructions:
      - text: Get vault 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 the project {project_id} vault record for connection {id} in organization {org_id}.
        slots:
          project_id: path.project_id
          id: path.id
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'