# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Bitbucket Commit statuses API
  version: 1.0.0
extends: openapi/bitbucket-commit-statuses-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 5
- target: $.paths['/repositories/{workspace}/{repo_slug}/commit/{commit}/statuses'].get
  update:
    x-apievangelist-phrasing:
      intent: List build statuses for a commit
      effect: read
      questions:
      - Did the builds pass on this commit?
      - Can I filter a commit's statuses by branch ref name?
      - Which CI results are attached to a specific commit?
      instructions:
      - text: List build statuses for commit {commit} in {workspace}/{repo_slug}.
        slots:
          commit: path.commit
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show statuses on commit {commit} for ref {refname}.
        slots:
          commit: path.commit
          refname: query.refname
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/commit/{commit}/statuses/build'].post
  update:
    x-apievangelist-phrasing:
      intent: Report a build status on a commit
      effect: write
      questions:
      - How does my CI server post a build result to a Bitbucket commit?
      - Can I mark a commit as failed or in progress from an external build?
      instructions:
      - text: Post build status {key} as {state} on commit {commit} in {workspace}/{repo_slug}.
        slots:
          key: requestBody.key
          state: requestBody.state
          commit: path.commit
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Create a {state} build result on {commit} linking to {url}.
        slots:
          state: requestBody.state
          commit: path.commit
          url: requestBody.url
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/commit/{commit}/statuses/build/{key}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one build status on a commit
      effect: read
      questions:
      - What is the state of one particular build on a commit?
      - Can I fetch a build status by its key?
      instructions:
      - text: Get build status {key} on commit {commit} in {workspace}/{repo_slug}.
        slots:
          key: path.key
          commit: path.commit
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show the {key} build result for {commit}.
        slots:
          key: path.key
          commit: path.commit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/commit/{commit}/statuses/build/{key}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a build status on a commit
      effect: write
      questions:
      - How do I flip an existing build status from in progress to successful?
      - Can I change the description or link of a build status I already posted?
      instructions:
      - text: Update existing build status {key} on commit {commit} in {workspace}/{repo_slug} to {state}.
        slots:
          key: path.key
          commit: path.commit
          workspace: path.workspace
          repo_slug: path.repo_slug
          state: requestBody.state
      - text: Change the link of build {key} on {commit} to {url}.
        slots:
          key: path.key
          commit: path.commit
          url: requestBody.url
      method: generated
      generated: '2026-10-01'
- target: $.paths['/repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/statuses'].get
  update:
    x-apievangelist-phrasing:
      intent: List build statuses for a pull request
      effect: read
      questions:
      - Are all the checks green on this pull request?
      - Which build results are reported against a PR?
      instructions:
      - text: List build statuses for pull request {pull_request_id} in {workspace}/{repo_slug}.
        slots:
          pull_request_id: path.pull_request_id
          workspace: path.workspace
          repo_slug: path.repo_slug
      - text: Show the CI checks on PR {pull_request_id}, sorted by {sort}.
        slots:
          pull_request_id: path.pull_request_id
          sort: query.sort
      method: generated
      generated: '2026-10-01'