# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Ghost Content and Admin Admin - Posts API
  version: 1.0.0
extends: openapi/ghost-org-admin-posts-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: 6
- target: $.paths['/admin/posts/'].get
  update:
    x-apievangelist-phrasing:
      intent: List posts including drafts
      effect: read
      questions:
      - How do I list all my posts, including drafts and scheduled ones?
      - Can I sort posts by publish date and only return certain fields?
      - Which filters can narrow down my post list, like by tag or status?
      instructions:
      - text: List posts matching {filter}.
        slots:
          filter: query.filter
      - text: Show me {limit} posts ordered by {order}.
        slots:
          limit: query.limit
          order: query.order
      - text: List posts with {include} and only the {fields} fields.
        slots:
          include: query.include
          fields: query.fields
      method: generated
      generated: '2026-09-26'
- target: $.paths['/admin/posts/'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a post
      effect: write
      questions:
      - How do I create a new blog post through the Admin API?
      - Can I write the post content in HTML rather than Lexical?
      instructions:
      - text: Create a new post from {posts}.
        slots:
          posts: requestBody.posts
      - text: Create a draft post with {source} content.
        slots:
          source: query.source
      method: generated
      generated: '2026-09-26'
- target: $.paths['/admin/posts/{id}/'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a post by ID
      effect: read
      questions:
      - How do I get one post by its ID, even if it's unpublished?
      - Can I get a post's content back in HTML format?
      instructions:
      - text: Get post {id}.
        slots:
          id: path.id
      - text: Fetch post {id} with its content in {formats}.
        slots:
          id: path.id
          formats: query.formats
      method: generated
      generated: '2026-09-26'
- target: $.paths['/admin/posts/{id}/'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a post
      effect: write
      questions:
      - How do I edit a post that's already been created?
      - Why does updating a post need the current updated_at value?
      instructions:
      - text: Update post {id} with {posts}.
        slots:
          id: path.id
          posts: requestBody.posts
      - text: Edit post {id} and send the new body as {source}.
        slots:
          id: path.id
          source: query.source
      method: generated
      generated: '2026-09-26'
- target: $.paths['/admin/posts/{id}/'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a post
      effect: destructive
      questions:
      - How do I permanently remove a blog post?
      - Can I delete a post if I only know its ID?
      instructions:
      - text: Delete post {id}.
        slots:
          id: path.id
      - text: Remove post {id} from the blog.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/admin/posts/slug/{slug}/'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a post by its URL slug
      effect: read
      questions:
      - How do I find a post when I only know its URL slug?
      - Can I look up a post from the last part of its link?
      instructions:
      - text: Get the post with slug {slug}.
        slots:
          slug: path.slug
      - text: Look up post {slug} by its slug.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'