# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand. overlay: 1.0.0 info: title: API Evangelist conversational phrasing for Test Observer Artefacts API version: 1.0.0 extends: openapi/canonical-artefacts-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: 10 - target: $.paths['/v1/artefacts'].get update: x-apievangelist-phrasing: intent: List the latest test artefacts effect: read questions: - Which artefacts are currently under test in Test Observer? - Can I narrow the latest artefacts to one family, like snaps or debs? instructions: - text: List the latest artefacts in family {family}. slots: family: query.family - text: Show all the newest artefacts being tested. method: generated generated: '2026-09-26' - target: $.paths['/v1/artefacts/search'].get update: x-apievangelist-phrasing: intent: Search artefact names effect: read questions: - Is there an artefact whose name contains a given word? - Can I page through artefact name search results across several families? instructions: - text: Search artefact names matching {q}. slots: q: query.q - text: Find artefact names like {q} in families {families}, {limit} at a time. slots: q: query.q families: query.families limit: query.limit method: generated generated: '2026-09-26' - target: $.paths['/v1/artefacts/history'].get update: x-apievangelist-phrasing: intent: Get an artefact's version history effect: read questions: - What versions of a snap have been through testing, and when were they created? - Can I see an artefact's version history for one track or stage only? instructions: - text: Show the version history of {name} in family {family}. slots: name: query.name family: query.family - text: List versions of {name} ({family}) on track {track} at stage {stage}. slots: name: query.name family: query.family track: query.track stage: query.stage method: generated generated: '2026-09-26' - target: $.paths['/v1/artefacts/{artefact_id}'].get update: x-apievangelist-phrasing: intent: Get one artefact effect: read questions: - What's the current status and stage of a specific artefact? - Who is assigned to review a given artefact? instructions: - text: Show artefact {artefact_id}. slots: artefact_id: path.artefact_id - text: Get the status and assignee of artefact {artefact_id}. slots: artefact_id: path.artefact_id method: generated generated: '2026-09-26' - target: $.paths['/v1/artefacts/{artefact_id}'].patch update: x-apievangelist-phrasing: intent: Update an artefact's status, stage or reviewers effect: write questions: - How do I approve or reject an artefact after testing? - Can I assign reviewers or link a Jira issue to an artefact? - Is it possible to archive an artefact? instructions: - text: Set artefact {artefact_id} status to {status}. slots: artefact_id: path.artefact_id status: requestBody.status - text: Assign artefact {artefact_id} to {assignee_email} and link Jira issue {jira_issue}. slots: artefact_id: path.artefact_id assignee_email: requestBody.assignee_email jira_issue: requestBody.jira_issue - text: Archive artefact {artefact_id} with comment {comment}. slots: artefact_id: path.artefact_id comment: requestBody.comment method: generated generated: '2026-09-26' - target: $.paths['/v1/artefacts/{artefact_id}/versions'].get update: x-apievangelist-phrasing: intent: List other versions of an artefact effect: read questions: - What other versions exist alongside a given artefact? - Can I jump from one artefact to its sibling versions? instructions: - text: List the versions related to artefact {artefact_id}. slots: artefact_id: path.artefact_id - text: Show sibling versions of artefact {artefact_id}. slots: artefact_id: path.artefact_id method: generated generated: '2026-09-26' - target: $.paths['/v1/artefacts/{artefact_id}/environment-reviews'].get update: x-apievangelist-phrasing: intent: List an artefact's environment reviews effect: read questions: - Which test environments have been reviewed for an artefact? - What review decisions were made per environment on an artefact? instructions: - text: List environment reviews for artefact {artefact_id}. slots: artefact_id: path.artefact_id - text: Show review decisions by environment on artefact {artefact_id}. slots: artefact_id: path.artefact_id method: generated generated: '2026-09-26' - target: $.paths['/v1/artefacts/{artefact_id}/environment-reviews'].patch update: x-apievangelist-phrasing: intent: Update many environment reviews at once effect: write questions: - Can I mark all environment reviews for an artefact in a single request? - How do I bulk-update review decisions across environments? instructions: - text: Bulk update every environment review on artefact {artefact_id}. slots: artefact_id: path.artefact_id - text: Apply review decisions to all environments of artefact {artefact_id} in one go. slots: artefact_id: path.artefact_id method: generated generated: '2026-09-26' - target: $.paths['/v1/artefacts/{artefact_id}/environment-reviews/{review_id}'].patch update: x-apievangelist-phrasing: intent: Record a decision on one environment review effect: write questions: - How do I approve a single environment's test results for an artefact? - Can I leave a comment on one environment review? instructions: - text: Set review {review_id} on artefact {artefact_id} to decision {review_decision}. slots: review_id: path.review_id artefact_id: path.artefact_id review_decision: requestBody.review_decision - text: Comment {review_comment} on environment review {review_id} of artefact {artefact_id}. slots: review_comment: requestBody.review_comment review_id: path.review_id artefact_id: path.artefact_id method: generated generated: '2026-09-26' - target: $.paths['/v1/artefacts/{artefact_id}/builds'].get update: x-apievangelist-phrasing: intent: Get an artefact's builds with test executions effect: read questions: - What builds does an artefact have and which tests ran on each? - Can I see the latest test executions per build for an artefact? instructions: - text: Show the latest builds and their test runs for artefact {artefact_id}. slots: artefact_id: path.artefact_id - text: List builds of artefact {artefact_id} with test executions. slots: artefact_id: path.artefact_id method: generated generated: '2026-09-26'