Insight API

The Insight API (minsight) provides node discovery, mesh connectivity, and tunneling capabilities for mimOE. This mim is pre-deployed as part of the mesh-foundation addon and enables devices to discover each other on the local network, across accounts, and via proximity, as well as route traffic across network boundaries.

Base URL

http://localhost:8083/mimik-mesh/insight/v1

info

The Insight API is pre-deployed with the mesh-foundation addon. No additional installation is required.

Authentication

All endpoints require a Bearer token in the Authorization header:

Authorization: Bearer 1234

The default API key is 1234, configured in the [minsight-v1] section of the addon .ini file. See Addon Configuration for details.

Token Requirements

Endpoints that use linkLocal, self, or supernode scope work with the API key alone. Account-scoped operations (account, proximity) and backend endpoint queries (bep, sep) require a JWT to be stored first via PUT /token.

Quick Reference

Method	Endpoint	Description
GET	/nodes	Discover nodes on the mesh
GET	/info	Get node and mesh info
PUT	/token	Store JWT for account-scoped operations

Token Requirements

Discovery Type	Stored JWT Required
linkLocal	No
self	No
supernode	No
account	Yes
proximity	Yes
bep	Yes
sep	Yes

---

Node Discovery

Discover Nodes

Discover other mimOE nodes on the mesh. The discovery scope depends on the type query parameter.

Request

GET /nodes?type={type}

Query Parameters

Parameter	Type	Required	Description
type	string	Yes	Discovery scope: linkLocal, account, or proximity

Discovery Types

Type	Description	JWT Required
linkLocal	Nodes on the same local network	No
account	Nodes associated with the same account	Yes
proximity	Nearby nodes discovered via proximity services	Yes

Response (200 OK)

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "accountId": "acct-123456",
      "name": "Living Room Hub",
      "os": "linux",
      "addresses": [
        {
          "type": "local",
          "url": {
            "href": "http://192.168.1.100:8083"
          }
        }
      ],
      "services": [
        {
          "id": "svc-001",
          "serviceType": "ai-agent-v1",
          "version": "1.0.0",
          "status": "running",
          "tenant": "default"
        }
      ]
    }
  ]
}

See Node Object for field descriptions.

Example

cURL

curl -X GET "http://localhost:8083/mimik-mesh/insight/v1/nodes?type=linkLocal" \
  -H "Authorization: Bearer $API_KEY"

JavaScript

const response = await fetch(
  'http://localhost:8083/mimik-mesh/insight/v1/nodes?type=linkLocal',
  {
    headers: { 'Authorization': `Bearer ${apiKey}` }
  }
);

const { data: nodes } = await response.json();
console.log(`Found ${nodes.length} nodes on local network`);

Python

import requests

response = requests.get(
    "http://localhost:8083/mimik-mesh/insight/v1/nodes",
    headers={"Authorization": f"Bearer {api_key}"},
    params={"type": "linkLocal"}
)

nodes = response.json()["data"]
print(f"Found {len(nodes)} nodes on local network")

Account-Based Discovery

To discover nodes across your account, first store a JWT with PUT /token, then query with type=account:

curl -X GET "http://localhost:8083/mimik-mesh/insight/v1/nodes?type=account" \
  -H "Authorization: Bearer $API_KEY"

---

Node Information

Get Node Info

Retrieve information about the current node and its mesh connectivity. Supports multiple info types in a single request.

Request

GET /info?types={types}

Query Parameters

Parameter	Type	Required	Description
types	string	Yes	Comma-separated info types: self, supernode, bep, sep

Info Types

Type	Description	JWT Required
self	Current node information	No
supernode	Supernode connection details	No
bep	Backend endpoint (cloud relay) status	Yes
sep	Service endpoint for cross-network tunneling	Yes

Self Info

Returns the current node's identity and network addresses.

Example

cURL

curl -X GET "http://localhost:8083/mimik-mesh/insight/v1/info?types=self" \
  -H "Authorization: Bearer $API_KEY"

JavaScript

const response = await fetch(
  'http://localhost:8083/mimik-mesh/insight/v1/info?types=self',
  {
    headers: { 'Authorization': `Bearer ${apiKey}` }
  }
);

const info = await response.json();
console.log('Node ID:', info.data.self.id);

Python

import requests

response = requests.get(
    "http://localhost:8083/mimik-mesh/insight/v1/info",
    headers={"Authorization": f"Bearer {api_key}"},
    params={"types": "self"}
)

info = response.json()
print(f"Node ID: {info['data']['self']['id']}")

Response (200 OK)

{
  "data": {
    "self": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "accountId": "acct-123456",
      "name": "My Device",
      "os": "linux",
      "addresses": [
        {
          "type": "local",
          "url": {
            "href": "http://192.168.1.100:8083"
          }
        }
      ],
      "services": []
    }
  }
}

Supernode Info

Returns the supernode this node is connected to for mesh coordination.

curl -X GET "http://localhost:8083/mimik-mesh/insight/v1/info?types=supernode" \
  -H "Authorization: Bearer $API_KEY"

Response (200 OK)

{
  "data": {
    "supernode": {
      "id": "sn-a1b2c3d4",
      "name": "Supernode-US-West",
      "addresses": [
        {
          "type": "public",
          "url": {
            "href": "https://sn-us-west.mimik.com"
          }
        }
      ]
    }
  }
}

BEP (Backend Endpoint)

Returns the backend endpoint status for cloud relay connectivity.

curl -X GET "http://localhost:8083/mimik-mesh/insight/v1/info?types=bep" \
  -H "Authorization: Bearer $API_KEY"

Response (200 OK)

{
  "data": {
    "bep": {
      "url": "https://bep.mimik.com",
      "status": "connected"
    }
  }
}

SEP (Service Endpoint)

Returns the service endpoint used for cross-network tunneling. The response includes routing headers needed to forward requests to this node from outside the local network.

curl -X GET "http://localhost:8083/mimik-mesh/insight/v1/info?types=sep" \
  -H "Authorization: Bearer $API_KEY"

Response (200 OK)

{
  "data": {
    "sep": {
      "nodeId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "url": "https://sep.mimik.com",
      "headers": {
        "x-mimik-port": "8083",
        "x-mimik-routing": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      },
      "status": "available"
    }
  }
}

Multiple Types

Request multiple info types in a single call:

curl -X GET "http://localhost:8083/mimik-mesh/insight/v1/info?types=self,supernode,bep,sep" \
  -H "Authorization: Bearer $API_KEY"

Response (200 OK)

{
  "data": {
    "self": { "id": "a1b2c3d4-...", "..." : "..." },
    "supernode": { "id": "sn-a1b2c3d4", "..." : "..." },
    "bep": { "url": "https://bep.mimik.com", "status": "connected" },
    "sep": { "nodeId": "a1b2c3d4-...", "url": "https://sep.mimik.com", "..." : "..." }
  }
}

Tunneling via SEP

The SEP response provides everything needed to route requests to a node across network boundaries. Use the url as the base and include the routing headers from the headers field.

Example: Calling a mim on a remote node

curl -X GET "https://sep.mimik.com/my-agent/v1/data" \
  -H "Authorization: Bearer $API_KEY" \
  -H "x-mimik-port: 8083" \
  -H "x-mimik-routing: a1b2c3d4-e5f6-7890-abcd-ef1234567890"

This routes the request through the mimik cloud relay to the target node, where it is forwarded to the local mim at /my-agent/v1/data.

info

Tunneling requires that the target node has a valid JWT stored and an active BEP connection. See Tunneling for the full workflow.

---

Token Management

Store Token

Store a JWT for account-scoped operations. Once stored, endpoints that require a JWT (account discovery, proximity discovery, BEP, SEP) become available.

Request

PUT /token

Headers

Header	Required	Value
Content-Type	Yes	application/json
Authorization	Yes	Bearer <apiKey>

Request Body

Field	Type	Required	Description
token	string	Yes	JWT access token
expiresAt	integer	No	Token expiration time (Unix timestamp in seconds)

Example

cURL

curl -X PUT "http://localhost:8083/mimik-mesh/insight/v1/token" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "token": "eyJhbGciOiJSUzI1NiIs...",
    "expiresAt": 1729677600
  }'

JavaScript

const response = await fetch(
  'http://localhost:8083/mimik-mesh/insight/v1/token',
  {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${apiKey}`
    },
    body: JSON.stringify({
      token: jwtAccessToken,
      expiresAt: Math.floor(Date.now() / 1000) + 3600
    })
  }
);

const result = await response.json();
console.log('Token stored:', result.status);

Python

import requests
import time

response = requests.put(
    "http://localhost:8083/mimik-mesh/insight/v1/token",
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {api_key}"
    },
    json={
        "token": jwt_access_token,
        "expiresAt": int(time.time()) + 3600
    }
)

result = response.json()
print(f"Token stored: {result['status']}")

Response (200 OK)

{
  "status": "ok"
}

Usage Flow

The typical workflow for account-scoped operations:

1. Obtain a JWT access token via Account Association
2. Store the token with PUT /token
3. Use account-scoped endpoints (GET /nodes?type=account, GET /info?types=sep, etc.)

---

Schemas

Node Object

Field	Type	Description
id	string	Unique node identifier
accountId	string	Account the node is associated with
name	string	Human-readable node name
os	string	Operating system (e.g., linux, darwin, android, ios)
addresses	array	Network addresses (Address Entry)
services	array	Deployed services (Service Entry)

Address Entry

Field	Type	Description
type	string	Address type (e.g., local, public)
url.href	string	Full URL of the node endpoint

Service Entry

Field	Type	Description
id	string	Service identifier
serviceType	string	Type of service (mim image name)
version	string	Service version
status	string	Service status (e.g., running)
tenant	string	Tenant identifier

---

Error Responses

Error Format

{
  "message": "Description of the error",
  "statusCode": 400
}

Error Codes

Code	Description
400	Bad request (invalid query parameter or request body)
401	Unauthorized (missing or invalid API key)
403	Forbidden (stored JWT missing or expired for account-scoped operation)
500	Internal server error

---

Related

• Discovery Overview
• Link Local Discovery
• Account-Based Discovery
• Proximity Discovery
• Tunneling