Ada · OpenAPI Overlay 1.0.0

API Evangelist conversational phrasing for Knowledge Platform Integrations API

6 actions 6 updates phrasing extends openapi/ada-platformintegrations-api-openapi.yml

Generated by API Evangelist Written by API Evangelist tooling for Ada's API. It is a proposal applied on top of the contract, not a document Ada publishes.

View Overlay File View on GitHub Overlay Specification

What the actions change

x-apievangelist-phrasing

Targets 6

$.info

$.paths['/v2/platform-integrations/'].get

$.paths['/v2/platform-integrations/'].post

$.paths['/v2/platform-integrations/{id}'].patch

$.paths['/v2/platform-integrations/{id}/installations/self'].get

$.paths['/v2/platform-integrations/{platform_integration_id}/installations/{installation_id}'].patch

OpenAPI Overlay

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Knowledge Platform Integrations API
  version: 1.0.0
extends: openapi/ada-platformintegrations-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: 5
- target: $.paths['/v2/platform-integrations/'].get
  update:
    x-apievangelist-phrasing:
      intent: List my platform integrations
      effect: read
      questions:
      - Which platform integrations has my developer account built?
      - Can I page through the integrations I own?
      instructions:
      - text: List my platform integrations.
      - text: Show {limit} of my integrations after {cursor}.
        slots:
          limit: query.limit
          cursor: query.cursor
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/platform-integrations/'].post
  update:
    x-apievangelist-phrasing:
      intent: Register a new platform integration
      effect: write
      questions:
      - How do I build and register an integration for the Ada platform?
      - What status does a newly created integration start in?
      - Which OAuth scopes and settings fields must a new integration declare?
      instructions:
      - text: Create integration {name} by {author}, described as {description}, with scopes {scopes}.
        slots:
          name: requestBody.name
          author: requestBody.author
          description: requestBody.description
          scopes: requestBody.scopes
      - text: Register integration {name} with OAuth callback {oauth_callback_url} and uninstall URL {uninstallation_url}.
        slots:
          name: requestBody.name
          oauth_callback_url: requestBody.oauth_callback_url
          uninstallation_url: requestBody.uninstallation_url
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/platform-integrations/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Edit an integration still in development
      effect: write
      questions:
      - How do I change the details of an integration I'm still developing?
      - Can I edit an integration after submitting it for publication?
      instructions:
      - text: Update integration {id} description to {description}.
        slots:
          id: path.id
          description: requestBody.description
      - text: Change the OAuth callback URL of integration {id} to {oauth_callback_url}.
        slots:
          id: path.id
          oauth_callback_url: requestBody.oauth_callback_url
      - text: Replace the requested scopes on integration {id} with {scopes}.
        slots:
          id: path.id
          scopes: requestBody.scopes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/platform-integrations/{id}/installations/self'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the installation behind my access token
      effect: read
      questions:
      - How does my integration read the configuration an admin filled in on install?
      - Can I see the installation details tied to the current access token?
      instructions:
      - text: Get my installation of integration {id}.
        slots:
          id: path.id
      - text: Show the admin's configuration form answers for integration {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/platform-integrations/{platform_integration_id}/installations/{installation_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Mark an installation complete or incomplete
      effect: write
      questions:
      - How do I tell Ada an installation of my integration finished setup?
      - Can I flag an installation as incomplete?
      instructions:
      - text: Set installation {installation_id} of integration {platform_integration_id} to {status}.
        slots:
          installation_id: path.installation_id
          platform_integration_id: path.platform_integration_id
          status: requestBody.status
      - text: Mark installation {installation_id} of integration {platform_integration_id} as complete.
        slots:
          installation_id: path.installation_id
          platform_integration_id: path.platform_integration_id
      method: generated
      generated: '2026-09-26'