# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Acquia Content API
  version: 1.0.0
extends: openapi/acquia-content-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: 8
- target: $.paths['/api'].get
  update:
    x-apievangelist-phrasing:
      intent: Discover the content types a site exposes
      effect: read
      questions:
      - Which content resource types can I query on my Drupal site's JSON:API?
      - What endpoints does the content API index list for this site?
      instructions:
      - text: Show me the index of content resource endpoints on this site.
      - text: List every resource type the content API makes available.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/{entityType}/{bundle}'].get
  update:
    x-apievangelist-phrasing:
      intent: List content entries of one bundle
      effect: read
      questions:
      - How do I fetch all the articles on my site through the content API?
      - Can I filter, sort and page through entries of a content type?
      - Why might meta.count be higher than the number of entries I get back?
      instructions:
      - text: List {entity_type} entries of bundle {bundle}.
        slots:
          entity_type: path.entityType
          bundle: path.bundle
      - text: Get {bundle} {entity_type} entries matching {filter}, sorted by {sort}.
        slots:
          bundle: path.bundle
          entity_type: path.entityType
          filter: query.filter
          sort: query.sort
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/{entityType}/{bundle}'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a content entry
      effect: write
      questions:
      - Can I publish a new article to my site through the content API?
      - What scope and site setting are needed before I can create content?
      instructions:
      - text: Create a new {bundle} {entity_type} entry with data {data}.
        slots:
          bundle: path.bundle
          entity_type: path.entityType
          data: requestBody.data
      - text: Add a {bundle} entry to {entity_type}.
        slots:
          bundle: path.bundle
          entity_type: path.entityType
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/{entityType}/{bundle}/{uuid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one content entry by UUID
      effect: read
      questions:
      - How can I read a single piece of content by its UUID?
      - Can I limit which fields come back when fetching one entry?
      instructions:
      - text: Get {bundle} {entity_type} entry {uuid}.
        slots:
          bundle: path.bundle
          entity_type: path.entityType
          uuid: path.uuid
      - text: Fetch entry {uuid} from {entity_type}/{bundle} returning only fields {fields}.
        slots:
          uuid: path.uuid
          entity_type: path.entityType
          bundle: path.bundle
          fields: query.fields
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/{entityType}/{bundle}/{uuid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a content entry
      effect: destructive
      questions:
      - Can I remove a piece of content from my site through the API?
      - What permissions does deleting an entry require?
      instructions:
      - text: Delete {bundle} {entity_type} entry {uuid}.
        slots:
          bundle: path.bundle
          entity_type: path.entityType
          uuid: path.uuid
      - text: Remove entry {uuid} from {entity_type}/{bundle}.
        slots:
          uuid: path.uuid
          entity_type: path.entityType
          bundle: path.bundle
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/{entityType}/{bundle}/{uuid}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update an existing content entry
      effect: write
      questions:
      - How do I edit the title or body of an article that's already published?
      - Can I change just some fields on an existing entry?
      instructions:
      - text: Update {bundle} {entity_type} entry {uuid} with data {data}.
        slots:
          bundle: path.bundle
          entity_type: path.entityType
          uuid: path.uuid
          data: requestBody.data
      - text: Patch existing entry {uuid} in {entity_type}/{bundle}.
        slots:
          uuid: path.uuid
          entity_type: path.entityType
          bundle: path.bundle
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/{entityType}/{bundle}/{uuid}/{field}'].get
  update:
    x-apievangelist-phrasing:
      intent: Fetch the entries a relationship field points to
      effect: read
      questions:
      - How do I get the full tags or author records an article references?
      - Can I pull the referenced entries with all their attributes in one call?
      instructions:
      - text: Get the full entries that field {field} of {entity_type}/{bundle} entry {uuid} references.
        slots:
          field: path.field
          entity_type: path.entityType
          bundle: path.bundle
          uuid: path.uuid
      - text: Load the related {field} records for {bundle} entry {uuid} in {entity_type}.
        slots:
          field: path.field
          bundle: path.bundle
          uuid: path.uuid
          entity_type: path.entityType
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/{entityType}/{bundle}/{uuid}/relationships/{field}'].get
  update:
    x-apievangelist-phrasing:
      intent: Read a relationship's linkage identifiers
      effect: read
      questions:
      - Can I see just the type and ID an entry points to, without the target's attributes?
      - What's the lightweight way to check which entries a relationship field links to?
      instructions:
      - text: Show only the linkage IDs for relationship {field} on {entity_type}/{bundle} entry {uuid}.
        slots:
          field: path.field
          entity_type: path.entityType
          bundle: path.bundle
          uuid: path.uuid
      - text: Get the type and id identifiers in the {field} relationship of entry {uuid} ({entity_type} {bundle}).
        slots:
          field: path.field
          uuid: path.uuid
          entity_type: path.entityType
          bundle: path.bundle
      method: generated
      generated: '2026-09-26'