# Stoplight Prism: Running a Mock API Server from an OpenAPI or Postman File > Prism turns an OpenAPI v2, OpenAPI v3.x or Postman Collection document into a local HTTP server that mocks responses and a proxy that validates real traffic against the same contract. The CLI is the part most teams adopt, and the basePath behaviour is the part that trips them up first. **stoplightio/prism** — Turn any OpenAPI2/3 and Postman Collection file into an API server with mocking, transformations and validations. - Repository: https://github.com/stoplightio/prism - Website: https://stoplight.io/open-source/prism - Stars: 5,045 · Forks: 415 - Language: TypeScript - License: Apache-2.0 - Published: 2026-09-23 · Updated: 2026-09-23 · Language: en - Canonical page: https://hysenlabs.com/projects/stoplightio-prism ## The gap Prism fills between a written contract and a running backend Frontend and integration work usually stalls on the same thing: the specification exists, the service does not. Prism reads the specification and serves responses from it. The README describes two roles. A mock server, started with prism mock, answers requests against the document so consumers can build against something concrete. A validation proxy, started with prism proxy, sits between a client and a real backend and checks that the traffic matches the document. Both take the same input: OpenAPI v3.1, OpenAPI v3.0, OpenAPI v2.0 (formerly Swagger) or a Postman Collection. The audience is API consumers and developers who already treat the specification as the source of truth, plus CI pipelines that want contract checks without a separate test suite. It is not a code generator and it does not produce a persistent store of anything. ## How Prism decides what to return: sampling, faker and content negotiation The mechanism is document-driven. Prism parses the specification, matches the incoming request to a path and method, and builds a response from the schema attached to that operation. The README credits openapi-sampler and json-schema-faker among the packages Prism is built on, which is where generated example values come from. Content negotiation is listed as completed on the roadmap, so the Accept header influences which response representation Prism picks when the operation defines more than one. Validation is the mirror image: on the proxy path, traffic is checked against the document and discrepancies are reported. Security Validation is also marked done, so security schemes declared in the document are evaluated. What is not there matters as much. Recording/Learning Mode (creating OpenAPI from HTTP traffic) and Data Persistence (letting Prism act like a sandbox) are both unchecked on the roadmap. Prism answers from the document, not from accumulated state, so a POST followed by a GET does not reflect the POST. ## Installing the Prism CLI and serving your first mock Prism ships as a set of npm packages; the CLI is @stoplight/prism-cli. The README states the runtime requirement as NodeJS >= 18.20.1, with a note that NodeJS 18.x needs at least 18.16. Install it globally: ```bash npm install -g @stoplight/prism-cli ``` With the binary on your PATH, point prism mock at a specification. The README uses a remote Petstore document as its example: ```bash prism mock https://raw.githack.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore-expanded.yaml ``` The CLI starts an HTTP server and prints the URLs it is serving, so read that output rather than assuming a path. A local file works the same way. The repository includes examples/petstore.oas2.yaml and examples/petstore.oas3.yaml, so you can run the command against a checkout copy of either one. For container use, the repository has a Dockerfile that builds the packages and runs on node:24-alpine with tini as the init process. The README notes one Docker-specific trap: Prism binds to localhost by default, so the mock is unreachable from outside the container unless you start it with -h 0.0.0.0. ## Switching from mocking to contract checking with prism proxy The second command turns Prism into a middlebox. You give it the document and the upstream base URL, and Prism forwards traffic while checking it. The README's example pairs the OAS2 Petstore file with the live Swagger Petstore service: ```bash prism proxy examples/petstore.oas2.yaml https://petstore.swagger.io/v2 ``` This is the mode to reach for when the backend exists and you want evidence that it still matches the contract, for instance in continuous integration. The trade-off is that Prism now sits in the request path, so it sees every request and response body that passes through it. That is a deployment decision, not just a configuration one, and the README does not document a redaction or filtering option for the proxy. ## The basePath behaviour that makes people think Prism is broken The most common false alarm is a 404 on a URL that looks correct. OpenAPI v2.0 had a basePath, applied to every URL. OpenAPI v3.0 folded that concept into server.url, and Prism v3 follows the v3 model: it treats OAS2 host plus basePath the same way it treats OAS3 server.url. The consequence, spelled out in the README, is that a base path of api/v1 with a path defined as hello is reachable at http://localhost:4010/hello, while http://localhost:4010/api/v1/hello fails. The README acknowledges the choice confuses some users and points at the CLI's default output as the authority on which URLs are actually served. Treat that printed list as the contract for your mock, not the server block in the document. The second Docker trap is the localhost binding already mentioned: -h 0.0.0.0 is the fix. ## What Prism does not do, and when to pick something else Prism is stateless by design. The roadmap lists Data Persistence as an open item, so if your test flow needs a created resource to appear in a later list call, Prism will not provide it. The same applies to Recording/Learning Mode: Prism cannot generate a specification from observed traffic. If you need either behaviour, look at WireMock, which is built around stubbed responses with state and request matching rather than around an OpenAPI document as the single source of truth. The difference in approach is the point: Prism derives everything from the specification, so the mock and the contract cannot drift apart, but you get no persistence and no learned behaviour. WireMock lets you author stubs and scenarios by hand, which gives you state at the cost of a second artefact to keep in sync with the API. If your specification is the artefact you already maintain, Prism's constraint is an advantage; if you need a programmable fake backend, it is the wrong tool. ## Licence, release cadence and the cost of staying current The repository is licensed Apache-2.0, and the root package.json carries the same identifier. That is a permissive licence, but this is not legal advice: if you redistribute Prism or embed it in a product, read the LICENSE file in the repository and get your own review. Maintenance signals are visible in the release list: v5.16.0 was published on 2026-07-17, following v5.15.11 on 2026-06-03 and v5.15.10 on 2026-04-20, and the last push to the default branch was on 2026-09-21. The upgrade cost is mostly Node version discipline. The README ties Prism to NodeJS >= 18.20.1, and the Dockerfile builds on node:24, so a CI image pinned to an older runtime is the likeliest breakage. Because the CLI is installed globally by npm, version drift between a developer's machine and CI is easy to introduce; pinning the @stoplight/prism-cli version in your pipeline is the concrete way to avoid it. ## Conclusion Adopt Prism when you have a written OpenAPI or Postman contract and need a server that answers requests before the backend exists, or a proxy that flags drift between the contract and the implementation. Skip it if you need stateful mock data: the README roadmap still lists Data Persistence as unchecked, so mocks do not act like a sandbox. Before rolling it into CI, run prism mock against your own specification and read the URL list the CLI prints, because a basePath of api/v1 is not part of the request path in Prism v3. ## FAQ ### What is Stoplight Prism used for? It runs a mock HTTP server from an OpenAPI v2, OpenAPI v3.x or Postman Collection document, and it can also act as a validation proxy that checks real traffic against that same document. The README positions it for API mocking and contract testing. ### How can I use Stoplight Prism? Install the CLI with npm install -g @stoplight/prism-cli, then run prism mock against a specification file or URL to start a mock server, or prism proxy with a document and an upstream base URL to validate live traffic. ### Is Stoplight Prism free to use? The source repository is licensed Apache-2.0, and the README points to hosted mock servers through the Stoplight Platform and Stoplight Studio as separate options. The README does not describe pricing for those hosted services. ## Sources - [License: Apache-2.0](https://github.com/stoplightio/prism/blob/main/LICENSE) - [Project website](https://stoplight.io/open-source/prism) - [README](https://github.com/stoplightio/prism/blob/main/README.md) - [Releases](https://github.com/stoplightio/prism/releases) - [stoplightio/prism on GitHub](https://github.com/stoplightio/prism) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/stoplightio-prism