# ScanAPI: Declarative REST API Integration Tests and Reports

> ScanAPI is a Python package for teams that want to describe REST API checks in YAML or JSON, execute those checks through the `scanapi` CLI, and receive an HTML diagnostic report. It is useful when test intent should be readable without writing a Python test module for every endpoint.

**scanapi/scanapi** — Automated Integration Testing and Live Documentation for your API

- Repository: https://github.com/scanapi/scanapi
- Website: https://scanapi.dev
- Stars: 1,586 · Forks: 142
- Language: Python
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/scanapi-scanapi

## ScanAPI's Declarative Check Model

ScanAPI addresses a specific gap between a manually maintained API description and a conventional test suite that expresses every check in code. Its input is an API specification written in YAML or JSON. That specification identifies endpoints, request paths, HTTP methods, and assertions. The runner then sends the configured requests, evaluates the expected behavior, and generates a report from the execution. This approach is aimed at teams that want to define API checks in a form that can be reviewed as configuration rather than as a Python test file.

The README presents the central use case as defining endpoints to call and the expected response behavior for each one. The example names a request and checks the response status code. The resulting report contains request details and execution results. That is useful for integration checks that verify live API behavior, including status codes and response conditions, while keeping the test definition close to an API-oriented configuration file.

The package is not limited to checking a single successful request. The specification format is hierarchical, with endpoints at the top level and requests beneath them. Each request can include tests. That structure allows several requests to be organized under one API base path, although the README does not document every feature of the format, such as authentication configuration, environment variables, request bodies, or chaining values between requests. Those capabilities should be checked in the full ScanAPI documentation before assuming they are available in a particular configuration.

## From YAML Specification to HTML Report

The documented execution path is straightforward. ScanAPI reads a YAML or JSON file, resolves the endpoints and requests described there, sends HTTP requests, evaluates the listed assertions, and writes `scanapi-report.html`. The report is therefore an execution artifact, not a separately maintained document generated from static comments. The README says that this report can also function as API documentation because it records the requests and their results.

The example uses a compact expression to assert the HTTP status. The syntax `${{ response.status_code == 200 }}` shows that assertions can be written as expressions evaluated against the response object. This keeps the example close to the response data being checked. The output report is intended to provide a real-time diagnostic view of the API run, including an overview and expanded request details as shown by the README screenshots.

This design has a clear consequence. The specification is executable configuration, so a malformed assertion or incorrect endpoint can affect both the test result and the generated report. The report should be treated as evidence from one execution, not as proof that the API is permanently correct. ScanAPI does not describe persistence, report history, or comparison against earlier runs in the available documentation, so teams should not assume those features from the existence of the HTML file alone.

## Installing ScanAPI and Running the First Check

ScanAPI is distributed as a Python package and requires `pip`. For a standalone command, the README also documents `pipx`, which isolates the CLI in its own environment. Choose the ordinary `pip` installation when ScanAPI should be available in the current project environment. Choose the documented `pipx` path when dependency isolation matters more than installing it as a project dependency.

Install the package with:

```bash
$ pip install scanapi
```

The README also provides this isolated CLI option:

```bash
$ pipx install scanapi
```

A first specification can be saved as YAML. The following example calls the users endpoint and checks for a successful response. The `path` on the endpoint is the API base URL, while the request-level `path` adds `users/`.

```yaml
endpoints:
  - name: scanapi-demo
    path: http://demo.scanapi.dev/api/v1
    requests:
      - name: list_all_users
        path: users/
        method: get
        tests:
          - name: status_code_is_200
            assert: ${{ response.status_code == 200 }}
```

Run the file with the `scanapi` command:

```bash
$ scanapi run <file_path>
```

The README states that the command generates `scanapi-report.html`. Replace `<file_path>` with the path to the YAML or JSON file. The report should contain the results of the requests and tests. A failure in connectivity, endpoint configuration, or an assertion will be reflected in that run rather than silently turning into a successful test.

## Python and Dependency Boundaries

ScanAPI is a Python package with a declared compatibility range of Python 3.10 through Python 3.14. That range is recorded in `pyproject.toml`, so an older interpreter or a Python version outside the declared range is not a supported installation target according to the package metadata. The current package version in `pyproject.toml` is 2.13.3, matching the latest listed release.

The runtime dependency list includes `httpx` for HTTP work, `PyYAML` for YAML handling, `Click` for the command-line interface, `Jinja2` and `rich` for reporting and output, `prance` and `openapi-spec-validator` for specification-related processing, and `restrictedpython` for restricted evaluation. These dependencies explain why ScanAPI can accept configuration files and produce reports without requiring the user to assemble the surrounding CLI and reporting stack.

The README discusses dependency management in detail. Most dependencies use compatible version ranges, while some test dependencies are strictly pinned. `MarkupSafe==3.0.3` is pinned for security and compatibility, `pytest-freezegun==0.4.2` is pinned because the README describes that package as unmaintained with only that version available, and `requests-mock==1.12.1` is pinned for compatibility. This is relevant for CI environments, where dependency resolution can differ from a developer machine. The repository also includes a `Makefile`, `uv.lock`, tests, and development tooling, but those files are for project development rather than the basic ScanAPI user workflow.

## When Declarative Tests Are the Wrong Choice

ScanAPI is a good fit for declarative checks whose value can be expressed through configured requests and assertions. It is less suitable as the sole home for tests that need substantial Python control flow, complex fixture construction, or extensive custom processing. The README example demonstrates a simple status-code assertion, but it does not document a general Python testing API. A team should not assume that arbitrary unit-test patterns can be transferred directly into a ScanAPI specification.

The generated HTML report also has a different purpose from a full test-management system. The README documents report generation and request details, but it does not state that ScanAPI stores historical runs, provides test selection, retries, parallel execution, or integration with a central results service. Those omissions are not proof that the features do not exist, but they are reasons to verify them before replacing an established reporting workflow.

A conventional Python integration suite is the main alternative. Instead of placing endpoints and assertions in YAML or JSON, that approach writes test logic in Python and can use the ecosystem's normal fixture and assertion mechanisms. ScanAPI's difference is declarative configuration plus a command-line report. The trade-off is readability and low Python involvement for simple endpoint checks versus more direct code control for tests with complex state and branching.

## ScanAPI Release and Maintenance Signals

The repository is not archived, and its last push was on 2026-10-15. Recent listed releases include v2.13.3 on 2026-08-13, v2.13.2 on 2026-05-18, and v2.13.1 on 2026-05-18. These dates indicate recent repository activity and recent package releases, but they do not by themselves establish that every feature is stable or that upgrades will be free of breaking changes.

The project uses the MIT license. That is a permissive license, but the license file and project terms should be reviewed for the obligations that apply to a particular distribution or organization. The available documentation does not provide legal advice, so this article does not interpret those obligations beyond identifying the license. Upgrade work is also not free of consideration: the README says dependencies are reviewed for compatibility with supported Python versions and CI stability, while several test dependencies have strict pins. Consumers should account for package resolution changes when moving between ScanAPI versions.

The repository's `Makefile` provides development commands such as `make test`, `make lint`, and `make mypy`, along with formatting and dependency-related targets. Those commands are aimed at contributors working in the repository. They do not replace an application team's own CI checks, especially when the application uses a different Python version or a separate dependency resolver.

## Conclusion

Adopt ScanAPI when your team wants declarative endpoint checks, readable YAML or JSON specifications, and an HTML report from one command. Do not choose it as the only solution for tests that require substantial Python logic, custom fixtures, or code-level control flow. Before adoption, verify that your supported Python version is between 3.10 and 3.14, then inspect how your API handles authentication, dynamic request data, and report retention.

## FAQ

### How do I install ScanAPI for a standalone CLI?

The README documents `pipx install scanapi` for an isolated CLI installation. It says that pipx gives ScanAPI its own virtual environment and puts the `scanapi` command on PATH.

### What file format can ScanAPI use for API tests?

ScanAPI accepts API specifications written in YAML or JSON. The specification contains endpoints, requests, and tests.

### What does ScanAPI produce after running a specification?

According to the README, ScanAPI generates `scanapi-report.html` after running the specified endpoints and tests. The report contains the execution results and request details.

## Sources

- [License: MIT](https://github.com/scanapi/scanapi/blob/main/LICENSE)
- [Project website](https://scanapi.dev)
- [README](https://github.com/scanapi/scanapi/blob/main/README.md)
- [Releases](https://github.com/scanapi/scanapi/releases)
- [scanapi/scanapi on GitHub](https://github.com/scanapi/scanapi)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/scanapi-scanapi