Feature Request: Add "Linked OpenAPI Workspace" Project Type

[jerrylusato]

Summary

I would like to propose a new project type in Insomnia called Linked OpenAPI Workspace (or similar) that allows Insomnia to work directly with an existing openapi.yml or openapi.yaml file on disk instead of importing it into its internal database.

The goal is to make OpenAPI the single source of truth and allow Insomnia to become the best development companion for API-first and code-first workflows.

Motivation

Many modern backend frameworks generate an OpenAPI specification automatically:

• FastAPI
• NestJS
• Spring Boot
• ASP.NET
• Express + Swagger
• Others

A typical project looks like:

backend/
├── src/
├── apis/
│   └── openapi.yml
└── ...

During development, this file is regenerated or updated whenever the application starts or builds.

Today, using this workflow with Insomnia requires importing the specification into Insomnia, creating a separate copy that can easily drift from the actual file.

Instead, I would like Insomnia to work directly against the file itself.

Proposal

Add a fourth, strictly additive project type to the existing Create project list:

• Local Vault
• Cloud Sync
• Git Sync
• Linked OpenAPI Workspace

This should not replace or change the behavior of any existing project type. It gives developers a new option when the project artifact they want Insomnia to work with is an existing OpenAPI document on disk.

The workflow could look like:

Create Project
○ Local Vault
○ Cloud Sync
○ Git Sync
● Linked OpenAPI Workspace

After selecting Linked OpenAPI Workspace, the user chooses an existing file, such as:

backend/apis/openapi.yml

or creates a new one. The user then chooses one of two modes.

Mode A: Watch Only (Read-only)

This mode is intended for generated specifications.

FastAPI / NestJS / Spring Boot
              │
              ▼
       apis/openapi.yml
              │
              ▼
          Insomnia

Behavior:

• Watches the file for changes.
• Automatically reloads when modified.
• Regenerates requests and endpoints.
• Disables the Design editor.
• Displays a banner indicating the specification is externally managed.

For example:

This specification is managed externally. Changes will automatically appear when the file is updated.

This is ideal when openapi.yml is generated by code annotations or decorators.

Mode B: Edit On Disk (Authoring)

This mode is intended for spec-first development.

Insomnia
   │
   ▼
apis/openapi.yml

Behavior:

• Editing the Design view writes directly back to openapi.yml.
• No internal copy exists.
• Git tracks the YAML file normally.
• VS Code immediately sees updates.
• Scalar, Redoc, Swagger UI, SDK generators, and CI all consume the exact same file.

This allows Insomnia to become an OpenAPI editor without duplicating the specification.

Why this matters

Today many teams accidentally maintain multiple sources of truth:

openapi.yml
Postman collection
Insomnia collection
Swagger docs
README examples

Eventually they diverge.

With a linked workspace:

                openapi.yml
                     │
      ┌──────────────┼──────────────┐
      │              │              │
      ▼              ▼              ▼
  Insomnia        Scalar         Redoc
      │
      ▼
 API Testing

Everything references the same artifact.

This is particularly valuable during active API development. Developers can use Insomnia to explore endpoints, configure environments, authenticate, send requests, test responses, and author or inspect the contract without creating a second OpenAPI copy. At the same time, documentation tools such as Swagger UI, Redoc, and Scalar remain free to render the canonical on-disk specification. SDK generators, validators, and CI pipelines can consume that same file as well.

Relative paths

The project should store relative paths whenever possible.

Example:

{
  "type": "linked-openapi",
  "path": "./apis/openapi.yml",
  "mode": "watch"
}

This allows teams to:

git clone backend
open insomnia

without machine-specific absolute paths.

Why not Git Sync?

Git Sync is excellent for synchronizing Insomnia projects. However, this proposal is different.

The goal is not to synchronize Insomnia's internal data. The goal is for Insomnia to treat an existing OpenAPI file as the project itself.

This avoids:

• Importing
• Exporting
• Duplicated specifications
• Synchronization drift

Expected developer workflow

Code-first

VS Code
   │
   ▼
FastAPI / NestJS / Spring
   │
Generate openapi.yml
   │
   ▼
Insomnia automatically reloads

No imports required.

Spec-first

Insomnia
   │
writes
   ▼
openapi.yml
   │
   ├── Scalar
   ├── Redoc
   ├── Swagger UI
   ├── SDK generation
   └── CI validation

Again, there is only one source of truth.

Benefits

• OpenAPI becomes the canonical project artifact.
• Eliminates duplicated specifications.
• Supports both code-first and spec-first teams.
• Fits naturally with FastAPI, NestJS, Spring Boot, and similar ecosystems.
• Makes Insomnia a first-class API development and testing companion rather than just an importer/exporter of API definitions.
• Lets teams use Insomnia for development while continuing to use Swagger UI, Redoc, Scalar, or another tool for published documentation.
• Enables seamless collaboration because the same openapi.yml is versioned in Git and consumed by every tool in the toolchain.

Related ideas

• #3565: Allow import/refresh of OpenAPI spec from URL covers refreshing an imported remote specification. This proposal instead treats a local OpenAPI file as the project itself and adds explicit read-only and authoring modes.
• #7866: Proposal to update the Insomnia YAML format mentions design documents that may reference a file. This proposal builds on that direction with a first-class linked-workspace workflow, file watching, and direct-on-disk authoring.

Final thought

The most valuable aspect of this proposal is not automatic file watching itself, but the shift in philosophy:

Instead of importing an OpenAPI document into Insomnia, let Insomnia work directly with the OpenAPI document as the project.

This would make Insomnia an ideal companion for modern OpenAPI-driven development and establish a true single source of truth for API design, testing, and documentation.

[jerrylusato]

Current Create project dialog for context. The proposed Linked OpenAPI Workspace should be an additive fourth option alongside these existing project types, without replacing or changing them.

[poojithap11]

Hi @jerrylusato,

Thank you for your detailed suggestion.

A feature request has been raised to add support for a Linked OpenAPI workspace, allowing insomnia to work directly with an existing OpenAPI file on disk rather than requiring the specification to be imported into insomnia.

Thank you.

[jerrylusato]

Thanks @poojithap11, I really appreciate you raising this as a feature request.

I’m genuinely excited to see this being considered. This would be a big improvement for teams working with Linked OpenAPI specs in Insomnia. If there’s a public issue or tracking link, I’d love to follow it so I can keep up with progress and be one of the first to test the feature when it lands.

[poojithap11]

Hi @jerrylusato, Thank you for your interest in following the progress of this request.

I've raised an internal ticket for this request. As this is an internal tracing ticket, the link can't be shared.

If the feature is implemented, it will be included in our changelog, which are the best places to stay informed about upcoming changed and new functionality.

Thank you.