# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Composition API
  version: 1.0.0
extends: openapi/algolia-composition-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: 20
- target: $.paths['/{path}'].get
  update:
    x-apievangelist-phrasing:
      intent: Send a raw GET request to the Composition API
      effect: read
      questions:
      - Can I read a Composition endpoint that the client library doesn't wrap?
      - Is there a generic way to GET any Composition API path with custom query parameters?
      instructions:
      - text: Send a raw GET request to Composition API path {path}.
        slots:
          path: path.path
      - text: Fetch Composition path {path} with query parameters {parameters}.
        slots:
          path: path.path
          parameters: query.parameters
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{path}'].put
  update:
    x-apievangelist-phrasing:
      intent: Send a raw PUT request to the Composition API
      effect: write
      questions:
      - Can I send a custom PUT to a Composition path that has no dedicated method?
      - Is there a passthrough for PUT calls on an arbitrary Composition endpoint?
      instructions:
      - text: Send a raw PUT request to Composition API path {path}.
        slots:
          path: path.path
      - text: PUT to Composition path {path} with query parameters {parameters}.
        slots:
          path: path.path
          parameters: query.parameters
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{path}'].post
  update:
    x-apievangelist-phrasing:
      intent: Send a raw POST request to the Composition API
      effect: write
      questions:
      - Can I POST to a Composition endpoint the SDK doesn't expose as a method?
      - What's the generic escape hatch for posting to any Composition API path?
      instructions:
      - text: Send a raw POST request to Composition API path {path}.
        slots:
          path: path.path
      - text: POST to Composition path {path} with query parameters {parameters}.
        slots:
          path: path.path
          parameters: query.parameters
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{path}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Send a raw DELETE request to the Composition API
      effect: destructive
      questions:
      - Can I issue a DELETE against an arbitrary Composition API path?
      - Is there a generic delete call for Composition endpoints without a dedicated method?
      instructions:
      - text: Send a raw DELETE request to Composition API path {path}.
        slots:
          path: path.path
      - text: DELETE Composition path {path} with query parameters {parameters}.
        slots:
          path: path.path
          parameters: query.parameters
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1/compositions/{compositionID}/run'].post
  update:
    x-apievangelist-phrasing:
      intent: Run a search query against a composition
      effect: read
      questions:
      - How do I get search results from a composition instead of querying an index directly?
      - Can I control the order in which a composition's feeds come back?
      instructions:
      - text: Run a search on composition {compositionID} with parameters {params}.
        slots:
          compositionID: path.compositionID
          params: requestBody.params
      - text: Query composition {compositionID} and return feeds in order {feedsOrder}.
        slots:
          compositionID: path.compositionID
          feedsOrder: requestBody.feedsOrder
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1/compositions/{compositionID}/facets/{facetName}/query'].post
  update:
    x-apievangelist-phrasing:
      intent: Search facet values in a composition's main source
      effect: read
      questions:
      - How do I autocomplete brand names from a facet on my composition's main index?
      - Can I search within one facet's values instead of the records themselves?
      instructions:
      - text: Search values of facet {facetName} in composition {compositionID}.
        slots:
          facetName: path.facetName
          compositionID: path.compositionID
      - text: Find facet values of {facetName} in composition {compositionID} matching {params}.
        slots:
          facetName: path.facetName
          compositionID: path.compositionID
          params: requestBody.params
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1/compositions'].get
  update:
    x-apievangelist-phrasing:
      intent: List compositions in the application
      effect: read
      questions:
      - Which compositions exist in my Algolia application?
      - Can I page through my compositions a set number at a time?
      instructions:
      - text: List all compositions in my application.
      - text: Show page {page} of my compositions, {hitsPerPage} per page.
        slots:
          page: query.page
          hitsPerPage: query.hitsPerPage
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1/compositions/{compositionID}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one composition's configuration
      effect: read
      questions:
      - How do I see how a specific composition is configured?
      - What behavior and sorting strategy does one composition use?
      instructions:
      - text: Show composition {compositionID}.
        slots:
          compositionID: path.compositionID
      - text: Retrieve the full configuration of composition {compositionID}.
        slots:
          compositionID: path.compositionID
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1/compositions/{compositionID}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or replace a composition
      effect: write
      questions:
      - How do I create a new composition that blends results from my indices?
      - Can I overwrite an existing composition's name and behavior in one call?
      instructions:
      - text: Upsert composition {compositionID} named {name} with behavior {behavior}.
        slots:
          compositionID: path.compositionID
          name: requestBody.name
          behavior: requestBody.behavior
      - text: Create composition {compositionID} called {name}, described as {description}, with behavior {behavior}.
        slots:
          compositionID: path.compositionID
          name: requestBody.name
          description: requestBody.description
          behavior: requestBody.behavior
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1/compositions/{compositionID}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a composition
      effect: destructive
      questions:
      - How do I remove a composition I no longer use?
      - Can I delete a single composition by its ID?
      instructions:
      - text: Delete composition {compositionID}.
        slots:
          compositionID: path.compositionID
      - text: Remove composition {compositionID} from my application.
        slots:
          compositionID: path.compositionID
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1/compositions/*/batch'].post
  update:
    x-apievangelist-phrasing:
      intent: Add, update or delete many compositions at once
      effect: write
      questions:
      - How do I create and delete several compositions in a single request?
      - Can I batch changes across multiple compositions instead of calling them one by one?
      instructions:
      - text: 'Apply this batch of composition changes: {requests}.'
        slots:
          requests: requestBody.requests
      - text: Upsert and delete compositions in one batch using {requests}.
        slots:
          requests: requestBody.requests
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1/compositions/{compositionID}/sortingStrategy'].post
  update:
    x-apievangelist-phrasing:
      intent: Set a composition's sorting strategy
      effect: write
      questions:
      - How do I let users sort a composition's results using a replica index?
      - Can I replace only the sorting strategy mapping without rewriting the whole composition?
      instructions:
      - text: Update the sorting strategy of composition {compositionID}.
        slots:
          compositionID: path.compositionID
      - text: Replace just the sort-by-replica mapping on composition {compositionID}.
        slots:
          compositionID: path.compositionID
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1/compositions/{compositionID}/rules/{objectID}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one composition rule
      effect: read
      questions:
      - How do I view the conditions and consequence of a single composition rule?
      - Where do I look up a composition rule when I already know its object ID?
      instructions:
      - text: Show rule {objectID} in composition {compositionID}.
        slots:
          objectID: path.objectID
          compositionID: path.compositionID
      - text: Retrieve composition rule {objectID} from {compositionID}.
        slots:
          objectID: path.objectID
          compositionID: path.compositionID
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1/compositions/{compositionID}/rules/{objectID}'].put
  update:
    x-apievangelist-phrasing:
      intent: Add or replace a single composition rule
      effect: write
      questions:
      - How do I add a merchandising rule to one composition?
      - Can I schedule a composition rule to be valid only during a promotion window?
      instructions:
      - text: Save rule {objectID} on composition {compositionID} with consequence {consequence}.
        slots:
          objectID: path.objectID
          compositionID: path.compositionID
          consequence: requestBody.consequence
      - text: Add rule {objectID} to composition {compositionID} with conditions {conditions}, consequence {consequence}, valid during {validity}.
        slots:
          objectID: path.objectID
          compositionID: path.compositionID
          conditions: requestBody.conditions
          consequence: requestBody.consequence
          validity: requestBody.validity
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1/compositions/{compositionID}/rules/{objectID}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a single composition rule
      effect: destructive
      questions:
      - How do I remove one rule from a composition?
      - Can I delete a composition rule by its object ID?
      instructions:
      - text: Delete rule {objectID} from composition {compositionID}.
        slots:
          objectID: path.objectID
          compositionID: path.compositionID
      - text: Remove composition rule {objectID} in {compositionID}.
        slots:
          objectID: path.objectID
          compositionID: path.compositionID
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1/compositions/{compositionID}/rules/batch'].post
  update:
    x-apievangelist-phrasing:
      intent: Batch create, update or delete composition rules
      effect: write
      questions:
      - How do I upload many composition rules in one request?
      - Can I mix rule additions and deletions for one composition in a single batch?
      instructions:
      - text: 'Apply this batch of rule changes to composition {compositionID}: {requests}.'
        slots:
          compositionID: path.compositionID
          requests: requestBody.requests
      - text: Bulk save and delete rules on composition {compositionID}.
        slots:
          compositionID: path.compositionID
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1/compositions/{compositionID}/rules/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search a composition's rules
      effect: read
      questions:
      - How do I find which composition rules mention a certain keyword?
      - Can I list only the enabled rules on a composition?
      - Which rules on a composition are anchored to a query pattern or context?
      instructions:
      - text: Search rules in composition {compositionID} for {query}.
        slots:
          compositionID: path.compositionID
          query: requestBody.query
      - text: List enabled={enabled} rules in composition {compositionID} for context {context}.
        slots:
          enabled: requestBody.enabled
          compositionID: path.compositionID
          context: requestBody.context
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1/compositions/{compositionID}/task/{taskID}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check the status of a composition task
      effect: read
      questions:
      - Has my composition update finished being applied yet?
      - How do I check whether a composition write task is still pending?
      instructions:
      - text: Check the status of task {taskID} on composition {compositionID}.
        slots:
          taskID: path.taskID
          compositionID: path.compositionID
      - text: Tell me once whether composition {compositionID} task {taskID} is published or still pending.
        slots:
          compositionID: path.compositionID
          taskID: path.taskID
      method: generated
      generated: '2026-09-26'
- target: $.paths['/setClientApiKey'].get
  update:
    x-apievangelist-phrasing:
      intent: Switch the API key the Composition client uses
      effect: write
      questions:
      - Can I change which API key my Composition client authenticates with?
      - How do I rotate the key an existing Composition client sends?
      instructions:
      - text: Switch the Composition client to authenticate with API key {apiKey}.
        slots:
          apiKey: query.apiKey
      - text: Use {apiKey} for all further Composition API requests.
        slots:
          apiKey: query.apiKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/waitForCompositionTask'].get
  update:
    x-apievangelist-phrasing:
      intent: Wait until a composition task completes
      effect: read
      questions:
      - How can my code block until a composition upsert is fully applied?
      - Is there a helper that polls a composition task until it's done?
      instructions:
      - text: Wait until task {taskID} on composition {compositionID} completes.
        slots:
          taskID: query.taskID
          compositionID: query.compositionID
      - text: Keep polling composition {compositionID} until task {taskID} is published.
        slots:
          compositionID: query.compositionID
          taskID: query.taskID
      method: generated
      generated: '2026-09-26'