# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for X API v2 Community Notes API
  version: 1.0.0
extends: openapi/x-community-notes-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['/2/notes'].post
  update:
    x-apievangelist-phrasing:
      intent: Write a Community Note on a post
      effect: write
      questions:
      - How can an AI note writer submit a Community Note on a post?
      - Can I submit a note in test mode so it isn't publicly visible?
      instructions:
      - text: Submit a Community Note on post {post_id} with {info}, test mode {test_mode}.
        slots:
          post_id: requestBody.post_id
          info: requestBody.info
          test_mode: requestBody.test_mode
      - text: Write a test Community Note for {post_id} containing {info} (test_mode {test_mode}).
        slots:
          post_id: requestBody.post_id
          info: requestBody.info
          test_mode: requestBody.test_mode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/notes/evaluate'].post
  update:
    x-apievangelist-phrasing:
      intent: Evaluate a draft Community Note
      effect: read
      questions:
      - Can I get feedback on a Community Note's text before submitting it?
      - How would a proposed note on a post be scored?
      instructions:
      - text: Evaluate the note text {note_text} for post {post_id}.
        slots:
          note_text: requestBody.note_text
          post_id: requestBody.post_id
      - text: Score my draft note {note_text} against post {post_id} without submitting it.
        slots:
          note_text: requestBody.note_text
          post_id: requestBody.post_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/notes/search/notes_written'].get
  update:
    x-apievangelist-phrasing:
      intent: List Community Notes I've written
      effect: read
      questions:
      - Which Community Notes have I already written?
      - Can I list only the test-mode notes my note writer submitted?
      instructions:
      - text: List the Community Notes I've written with test mode {test_mode}.
        slots:
          test_mode: query.test_mode
      - text: Show {max_results} of my written notes where test_mode is {test_mode}.
        slots:
          max_results: query.max_results
          test_mode: query.test_mode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/notes/search/posts_eligible_for_notes'].get
  update:
    x-apievangelist-phrasing:
      intent: Find posts eligible for Community Notes
      effect: read
      questions:
      - Which posts are currently eligible to receive a Community Note?
      - Can I pick how eligible posts are selected when looking for ones to annotate?
      instructions:
      - text: Find posts eligible for notes with test mode {test_mode}.
        slots:
          test_mode: query.test_mode
      - text: Get {max_results} note-eligible posts using selection {post_selection} and test mode {test_mode}.
        slots:
          max_results: query.max_results
          post_selection: query.post_selection
          test_mode: query.test_mode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/notes/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a Community Note
      effect: destructive
      questions:
      - Is there a way to delete a Community Note I wrote?
      - Can a note be withdrawn after it was submitted?
      instructions:
      - text: Delete Community Note {id}.
        slots:
          id: path.id
      - text: Withdraw my note {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'