Idea: Import structured Markdown docs to auto-generate Insomnia collections with folders, params, docs, and examples

[manikandan-findmyhub]

Hi Insomnia team,

I want to share a workflow idea that feels increasingly important now that many developers are using Cursor, agent IDEs, and MCP-based automation for API development.

Current workflow:

• A feature gets implemented in an AI-assisted IDE such as Cursor
• After implementation, the agent generates a structured Markdown block for each endpoint
• That Markdown includes:
  • feature name
  • folder structure
  • method + URL
  • path params
  • query params
  • headers
  • request body
  • endpoint docs
  • sample response
  • error codes
  • environment variables

Example:

Feature: Create Order

Folder: admin/checkout

Request

Method: POST
URL: {{apibaseurl}}/api/v1/orders/:TESTPATHPARAM

Description

Create a new order for a customer.

Path Params

• TESTPATHPARAM = 21 | Test path param

Query Params

• ABC = 23 | Test query param

Headers

• Content-Type = application/json

Request Body

{
"customer_id": "{{customer_id}}",
"items": [
{ "sku": "{{sku}}", "qty": 2 }
],
"currency": "INR"
}

Docs

Endpoint overview

Creates a new order for a customer in the checkout flow.

Business rules

• customer_id must be a valid active customer
• sku must exist in catalog
• qty must be greater than 0

Request notes

• This API belongs to the admin checkout module
• Use path param for test routing scenarios
• Query param ABC is used for internal validation

Success response

Returns created order details with status.

Error handling

• 400 for invalid payload
• 401 for unauthorized request
• 409 for duplicate order
• 500 for server-side failure

Sample Response 200

{
"order_id": "ord_12345",
"status": "created"
}

Error Codes

• 400 = Invalid request
• 401 = Unauthorized
• 409 = Duplicate order
• 500 = Internal server error

Environment Variables

• apibaseurl = https://api.example.com
• customer_id = CUST-1001
• sku = SKU-001

Problem:
Today, even if the agent can generate all this information, I still need to manually recreate it inside Insomnia. This becomes painful in real-world cases where I already have 100 endpoints in a workspace and a new feature adds 5 more endpoints. There does not seem to be an easy built-in incremental “merge these 5 into my existing collection with folder structure and docs” flow.

Idea:
Insomnia could support one of these approaches:

1. Native Markdown import

• Paste a structured Markdown block
• Insomnia parses it and creates/updates:
  • folders/request groups
  • requests
  • path/query params
  • headers
  • body
  • examples
  • endpoint docs
  • environment variables

2. MCP-first workflow

• Cursor / agent IDE connects to an Insomnia MCP server
• The agent reads the generated Markdown
• The agent calls MCP tools to create or update collections directly
• Insomnia then becomes part of the implementation workflow, not a separate manual step

3. Hybrid import/update flow

• Import structured Markdown into an existing workspace
• Show preview:
  • new endpoints
  • changed endpoints
  • conflicting endpoints
• Let the user choose merge/update/create-duplicate behavior

Why this makes sense:
There are already MCP-based efforts in the ecosystem for managing Insomnia-compatible collections, requests, and environments. That means the workflow is already technically meaningful:

• create collections
• create/update requests
• manage environments
• import from cURL/Postman
• export Insomnia-compatible JSON

A native or officially supported version of this idea would make Insomnia much more useful for modern AI-assisted API workflows.

Concrete Cursor/MCP example:

• Cursor agent finishes a feature called “admin checkout”
• Agent generates 5 endpoint markdown specs
• Agent connects through MCP to Insomnia
• Agent checks whether folder admin/checkout exists
• If not, create it
• If yes, append only new requests
• For changed endpoints, show diff or update preview
• Add request body, params, docs, examples, and environment variables automatically

This would save a lot of repetitive manual work and make Insomnia a much better fit for teams using AI-generated docs, spec-first development, and agentic workflows.

If native support is too large as a first step, even an officially recommended schema + plugin/MCP integration path would already help a lot.

Thanks for considering this.

[poojithap11]

Hi @manikandan-findmyhub,

Thank you for taking the time to share a detailed suggestion and for outlining your workflow with examples.

A feature request has been raised with the team to evaluate support for AI-assisted API workflows, including capabilities such as structured markdown import, MCP-based integrations, and incremental merge/ update workflows for existing insomnia collections.

Thank you.