Skip to main content
Connections represent integrations with external systems such as Kubernetes clusters, Prometheus, Grafana, and other platforms. Meshery uses connections to discover, monitor, and manage infrastructure.

​
List Connections

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:9081/api/integrations/connections?page=0&pagesize=25"
Method: GET Endpoint: /api/integrations/connections

​
Query Parameters

​
page
integer
default:"0"
Page number for pagination (0-indexed)
​
pagesize
string
default:"10"
Number of connections per page. Use all to return all results (max 100).
​
search
string
Search term for filtering connections
​
order
string
default:"updated_at desc"
Field to order by
​
filter
string
Filter by type or sub_type:
  • type platform
  • sub_type management
​
status
array
Filter by status array: ["connected", "deleted"]
status=["connected","registered"]
​
kind
array
Filter by kind array: ["kubernetes", "prometheus"]
kind=["kubernetes","meshery"]
​
type
array
Filter by type array: ["platform", "observability"]
type=["platform","observability"]
​
name
string
Filter by connection name (partial match)

​
Response

​
page
integer
Current page number
​
page_size
integer
Number of items per page
​
total_count
integer
Total number of connections
​
connections
array
Array of connection objects
Example Response: 
{
  "page": 0,
  "page_size": 25,
  "total_count": 3,
  "connections": [
    {
      "id": "880e8400-e29b-41d4-a716-446655440003",
      "name": "prod-cluster-1",
      "kind": "kubernetes",
      "type": "platform",
      "sub_type": "management",
      "status": "connected",
      "metadata": {
        "server": "https://k8s.example.com:6443",
        "version": "v1.28.0"
      },
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-02-20T14:45:00Z"
    }
  ]
}

​
Get Connection by ID

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:9081/api/integrations/connections/{connectionId}
Method: GET Endpoint: /api/integrations/connections/{connectionId}

​
Path Parameters

​
connectionId
string
required
Connection ID (UUID)

​
Response

Returns a single connection object.

​
Create Connection

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-k8s-cluster",
    "kind": "kubernetes",
    "type": "platform",
    "sub_type": "management"
  }' \
  http://localhost:9081/api/integrations/connections
Method: POST Endpoint: /api/integrations/connections

​
Request Body

​
name
string
required
Connection name
​
kind
string
required
Connection kind:
  • kubernetes
  • prometheus
  • grafana
  • meshery
  • And other supported integrations
​
type
string
required
Connection type:
  • platform
  • observability
  • registry
​
sub_type
string
required
Connection sub-type:
  • management
  • metrics
  • logs
  • traces
​
metadata
object
Connection-specific metadata (varies by kind)

​
Response

Status: 201 Created Returns the created connection object.

​
Update Connection

curl -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Connection Name",
    "status": "connected"
  }' \
  http://localhost:9081/api/integrations/connections/{connectionId}
Method: PUT Endpoint: /api/integrations/connections/{connectionId}

​
Path Parameters

​
connectionId
string
required
Connection ID (UUID)

​
Request Body

​
name
string
Updated connection name
​
status
string
Updated connection status
​
metadata
object
Updated metadata objectSpecial: MeshSync Deployment ModeFor Kubernetes connections, you can change the MeshSync deployment mode:
{
  "metadata": {
    "meshsync_deployment_mode": "broker"
  }
}
Valid modes:
  • broker - Deploy MeshSync via Meshery Broker (default)
  • native - Deploy MeshSync natively in the cluster

​
Response

Status: 200 OK Returns the updated connection object.

​
Delete Connection

curl -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  http://localhost:9081/api/integrations/connections/{connectionId}
Method: DELETE Endpoint: /api/integrations/connections/{connectionId}

​
Path Parameters

​
connectionId
string
required
Connection ID (UUID)

​
Response

Status: 200 OK Returns the deleted connection object.

​
Register Connection

The connection registration endpoint handles a multi-step process for registering new connections, particularly for Kubernetes clusters. 
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "kubernetes",
    "status": "init"
  }' \
  http://localhost:9081/api/integrations/connections/register
Method: POST, DELETE Endpoint: /api/integrations/connections/register

​
Request Body (Init)

​
kind
string
required
Connection kind (e.g., kubernetes)
​
status
string
required
Set to init to initialize registration

​
Response (Init)

Returns connection and credential schemas along with a registration ID: 
{
  "id": "registration-uuid",
  "connection": {
    "schema": {...}
  },
  "credential": {
    "schema": {...}
  }
}

​
Request Body (Register)

​
id
string
required
Registration ID from init step
​
kind
string
required
Connection kind
​
status
string
required
Registration status event (e.g., register, connect, verify)
​
name
string
Connection name

​
Connection Kinds

Supported connection kinds:
  • kubernetes - Kubernetes clusters
  • prometheus - Prometheus metrics servers
  • grafana - Grafana dashboards
  • meshery - Other Meshery instances
  • github - GitHub repositories
  • aws - AWS accounts
  • gcp - Google Cloud projects
  • azure - Azure subscriptions
Each kind has specific metadata requirements. Refer to the connection schemas for details.

​
Error Codes

​
400 Bad Request
error
Invalid request parameters or malformed JSON
​
401 Unauthorized
error
Missing or invalid authentication token
​
404 Not Found
error
Connection not found
​
500 Internal Server Error
error
Server error occurred