Getting started
Load a specification, read your first map, and find your way back to it later. No account and nothing to install.
You can go from a specification file to a map in under a minute. You don't need an account, and there is nothing to install.
Your first map
- Go to
/workspace, or pick Import an API on the Home page. - Give it a specification in one of three ways. Paste takes text, or click Paste from clipboard. Upload takes a file, or you can drop one anywhere on the editor. Remote URL fetches an address for you.
- Watch the status line under the editor. It names the format it found, such as "OpenAPI 3.0.x", "Postman" or "WSDL", and says when the input is ready.
- Click Build map, or press Ctrl+Enter.
No file to hand? Under Start from a sample there are three to try: a Postman collection, the OpenAPI Petstore and a custom JSON list. Click Use this on any of them.
What it can read
| Format | Versions | How to give it |
|---|---|---|
| OpenAPI | 3.0 and 3.1, JSON or YAML | Paste, upload or URL |
| Swagger | 2.0 | Paste, upload or URL |
| Postman collection | v2.0, v2.1 and v1 exports | Paste, upload or URL |
| cURL | One command, or several with one per line | Paste |
| HAR | A recording saved from your browser's network tab | Paste or upload |
| WSDL | A SOAP service, as .wsdl or .xml | Paste, upload or URL |
| Plain JSON or YAML | A list of endpoints | Paste or upload |
| Postman environment | An environment or globals export | Paste or upload |
Files are accepted with the extensions .json, .yaml, .yml, .har, .wsdl and .xml. GraphQL and gRPC schemas are not read.
Formats that are handled differently
- WSDL. A SOAP service has no REST paths, so Vizroute proposes them. Each operation becomes an endpoint, and the status line says how many paths it produced. The status line shows "Reading the WSDL" for a moment first. If the XML can't be read as a WSDL, the status line gives the reason instead of building a map.
- HAR. A browser recording is mostly page assets. Only the API calls are kept, and the status line says how many requests were kept and how many were skipped.
- Postman environment. An environment holds variables, not endpoints, so there is nothing to draw. The button changes to Save environment. Click it and the variables are added to your environments, ready for the playground. Then load a specification to use them.
When a URL will not load
The address is fetched by your browser, not by a server. So the host has to allow requests from other sites, which means it must send CORS headers. Many don't. If you see "CORS blocked", download the file yourself and use Upload instead. For files on GitHub, use the raw file address.
Very large files
Above about 600,000 characters, the text editor is skipped so the page stays responsive. You get a card saying the file was read and is ready. Click Build map as usual.
Coming back to a specification
Every specification you build a map from is added to Recent APIs, which keeps the last eight. You'll find the list on the Home page, at the foot of the import screen, in the sidebar of the map, and in the History menu on the map's top bar. These copies stay in this browser, and everyone who uses this browser sees the same list.
Your browser can clear stored copies to free space. If that has happened, clicking the entry tells you, removes it, and asks you to load the file again.
To keep a specification for longer, open the command palette with Ctrl+K and choose Save to collections. Collections hold up to 20 entries. When the list is full, the oldest is dropped.
Moving around
The product switcher beside the logo lists every part: Home, API Map, Contract Graph and Explore Tools. A lock beside Contract Graph means you have to sign in first. Docs, in the sidebar and in the site header, brings you back to this guide.
On the Home page, Ctrl+K searches your recent APIs and workspaces. Inside the API Map, Ctrl+K opens the command palette instead. See Keyboard shortcuts.