openapi: 3.1.0
info:
  title: Insomnia Mock Server Mock Logs Mock Servers API
  description: The Insomnia Mock Server API allows developers to create, manage, and interact with mock servers powered by Insomnia (Kong). Mock servers simulate API endpoints by returning predefined responses based on OpenAPI specifications or custom route configurations. This enables frontend and backend teams to develop and test against realistic API behavior before the actual implementation is complete. Insomnia supports both cloud-hosted and self-hosted mock server deployments.
  version: 1.0.0
  contact:
    name: Kong Inc
    url: https://konghq.com/products/kong-insomnia
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
- url: https://mock.insomnia.rest
  description: Insomnia Cloud Mock Server
- url: http://localhost:4010
  description: Local Self-Hosted Mock Server
security:
- bearerAuth: []
tags:
- name: Mock Servers
  description: Manage mock server instances.
paths:
  /mock-servers:
    get:
      operationId: listMockServers
      summary: Insomnia List Mock Servers
      description: Returns a list of all mock servers configured within the current workspace, including their status, associated OpenAPI specification, and endpoint URL.
      tags:
      - Mock Servers
      parameters:
      - name: workspaceId
        in: query
        description: Filter mock servers by workspace identifier.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: A list of mock servers.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MockServer'
        '401':
          description: Unauthorized. Invalid or missing authentication.
    post:
      operationId: createMockServer
      summary: Insomnia Create Mock Server
      description: Creates a new mock server from an OpenAPI specification or custom route definitions. The mock server begins serving responses immediately after creation.
      tags:
      - Mock Servers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MockServerCreate'
      responses:
        '201':
          description: Mock server created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MockServer'
        '400':
          description: Invalid request body or specification.
        '401':
          description: Unauthorized.
  /mock-servers/{mockServerId}:
    get:
      operationId: getMockServer
      summary: Insomnia Get Mock Server
      description: Retrieves details of a specific mock server by its identifier.
      tags:
      - Mock Servers
      parameters:
      - $ref: '#/components/parameters/mockServerId'
      responses:
        '200':
          description: Mock server details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MockServer'
        '404':
          description: Mock server not found.
    put:
      operationId: updateMockServer
      summary: Insomnia Update Mock Server
      description: Updates an existing mock server configuration, including its associated specification and route behaviors.
      tags:
      - Mock Servers
      parameters:
      - $ref: '#/components/parameters/mockServerId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MockServerUpdate'
      responses:
        '200':
          description: Mock server updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MockServer'
        '400':
          description: Invalid request body.
        '404':
          description: Mock server not found.
    delete:
      operationId: deleteMockServer
      summary: Insomnia Delete Mock Server
      description: Deletes a mock server and stops serving all associated mock endpoints.
      tags:
      - Mock Servers
      parameters:
      - $ref: '#/components/parameters/mockServerId'
      responses:
        '204':
          description: Mock server deleted successfully.
        '404':
          description: Mock server not found.
components:
  schemas:
    MockServerCreate:
      type: object
      properties:
        name:
          type: string
          description: Human-readable name for the new mock server.
        workspaceId:
          type: string
          description: Identifier of the workspace to create the mock server in.
        specification:
          type: string
          description: OpenAPI specification content (YAML or JSON) to generate mock routes from.
        useExamples:
          type: boolean
          default: true
          description: Whether to use example values from the OpenAPI spec in responses.
      required:
      - name
      - workspaceId
    MockServer:
      type: object
      properties:
        _id:
          type: string
          description: Unique identifier for the mock server.
        name:
          type: string
          description: Human-readable name of the mock server.
        workspaceId:
          type: string
          description: Identifier of the workspace this mock server belongs to.
        url:
          type: string
          format: uri
          description: The base URL where the mock server is accessible.
        status:
          type: string
          enum:
          - running
          - stopped
          - error
          description: Current operational status of the mock server.
        specificationSource:
          type: string
          enum:
          - openapi
          - custom
          description: Whether routes are generated from an OpenAPI spec or custom definitions.
        created:
          type: string
          format: date-time
          description: Timestamp when the mock server was created.
        modified:
          type: string
          format: date-time
          description: Timestamp when the mock server was last modified.
      required:
      - _id
      - name
      - workspaceId
      - url
      - status
    MockServerUpdate:
      type: object
      properties:
        name:
          type: string
          description: Updated name for the mock server.
        specification:
          type: string
          description: Updated OpenAPI specification content.
        useExamples:
          type: boolean
          description: Whether to use example values from the spec.
  parameters:
    mockServerId:
      name: mockServerId
      in: path
      required: true
      description: Unique identifier of the mock server.
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Insomnia cloud authentication token for accessing mock server management endpoints.