# API Smoke Validation

> Use when running quick, repeatable API smoke tests after changes with hurl, including auth, status-code, response-shape, endpoint sanity, and pre-integration health checks.

- Skill: `matt-riley/api-smoke-validation` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx get-skill add matt-riley/api-smoke-validation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/matt-riley/api-smoke-validation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- License: GNU GPL v3
- Author: matt-riley (https://skillmd.com/u/matt-riley)
- Updated: 2026-11-14
- Page: https://skillmd.com/skills/matt-riley/api-smoke-validation

---


# API smoke validation

Use this skill when you need fast, scriptable API smoke checks with `hurl` so endpoint regressions are caught immediately after a change.

## Use this skill when

- You changed API handlers, routing, auth checks, or request/response shaping.
- You need a minimal, repeatable request suite that verifies critical paths quickly.
- A branch needs confidence in endpoint health before heavier integration coverage.
- Existing hurl files can be reused or small targeted ones can be added.

## Do not use this skill when

- The task is full contract testing, load testing, or deep integration test design.
- There is no runnable API target environment for smoke requests.
- The request is non-HTTP validation unrelated to endpoint behavior.

## Routing boundary

| Situation | Use this skill? | Route instead |
| --- | --- | --- |
| Quick endpoint sanity checks after API changes | Yes | - |
| Full behavior change requiring TDD-first feature implementation | No | `test-driven-development` |
| Non-HTTP pipeline or CI troubleshooting with failing workflow jobs | No | `github-actions-failure-triage` |

## Inputs to gather

- Base URL and target environment for smoke execution.
- Critical endpoints and methods to validate.
- Required auth mode (token, API key, session cookie) and safe test credentials.
- Expected response status, key headers, and minimal body assertions.

## First move

1. Select the smallest endpoint set that represents service health and changed behavior.
2. Write or update targeted `hurl` requests with explicit assertions.
3. Run the smoke file and capture first failure before broadening coverage.

## Workflow

1. Identify must-pass paths (for example health check, core read, core write, auth-protected endpoint).
2. Create or update `hurl` scenarios with deterministic inputs and explicit assertions:
   - status code
   - critical headers
   - minimal response body checks
3. Parameterize environment-specific values through variables or env files.
4. Run `hurl` for the targeted suite and fix the smallest API issue exposed.
5. Re-run until smoke requests are stable.
6. If failures are environment/setup related, report the blocker and keep test artifacts reusable.

## Outputs

- Focused `hurl` smoke scenarios tied to changed API surfaces.
- Failure evidence and minimal fixes applied.
- Repeatable command for local or CI smoke execution.

## Guardrails

- Do not hardcode sensitive credentials in hurl files.
- Keep assertions specific enough to catch regressions but stable enough to avoid noise.
- Avoid turning smoke coverage into a full end-to-end suite in this skill.
- Prefer deterministic fixtures and idempotent requests where practical.

## Validation

- Smoke suite passes against the intended target environment.
- Assertions cover changed behavior and core health paths.
- Relevant repository checks for touched files still pass.

- Smoke test:
  - should trigger: "Add hurl smoke checks for POST /orders after auth changes."
  - should not trigger: "Write full behavior tests for the orders API." (→ `test-driven-development`)

## Examples

- "After auth middleware changes, add hurl smoke checks for unauthenticated vs authenticated responses on `/v1/profile`."
- "Validate `POST /orders` and `GET /orders/:id` with hurl after request-body validation changes, keeping checks minimal and repeatable."

## Reference files

- [`references/hurl-smoke-patterns.md`](references/hurl-smoke-patterns.md) - practical request/assertion patterns for stable smoke coverage

