REST API Reference

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/environments

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/environments

Parameters

Query parameters

Name	Type	Required	Description
`search`	string	No	Get responses that match search param value
`order`	string	No	Get ordered responses
`page`	integer	No	Get responses by page
`pageSize`	integer	No	Number of responses to return per page. Canonical camelCase pagination parameter; prefer this over the deprecated all-lowercase `pagesize`.
`pagesize`	integer	No	Get responses by pagesize. Deprecated alias of pageSize.
`orgId`	string (uuid)	Yes	User’s organization ID
`purpose`	string	No	Return only environments with this purpose; absent returns every purpose the caller may see. The filter only narrows the environments the caller can already list and grants no visibility - a caller who cannot see administrative environments receives an empty page for purpose=administrative.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Paginated list of environments.

Field	Type	Required	Description
`environments`	array of object	No	Environments associated with this resource.
`page`	integer	No	Zero-based page index returned in this response.
`pageSize`	integer	No	Maximum number of items returned on each page.
`totalCount`	integer	No	Total number of items across all pages.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/environments

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/environments

Request body

application/json Required

Body for creating environment

Payload for creating or updating an environment. Carries only the client-settable fields. Server-owned fields are deliberately absent: id, owner, createdAt, updatedAt and deletedAt because the server assigns them. purpose is present but limited to the non-privileged values, because permission to create an environment must not confer the ability to designate it administrative. Limiting it here is a codegen guarantee rather than access control: the registrant connection inlines the full environment entity, so purpose still reaches the registerRegistryComponent and registerRegistryRelationship request types, and every consumer must refuse a privileged value on input whatever surface it arrives on. Do not widen EnvironmentPayloadPurpose to a privileged value - see https://github.com/meshery/schemas/blob/master/docs/environment-purpose-contract.md.

Field	Type	Required	Description
`description`	string	No	An environment is a collection of resources, such as connections & credentials. Provide a detailed description to clarify the purpose of this environment and the types of resources it encompasses. You can modify the description at any time. Learn more about environments here.
`metadata`	object	No	Free-form settings stored with the environment.
`name`	string	Yes	An environment is a collection of resources. Provide a name that meaningfully represents these resources. You can change the name of the environment even after its creation.
`organizationId`	string (uuid)	Yes	Select an organization in which you want to create this new environment. Keep in mind that the organization cannot be changed after creation.
`purpose`	string	No	The purpose a client may give an environment on create or update: `user` (an ordinary environment). Profiles are not environments; they are their own construct at `/api/profiles`, assigned to workspaces. Omitted means `user` on create and unchanged on update. A server refuses any other value with 400, and never lets this field change an environment that already carries a privileged purpose.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Environments allow you to logically group related Connections and their associated Credentials. Learn more at https://docs.meshery.io/concepts/logical/environments

Field	Type	Required	Description
`id`	string (uuid)	Yes	ID
`schemaVersion`	string	Yes	Specifies the version of the schema to which the environment conforms.
`name`	string	Yes	Environment name
`description`	string	Yes	Environment description
`organizationId`	string (uuid)	Yes	Environment organization ID
`owner`	string (uuid)	No	Environment owner
`createdAt`	string (date-time)	No	Timestamp when the environment was created.
`metadata`	object	No	Additional metadata associated with the environment.
`updatedAt`	string (date-time)	No	Timestamp when the environment was last updated.
`deletedAt`	string \| null (date-time)	No	Timestamp when the environment was soft deleted. Null while the environment remains active.
`purpose`	string	No	What the environment exists for. `user` is an ordinary environment that people create to logically group Connections and their Credentials. `administrative` designates an environment the platform itself provisions to hold organization-level configuration, and which resolvers of that configuration therefore trust. Profiles are not environments: they are their own construct (`schemas/constructs/v1beta3/profile`, served at `/api/profiles` and assigned to workspaces under `/api/workspaces/{workspaceId}/profiles`). Absent means `user`. Nothing may read an unset or unrecognised value as administrative: test for the administrative value explicitly rather than for “not user”, so the property fails closed. At most one live environment per organization may carry any single privileged purpose - `administrative`, and each privileged value a later version adds. Name those values explicitly wherever the rule is enforced, including the database index predicate: a “not `user`” test also matches the empty value that unmigrated rows and un-normalised writes read back as, which means ordinary. A resolver that selects an environment by purpose MUST fail closed when more than one live row matches: return an error rather than whichever row the database happened to return first. Privileged values are server-owned and never client-settable. `EnvironmentPayload`, which every environment POST and PUT requestBody references, accepts only the non-privileged value `user`, and the create-or-edit form has no field for it, so the environment create and update endpoints cannot designate an environment administrative. That restriction is a codegen guarantee, never access control: the registrant connection inlines the full environment entity, so `registerRegistryComponent` and `registerRegistryRelationship` do carry `purpose` in a request type and consumers MUST refuse it on input there too. Whatever surface a value arrives on, every consumer MUST assign this property only from server-side provisioning or a data migration. Permission to create an environment does not confer the ability to make one administrative. The database index that enforces the uniqueness invariant, the migration path for environments that are administrative by naming convention today, and each consumer’s obligations are specified in https://github.com/meshery/schemas/blob/master/docs/environment-purpose-contract.md.

Example response

{
  "createdAt": "0001-01-01T00:00:00Z",
  "deletedAt": null,
  "description": "Connections and credentials for the production cluster.",
  "id": "00000000-0000-0000-0000-000000000000",
  "metadata": {},
  "name": "Production Environment",
  "organizationId": "00000000-0000-0000-0000-000000000000",
  "owner": "00000000-0000-0000-0000-000000000000",
  "purpose": "user",
  "schemaVersion": "environments.meshery.io/v1beta3",
  "updatedAt": "0001-01-01T00:00:00Z"
}

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/environments/{environmentId}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/environments/{environmentId}

Parameters

Path parameters

Name	Type	Required	Description
`environmentId`	string (uuid)	Yes	Environment ID

Query parameters

Name	Type	Required	Description
`orgId`	string (uuid)	Yes	User’s organization ID

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Paginated list of environments.

Field	Type	Required	Description
`environments`	array of object	No	Environments associated with this resource.
`page`	integer	No	Zero-based page index returned in this response.
`pageSize`	integer	No	Maximum number of items returned on each page.
`totalCount`	integer	No	Total number of items across all pages.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/environments/{environmentId}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/environments/{environmentId}

Parameters

Path parameters

Name	Type	Required	Description
`environmentId`	string (uuid)	Yes	Environment ID

Request body

application/json Required

Body for creating environment

Payload for creating or updating an environment. Carries only the client-settable fields. Server-owned fields are deliberately absent: id, owner, createdAt, updatedAt and deletedAt because the server assigns them. purpose is present but limited to the non-privileged values, because permission to create an environment must not confer the ability to designate it administrative. Limiting it here is a codegen guarantee rather than access control: the registrant connection inlines the full environment entity, so purpose still reaches the registerRegistryComponent and registerRegistryRelationship request types, and every consumer must refuse a privileged value on input whatever surface it arrives on. Do not widen EnvironmentPayloadPurpose to a privileged value - see https://github.com/meshery/schemas/blob/master/docs/environment-purpose-contract.md.

Field	Type	Required	Description
`description`	string	No	An environment is a collection of resources, such as connections & credentials. Provide a detailed description to clarify the purpose of this environment and the types of resources it encompasses. You can modify the description at any time. Learn more about environments here.
`metadata`	object	No	Free-form settings stored with the environment.
`name`	string	Yes	An environment is a collection of resources. Provide a name that meaningfully represents these resources. You can change the name of the environment even after its creation.
`organizationId`	string (uuid)	Yes	Select an organization in which you want to create this new environment. Keep in mind that the organization cannot be changed after creation.
`purpose`	string	No	The purpose a client may give an environment on create or update: `user` (an ordinary environment). Profiles are not environments; they are their own construct at `/api/profiles`, assigned to workspaces. Omitted means `user` on create and unchanged on update. A server refuses any other value with 400, and never lets this field change an environment that already carries a privileged purpose.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Paginated list of environments.

Field	Type	Required	Description
`environments`	array of object	No	Environments associated with this resource.
`page`	integer	No	Zero-based page index returned in this response.
`pageSize`	integer	No	Maximum number of items returned on each page.
`totalCount`	integer	No	Total number of items across all pages.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/environments/{environmentId}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/environments/{environmentId}

Parameters

Path parameters

Name	Type	Required	Description
`environmentId`	string (uuid)	Yes	Environment ID

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/environments/{environmentId}/connections

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/environments/{environmentId}/connections

Parameters

Path parameters

Name	Type	Required	Description
`environmentId`	string (uuid)	Yes	Environment ID

Query parameters

Name	Type	Required	Description
`search`	string	No	Get responses that match search param value
`order`	string	No	Get ordered responses
`page`	integer	No	Get responses by page
`pageSize`	integer	No	Number of responses to return per page. Canonical camelCase pagination parameter; prefer this over the deprecated all-lowercase `pagesize`.
`pagesize`	integer	No	Get responses by pagesize. Deprecated alias of pageSize.
`filter`	string	No	JSON-encoded filter string used to scope the connection listing.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Paginated list of connections associated with an environment.

Field	Type	Required	Description
`connections`	array of object	No	The connections of the environmentconnectionspage.
`page`	integer	No	Current page number of the result set.
`pageSize`	integer	No	Number of items per page.
`totalCount`	integer	No	Total number of items available.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/environments/{environmentId}/connections/{connectionId}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/environments/{environmentId}/connections/{connectionId}

Parameters

Path parameters

Name	Type	Required	Description
`environmentId`	string (uuid)	Yes	Environment ID
`connectionId`	string (uuid)	Yes	Connection ID

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/environments/{environmentId}/connections/{connectionId}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/environments/{environmentId}/connections/{connectionId}

Parameters

Path parameters

Name	Type	Required	Description
`environmentId`	string (uuid)	Yes	Environment ID
`connectionId`	string (uuid)	Yes	Connection ID

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/events

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/events

Request body

application/json Required

Payload for creating a new event. If visibility is absent, the event is private.

Field	Type	Required	Description
`action`	string	No	The action of the event.
`category`	string	No	The category of the event.
`description`	string	No	Description of the event.
`idempotencyKey`	string	No	Optional client-chosen key that makes recording this event safe to retry. Keys are scoped to the authenticated caller (organization and user), never to the client-settable `owner` field, so `owner` may be omitted without affecting deduplication. The first event a caller records with a key is kept, and a later create with the same key records nothing and answers 200 with that event, whatever the rest of the payload says. Use a value that names the occurrence, for example a run id, so a client replaying a local queue after a timeout never records a duplicate. Omit it for events that need no deduplication.
`owner`	string (uuid)	No	UUID of the user associated with the event.
`visibility`	string	No	Who can see the event. `private` is the default; clients may set `public` for events eligible for the unauthenticated feed.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

One recorded event (an event_trackers row) in the wire form MeshKit’s models/events.Event serializes. Meshery Cloud returns these, for example, as the per-path failure records of a GitHub repository import (importGithubRepository, errors). Unlike EventResult, it carries no joined user profile fields.

Field	Type	Required	Description
`actedUpon`	string (uuid)	Yes	ID of the entity on which the event was performed.
`action`	string	Yes	Action taken on the resource, for example `import`.
`category`	string	Yes	Resource kind the operation was invoked on, for example `pattern`.
`createdAt`	string (date-time)	Yes	Timestamp when the event was recorded.
`deletedAt`	string \| null (date-time)	No	Timestamp when the event was soft-deleted; omitted when it was not.
`description`	string	Yes	Human-readable summary of what happened.
`id`	string (uuid)	Yes	Event ID.
`metadata`	object \| null	Yes	Event-specific details; the structure varies by event kind. `null` when the producer attached none. It stays a free-form map; design events fill it with a named shape: RelationshipEvaluationEventMetadata (category `relationship`, action `evaluation`), DesignValidationEventMetadata (category `pattern`, actions `validate`, `deploy`, `undeploy`, `dry-run`) and DesignSavedEventMetadata (category `pattern`, actions `create`, `update`); ScheduleCompletedEventMetadata (category `schedule`, action `completed`); DesignEventIdentity names the design. Never put design contents into event metadata - no `designFile`, `patternFile`, `components`, `relationships`, `trace`, `evaluationResponse`, the raw `summary` or `validationResult`. Meshery Server applies a 16 KB guard that drops oversized metadata down to the identity fields (`designId`, `designName`, `designVersion`, `designLink`, `viewLink`). On an error event, `metadata.error` holds only the MeshKit error, never the design or the request that failed; a design validation event whose operation did not complete (`status` `error`) carries it as a DesignEventOperationError. Older Meshery Cloud rows may carry the legacy `design_name` and `view_link` keys; readers should fall back to them when `designName` and `viewLink` are absent.
`operationId`	string (uuid)	Yes	ID correlating the events one operation emitted.
`owner`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`organizationId`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`severity`	string	Yes	Event level. MeshKit’s producers set one of `emergency`, `alert`, `critical`, `error`, `warning`, `informational`, `debug` or `success`. The set is not closed on the wire - the event write APIs persist the value they are given - so consumers must tolerate other values.
`status`	string	Yes	Read state of the event. MeshKit records new events as `unread`, and acknowledged ones become `read`; the event status APIs persist any value they are given, so consumers must tolerate other values.
`systemId`	string (uuid)	Yes	ID of the system instance that emitted the event. A Meshery Server sends its server instance ID; an event the provider emits itself carries the nil UUID. A client that registered a connection for its machine (for example a desktop client) sets its connection ID, so an event that records a run names the computer that ran it and can be joined to the claim it released (`Claim.outcomeEventId`) and to the connection (`connections.id`). The value is asserted by the sender and is not checked against the caller’s connections.
`updatedAt`	string (date-time)	Yes	Timestamp when the event was last updated.
`visibility`	string	Yes	Who can see the event. Defaults to `private`.

One recorded event (an event_trackers row) in the wire form MeshKit’s models/events.Event serializes. Meshery Cloud returns these, for example, as the per-path failure records of a GitHub repository import (importGithubRepository, errors). Unlike EventResult, it carries no joined user profile fields.

Field	Type	Required	Description
`actedUpon`	string (uuid)	Yes	ID of the entity on which the event was performed.
`action`	string	Yes	Action taken on the resource, for example `import`.
`category`	string	Yes	Resource kind the operation was invoked on, for example `pattern`.
`createdAt`	string (date-time)	Yes	Timestamp when the event was recorded.
`deletedAt`	string \| null (date-time)	No	Timestamp when the event was soft-deleted; omitted when it was not.
`description`	string	Yes	Human-readable summary of what happened.
`id`	string (uuid)	Yes	Event ID.
`metadata`	object \| null	Yes	Event-specific details; the structure varies by event kind. `null` when the producer attached none. It stays a free-form map; design events fill it with a named shape: RelationshipEvaluationEventMetadata (category `relationship`, action `evaluation`), DesignValidationEventMetadata (category `pattern`, actions `validate`, `deploy`, `undeploy`, `dry-run`) and DesignSavedEventMetadata (category `pattern`, actions `create`, `update`); ScheduleCompletedEventMetadata (category `schedule`, action `completed`); DesignEventIdentity names the design. Never put design contents into event metadata - no `designFile`, `patternFile`, `components`, `relationships`, `trace`, `evaluationResponse`, the raw `summary` or `validationResult`. Meshery Server applies a 16 KB guard that drops oversized metadata down to the identity fields (`designId`, `designName`, `designVersion`, `designLink`, `viewLink`). On an error event, `metadata.error` holds only the MeshKit error, never the design or the request that failed; a design validation event whose operation did not complete (`status` `error`) carries it as a DesignEventOperationError. Older Meshery Cloud rows may carry the legacy `design_name` and `view_link` keys; readers should fall back to them when `designName` and `viewLink` are absent.
`operationId`	string (uuid)	Yes	ID correlating the events one operation emitted.
`owner`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`organizationId`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`severity`	string	Yes	Event level. MeshKit’s producers set one of `emergency`, `alert`, `critical`, `error`, `warning`, `informational`, `debug` or `success`. The set is not closed on the wire - the event write APIs persist the value they are given - so consumers must tolerate other values.
`status`	string	Yes	Read state of the event. MeshKit records new events as `unread`, and acknowledged ones become `read`; the event status APIs persist any value they are given, so consumers must tolerate other values.
`systemId`	string (uuid)	Yes	ID of the system instance that emitted the event. A Meshery Server sends its server instance ID; an event the provider emits itself carries the nil UUID. A client that registered a connection for its machine (for example a desktop client) sets its connection ID, so an event that records a run names the computer that ran it and can be joined to the claim it released (`Claim.outcomeEventId`) and to the connection (`connections.id`). The value is asserted by the sender and is not checked against the caller’s connections.
`updatedAt`	string (date-time)	Yes	Timestamp when the event was last updated.
`visibility`	string	Yes	Who can see the event. Defaults to `private`.

Schema: string

A MeshKit error answered as a JSON body. error is the sentence the caller is shown; MeshKit’s long description is never serialized. Use the MeshkitError400, MeshkitError403, MeshkitError404, MeshkitError409, MeshkitError429, MeshkitError500 and MeshkitError502 responses for an operation whose server answers its refusals this way.

Field	Type	Required	Description
`code`	string	No	MeshKit error code, a component-scoped identifier allocated by the emitting service (e.g. `<component>-<number>`); it is not a stable part of this contract. Omitted for an error that is not a MeshKit error.
`error`	string	Yes	The sentence the caller is shown.
`probableCause`	array of string	No	MeshKit’s probable causes of the error.
`severity`	string	No	MeshKit severity name. Omitted when MeshKit reports none.
`suggestedRemediation`	array of string	No	MeshKit’s suggested remediations for the error.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/events/delete

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/events/delete

Request body

application/json Required

Payload for bulk-deleting events by ID.

Field	Type	Required	Description
`ids`	array of string (uuid)	Yes	UUIDs of the events to delete.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Response body returned after bulk event deletion.

Field	Type	Required	Description
`deleted`	array of string (uuid)	No	UUIDs of events that were deleted.

Schema: string

A MeshKit error answered as a JSON body. error is the sentence the caller is shown; MeshKit’s long description is never serialized. Use the MeshkitError400, MeshkitError403, MeshkitError404, MeshkitError409, MeshkitError429, MeshkitError500 and MeshkitError502 responses for an operation whose server answers its refusals this way.

Field	Type	Required	Description
`code`	string	No	MeshKit error code, a component-scoped identifier allocated by the emitting service (e.g. `<component>-<number>`); it is not a stable part of this contract. Omitted for an error that is not a MeshKit error.
`error`	string	Yes	The sentence the caller is shown.
`probableCause`	array of string	No	MeshKit’s probable causes of the error.
`severity`	string	No	MeshKit severity name. Omitted when MeshKit reports none.
`suggestedRemediation`	array of string	No	MeshKit’s suggested remediations for the error.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/events/status

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/events/status

Request body

application/json Required

Payload for bulk-updating the status of events.

Field	Type	Required	Description
`ids`	array of string (uuid)	Yes	UUIDs of the events to update.
`status`	string	Yes	New status to apply to the selected events.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Response body returned after bulk event status update.

Field	Type	Required	Description
`updated`	array of string (uuid)	No	UUIDs of events whose status was updated.

Schema: string

A MeshKit error answered as a JSON body. error is the sentence the caller is shown; MeshKit’s long description is never serialized. Use the MeshkitError400, MeshkitError403, MeshkitError404, MeshkitError409, MeshkitError429, MeshkitError500 and MeshkitError502 responses for an operation whose server answers its refusals this way.

Field	Type	Required	Description
`code`	string	No	MeshKit error code, a component-scoped identifier allocated by the emitting service (e.g. `<component>-<number>`); it is not a stable part of this contract. Omitted for an error that is not a MeshKit error.
`error`	string	Yes	The sentence the caller is shown.
`probableCause`	array of string	No	MeshKit’s probable causes of the error.
`severity`	string	No	MeshKit severity name. Omitted when MeshKit reports none.
`suggestedRemediation`	array of string	No	MeshKit’s suggested remediations for the error.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/events/{eventId}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/events/{eventId}

Parameters

Path parameters

Name	Type	Required	Description
`eventId`	string (uuid)	Yes	ID of the event.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Schema: string

A MeshKit error answered as a JSON body. error is the sentence the caller is shown; MeshKit’s long description is never serialized. Use the MeshkitError400, MeshkitError403, MeshkitError404, MeshkitError409, MeshkitError429, MeshkitError500 and MeshkitError502 responses for an operation whose server answers its refusals this way.

Field	Type	Required	Description
`code`	string	No	MeshKit error code, a component-scoped identifier allocated by the emitting service (e.g. `<component>-<number>`); it is not a stable part of this contract. Omitted for an error that is not a MeshKit error.
`error`	string	Yes	The sentence the caller is shown.
`probableCause`	array of string	No	MeshKit’s probable causes of the error.
`severity`	string	No	MeshKit severity name. Omitted when MeshKit reports none.
`suggestedRemediation`	array of string	No	MeshKit’s suggested remediations for the error.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/events/{eventId}/status

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/events/{eventId}/status

Parameters

Path parameters

Name	Type	Required	Description
`eventId`	string (uuid)	Yes	ID of the event.

Request body

application/json Required

Payload for updating the status of a single event.

Field	Type	Required	Description
`status`	string	Yes	Current status of the event.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Response body returned after updating an event’s status.

Field	Type	Required	Description
`eventId`	string (uuid)	No	UUID of the event whose status was updated.
`message`	string	No	Human-readable status message.
`status`	string	No	Updated status of the event.

Schema: string

A MeshKit error answered as a JSON body. error is the sentence the caller is shown; MeshKit’s long description is never serialized. Use the MeshkitError400, MeshkitError403, MeshkitError404, MeshkitError409, MeshkitError429, MeshkitError500 and MeshkitError502 responses for an operation whose server answers its refusals this way.

Field	Type	Required	Description
`code`	string	No	MeshKit error code, a component-scoped identifier allocated by the emitting service (e.g. `<component>-<number>`); it is not a stable part of this contract. Omitted for an error that is not a MeshKit error.
`error`	string	Yes	The sentence the caller is shown.
`probableCause`	array of string	No	MeshKit’s probable causes of the error.
`severity`	string	No	MeshKit severity name. Omitted when MeshKit reports none.
`suggestedRemediation`	array of string	No	MeshKit’s suggested remediations for the error.

Schema: string

Authentication

Bearer JWT

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/identity/orgs

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/identity/orgs

Parameters

Query parameters

Name	Type	Required	Description
`page`	integer	No	Zero-based index of the result page to return.
`pageSize`	integer	No	Maximum number of items returned on each page.
`search`	string	No	Get responses that match search param value
`order`	string	No	Get ordered responses
`all`	boolean	No	Get all possible entries

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Paginated list of organizations.

Field	Type	Required	Description
`organizations`	array of object	No	Organizations in this page.
`page`	integer	No	Zero-based page index returned in this response.
`pageSize`	integer	No	Maximum number of items returned on each page.
`totalCount`	integer	No	Total number of items across all pages.

Schema: string

Authentication

Bearer JWT

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/identity/orgs

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/identity/orgs

Request body

application/json Required

Body for creating or updating an organization

Payload for creating or updating an organization. Contains only client-settable fields.

Field	Type	Required	Description
`country`	string	No	Country of the organization.
`description`	string	No	Description of the organization.
`name`	string	No	Name of the organization.
`notifyOrgUpdate`	boolean	No	Indicates whether organization members should be notified of this update.
`preferences`	object	No	Organization-level user experience preferences.
`region`	string	No	Region of the organization.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Single-organization wrapper used by current meshery-cloud organization handlers.

Field	Type	Required	Description
`organizations`	array of object	No	Organizations returned in this single-item page wrapper.
`page`	integer	No	Zero-based page index returned in this response.
`pageSize`	integer	No	Maximum number of items returned on each page.
`totalCount`	integer	No	Total number of items across all pages.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/identity/orgs/by-domain

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/identity/orgs/by-domain

Parameters

Query parameters

Name	Type	Required	Description
`domain`	string	Yes	Domain name of the organization to look up.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

An organization in Meshery Cloud. Organizations are the top-level tenancy boundary and own teams, workspaces, environments, designs, and other resources. Learn more at https://docs.meshery.io/concepts/logical/organizations

Field	Type	Required	Description
`country`	string	Yes	Country of the organization.
`createdAt`	string (date-time)	Yes	Timestamp when the organization was created.
`deletedAt`	string (date-time)	No	Timestamp when the organization was soft-deleted. Null while the organization is active.
`description`	string	Yes	Description of the organization.
`domain`	string \| null	No	Domain of the organization.
`id`	string (uuid)	Yes	Organization ID.
`metadata`	object	Yes	Free-form metadata associated with the organization, including preferences.
`name`	string	Yes	Name of the organization.
`owner`	string (uuid)	Yes	Owner user ID of the organization.
`region`	string	Yes	Region of the organization.
`updatedAt`	string (date-time)	Yes	Timestamp when the organization was last updated.

Schema: string

Authentication

Bearer JWT

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/identity/orgs/{orgId}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/identity/orgs/{orgId}

Parameters

Path parameters

Name	Type	Required	Description
`orgId`	string (uuid)	Yes	Organization ID.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Single-organization wrapper used by current meshery-cloud organization handlers.

Field	Type	Required	Description
`organizations`	array of object	No	Organizations returned in this single-item page wrapper.
`page`	integer	No	Zero-based page index returned in this response.
`pageSize`	integer	No	Maximum number of items returned on each page.
`totalCount`	integer	No	Total number of items across all pages.

Schema: string

Authentication

Bearer JWT

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/identity/orgs/{orgId}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/identity/orgs/{orgId}

Parameters

Path parameters

Name	Type	Required	Description
`orgId`	string (uuid)	Yes	Organization ID.

Request body

application/json Required

Body for creating or updating an organization

Payload for creating or updating an organization. Contains only client-settable fields.

Field	Type	Required	Description
`country`	string	No	Country of the organization.
`description`	string	No	Description of the organization.
`name`	string	No	Name of the organization.
`notifyOrgUpdate`	boolean	No	Indicates whether organization members should be notified of this update.
`preferences`	object	No	Organization-level user experience preferences.
`region`	string	No	Region of the organization.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Single-organization wrapper used by current meshery-cloud organization handlers.

Field	Type	Required	Description
`organizations`	array of object	No	Organizations returned in this single-item page wrapper.
`page`	integer	No	Zero-based page index returned in this response.
`pageSize`	integer	No	Maximum number of items returned on each page.
`totalCount`	integer	No	Total number of items across all pages.

Schema: string

Authentication

Bearer JWT

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/identity/orgs/{orgId}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/identity/orgs/{orgId}

Parameters

Path parameters

Name	Type	Required	Description
`orgId`	string (uuid)	Yes	Organization ID.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Schema: string

Organization GET

/api/identity/orgs/{orgId}/children

Read the direct child organizations of an organization

Returns the live organizations whose parent is the organization named by orgId, as the ChildOrganization projection. Only direct children are returned; the hierarchy has no depth limit, and a listed child may itself be a parent, but this operation never walks grandchildren or ancestors. Authorization is the View Organizations permission key evaluated in the parent (orgId); a caller without it receives 403 before any lookup, and a parent the caller may see but that has no children is a 200 with an empty page. The Provider Organization is never a parent, so it has no children to list.

Authentication

Bearer JWT

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/identity/orgs/{orgId}/children

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/identity/orgs/{orgId}/children

Parameters

Path parameters

Name	Type	Required	Description
`orgId`	string (uuid)	Yes	Organization ID.

Query parameters

Name	Type	Required	Description
`page`	integer	No	Zero-based index of the result page to return.
`pageSize`	integer	No	Maximum number of items returned on each page.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Page of the direct child organizations of one parent. Carries only the organizations list and the total count; it is not the OrganizationsPage wrapper, whose AvailableOrganization rows expose owner and metadata.

Field	Type	Required	Description
`organizations`	array of object	Yes	Direct child organizations in this page.
`totalCount`	integer	Yes	Total number of live direct children across all pages.

Schema: string

Organization POST

/api/identity/orgs/{orgId}/children

Create a child organization

Creates a new organization whose parent is the organization named by orgId. The path is the parent; the body is the same organization payload the flat create accepts (name, country, region, description) and carries no parentId - a parentId in the body is ignored. The parent is stamped at creation and cannot be changed afterwards. Authorization is the Create Organization permission key evaluated in the parent (orgId). The Provider Organization is never a valid parent: naming it, or the “all” scope, as orgId is refused with 403. A missing or soft-deleted parent is 404, and the body does not distinguish the two. An empty name is 400. On success the creator receives Organization Admin in the new child and the response is the same single-organization page wrapper the flat create returns; parentId is absent from it.

Authentication

Bearer JWT

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/identity/orgs/{orgId}/children

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/identity/orgs/{orgId}/children

Parameters

Path parameters

Name	Type	Required	Description
`orgId`	string (uuid)	Yes	Organization ID.

Request body

application/json Required

Body for creating or updating an organization

Payload for creating or updating an organization. Contains only client-settable fields.

Field	Type	Required	Description
`country`	string	No	Country of the organization.
`description`	string	No	Description of the organization.
`name`	string	No	Name of the organization.
`notifyOrgUpdate`	boolean	No	Indicates whether organization members should be notified of this update.
`preferences`	object	No	Organization-level user experience preferences.
`region`	string	No	Region of the organization.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Single-organization wrapper used by current meshery-cloud organization handlers.

Field	Type	Required	Description
`organizations`	array of object	No	Organizations returned in this single-item page wrapper.
`page`	integer	No	Zero-based page index returned in this response.
`pageSize`	integer	No	Maximum number of items returned on each page.
`totalCount`	integer	No	Total number of items across all pages.

Schema: string

Authentication

Bearer JWT

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/identity/orgs/{orgId}/preferences

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/identity/orgs/{orgId}/preferences

Parameters

Path parameters

Name	Type	Required	Description
`orgId`	string (uuid)	Yes	Organization ID.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Free-form metadata associated with an organization, including preferences.

Field	Type	Required	Description
`preferences`	object	Yes	Organization-level user experience preferences.

Schema: string

Organization PATCH

/api/identity/orgs/{orgId}/preferences

Partially update organization preferences

Merges the body into the organization’s stored preferences. Every member of the body is optional: a member that is present replaces that member of the stored preferences as a whole, and a member that is omitted stays unchanged. An empty body changes nothing and returns the current preferences. Members may not be null. Authorization is the same as updating the organization (updateOrg) for every member, and changing schedulePause is additionally restricted to organization admins (otherwise 403, and nothing is written). Lifting the pause clears its reason and server-recorded fields exactly as updateOrg does. The optional If-Match header makes the write conditional on the entity tag the preferences carried when they were read (see the ETag header of getOrgPreferences and of this response): when it no longer matches, the request is refused with 412 and nothing is written. Without If-Match the write is unconditional.

Authentication

Bearer JWT

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/identity/orgs/{orgId}/preferences

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/identity/orgs/{orgId}/preferences

Parameters

Path parameters

Name	Type	Required	Description
`orgId`	string (uuid)	Yes	Organization ID.

Header parameters

Name	Type	Required	Description
`If-Match`	string	No	Entity tag of the organization’s preferences as last read, from the `ETag` header of getOrgPreferences or patchOrgPreferences. When present the write applies only if it still matches; otherwise 412.

Request body

application/json Required

Partial update of organization preferences (patchOrgPreferences). Every member is optional: a present member replaces that member of the stored preferences as a whole, and an omitted member stays unchanged. Members are those of PreferencesPayload, with the same schemas, and may not be null.

Field	Type	Required	Description
`authBranding`	object	No	Optional per-organization branding overrides for the auth pages: carousel slides and FAQ entries. Stored as JSON inside organization.metadata.preferences, so no dedicated column backs it. Empty or omitted fields fall back to the platform defaults.
`dashboard`	object	No	Preferences specific to dashboard behavior.
`links`	object	No	Per-organization overrides for the legal, support, and social links shown on the auth pages and the error page. termsOfService and privacy are the named legal links; support is an open-ended set of named support contacts/links; social carries the organization’s brand profiles. Empty or omitted fields fall back to the platform defaults.
`schedulePause`	object	No	Organization-wide schedule pause. Only organization admins may set or lift it; a write from anyone else that changes it is refused with 403. Omitted keeps the current pause unchanged; it does not lift the pause.
`showAuthCarousel`	boolean	No	Whether the feature carousel renders on the organization’s auth pages. Omitted keeps the stored value.
`theme`	object	No	UI theme configured for an organization.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Free-form metadata associated with an organization, including preferences.

Field	Type	Required	Description
`preferences`	object	Yes	Organization-level user experience preferences.

Schema: string

Authentication

Bearer JWT

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/identity/orgs/{orgId}/teams/{teamId}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/identity/orgs/{orgId}/teams/{teamId}

Parameters

Path parameters

Name	Type	Required	Description
`orgId`	string (uuid)	Yes	Organization ID.
`teamId`	string (uuid)	Yes	Team ID.

Request body

application/json Optional

Optional action payload for POST on /api/identity/orgs/{orgId}/teams/{teamId}.

Field	Type	Required	Description
`action`	string	No	Internal action to perform on the team resource.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Schema: one of object

object

Paginated list of team-organization mappings.

Field	Type	Required	Description
`page`	integer	No	Zero-based page index returned in this response.
`pageSize`	integer	No	Maximum number of items returned on each page.
`teamsOrganizationsMapping`	array of object	No	Team-organization mapping entries.
`totalCount`	integer	No	Total number of items across all pages.

object

Paginated list of teams.

Field	Type	Required	Description
`page`	integer	No	Zero-based page index returned in this response.
`pageSize`	integer	No	Maximum number of items returned on each page.
`teams`	array of object	No	Teams in this page.
`totalCount`	integer	No	Total number of items across all pages.

Schema: string

Authentication

Bearer JWT

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/identity/orgs/{orgId}/teams/{teamId}/remove

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/identity/orgs/{orgId}/teams/{teamId}/remove

Parameters

Path parameters

Name	Type	Required	Description
`orgId`	string (uuid)	Yes	Organization ID.
`teamId`	string (uuid)	Yes	Team ID.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Paginated list of team-organization mappings.

Field	Type	Required	Description
`page`	integer	No	Zero-based page index returned in this response.
`pageSize`	integer	No	Maximum number of items returned on each page.
`teamsOrganizationsMapping`	array of object	No	Team-organization mapping entries.
`totalCount`	integer	No	Total number of items across all pages.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/identity/orgs/{orgId}/users

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/identity/orgs/{orgId}/users

Parameters

Path parameters

Name	Type	Required	Description
`orgId`	string (uuid)	Yes	Organization ID

Query parameters

Name	Type	Required	Description
`page`	integer	No	Get responses by page
`pageSize`	integer	No	Get responses by page size
`search`	string	No	Get responses that match search param value
`order`	string	No	Get ordered responses
`filter`	string	No	Get filtered reponses
`teamId`	string (uuid)	No	Optional team filter when listing organization users

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Paginated list of users with organization and team role context

Field	Type	Required	Description
`data`	array of object	No	The data of the userspageforadmin.
`page`	integer	No	Current page number of the result set.
`pageSize`	integer	No	Number of items per page.
`totalCount`	integer	No	Total number of items available.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/identity/orgs/{orgId}/users/keys

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/identity/orgs/{orgId}/users/keys

Parameters

Path parameters

Name	Type	Required	Description
`orgId`	string (uuid)	Yes	Organization ID

Query parameters

Name	Type	Required	Description
`page`	integer	No	Get responses by page
`pageSize`	integer	No	Number of responses to return per page. Canonical camelCase pagination parameter; prefer this over the deprecated all-lowercase `pagesize`.
`pagesize`	integer	No	Get responses by pagesize. Deprecated alias of pageSize.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

A paginated list of authorization keys.

Field	Type	Required	Description
`page`	integer	Yes	Zero-based page index returned in this response.
`pageSize`	integer	Yes	Maximum number of items returned on each page.
`totalCount`	integer	Yes	Total number of items across all pages.
`keys`	array of object	Yes	Keys returned on the current page.

Schema: string

Authentication

Bearer JWT

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/identity/orgs/{orgId}/users/{userId}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/identity/orgs/{orgId}/users/{userId}

Parameters

Path parameters

Name	Type	Required	Description
`orgId`	string (uuid)	Yes	Organization ID.
`userId`	string (uuid)	Yes	User ID.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Schema: object

Schema: string

Authentication

Bearer JWT

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/identity/orgs/{orgId}/users/{userId}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/identity/orgs/{orgId}/users/{userId}

Parameters

Path parameters

Name	Type	Required	Description
`orgId`	string (uuid)	Yes	Organization ID.
`userId`	string (uuid)	Yes	User ID.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/identity/users/profile

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/identity/users/profile

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Represents a user

Field	Type	Required	Description
`acceptedTermsAt`	string (date-time)	No	Timestamp when user accepted terms and conditions
`avatarUrl`	string (uri)	No	URL to user’s avatar image
`bio`	string	No	User’s biography or description
`country`	object	No	User’s country information stored as JSONB
`createdAt`	string (date-time)	Yes	Timestamp when the user record was created
`deletedAt`	string \| null (date-time)	Yes	Timestamp when the user record was soft-deleted (null if not deleted)
`email`	string (email)	Yes	User’s email address
`firstLoginTime`	string (date-time)	No	Timestamp of user’s first login
`firstName`	string	Yes	User’s first name
`id`	string (uuid)	Yes	Unique identifier for the user
`lastLoginTime`	string (date-time)	Yes	Timestamp of user’s most recent login
`lastName`	string	Yes	User’s last name
`organizations`	object	No	Organizations the user belongs to with role information
`preferences`	object	No	User preferences stored as JSONB
`provider`	string	Yes	Authentication provider (e.g., Google, Github)
`region`	object	No	User’s region information stored as JSONB
`roleNames`	array of string	No	Names of the global roles assigned to the user. Free-form, user-generated values sourced from the roles table (role_name is a varchar, not a fixed enumeration); the seeded system roles such as “admin”, “organization admin” and “user” are a subset, not the whole set.
`socials`	array of object	No	Various online profiles associated with the user account
`status`	string	Yes	User account status
`teams`	object	No	Teams the user belongs to with role information
`updatedAt`	string (date-time)	Yes	Timestamp when the user record was last updated
`userId`	string	Yes	Legacy IdP-derived identifier. Removed in v1beta3; resolve users by id or email.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/identity/users/profile/{id}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/identity/users/profile/{id}

Parameters

Path parameters

Name	Type	Required	Description
`id`	string (uuid)	Yes	User ID

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Represents a user

Field	Type	Required	Description
`acceptedTermsAt`	string (date-time)	No	Timestamp when user accepted terms and conditions
`avatarUrl`	string (uri)	No	URL to user’s avatar image
`bio`	string	No	User’s biography or description
`country`	object	No	User’s country information stored as JSONB
`createdAt`	string (date-time)	Yes	Timestamp when the user record was created
`deletedAt`	string \| null (date-time)	Yes	Timestamp when the user record was soft-deleted (null if not deleted)
`email`	string (email)	Yes	User’s email address
`firstLoginTime`	string (date-time)	No	Timestamp of user’s first login
`firstName`	string	Yes	User’s first name
`id`	string (uuid)	Yes	Unique identifier for the user
`lastLoginTime`	string (date-time)	Yes	Timestamp of user’s most recent login
`lastName`	string	Yes	User’s last name
`organizations`	object	No	Organizations the user belongs to with role information
`preferences`	object	No	User preferences stored as JSONB
`provider`	string	Yes	Authentication provider (e.g., Google, Github)
`region`	object	No	User’s region information stored as JSONB
`roleNames`	array of string	No	Names of the global roles assigned to the user. Free-form, user-generated values sourced from the roles table (role_name is a varchar, not a fixed enumeration); the seeded system roles such as “admin”, “organization admin” and “user” are a subset, not the whole set.
`socials`	array of object	No	Various online profiles associated with the user account
`status`	string	Yes	User account status
`teams`	object	No	Teams the user belongs to with role information
`updatedAt`	string (date-time)	Yes	Timestamp when the user record was last updated
`userId`	string	Yes	Legacy IdP-derived identifier. Removed in v1beta3; resolve users by id or email.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/identity/users/search

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/identity/users/search

Parameters

Query parameters

Name	Type	Required	Description
`page`	integer	No	Get responses by page
`pageSize`	integer	No	Number of responses to return per page. Canonical camelCase pagination parameter; prefer this over the deprecated all-lowercase `pagesize`.
`search`	string	No	Get responses that match search param value
`order`	string	No	Get ordered responses
`filter`	string	No	Get filtered reponses

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Paginated list of users in the searchable collaboration projection

Field	Type	Required	Description
`data`	array of object	Yes	Matching user records for the requested page.
`page`	integer	Yes	Current page number of the result set.
`pageSize`	integer	Yes	Number of items per page.
`totalCount`	integer	Yes	Total number of items available.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/identity/users/{userId}/emails

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/identity/users/{userId}/emails

Parameters

Path parameters

Name	Type	Required	Description
`userId`	string (uuid)	Yes	ID of the user

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Schema: array of object

Field	Type	Required	Description
`createdAt`	string (date-time)	Yes	No description provided.
`deletedAt`	string \| null (date-time)	No	SQL null Timestamp to handle null values of time.
`email`	string (email)	Yes	The email address
`id`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`isPrimary`	boolean	Yes	Exactly one live primary address per user; mirrors users.email
`source`	string	Yes	How this address became associated with the account
`updatedAt`	string (date-time)	Yes	No description provided.
`userId`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`verified`	boolean	Yes	Whether the address was verified (per Kratos verifiable addresses) at record time

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/integrations/connections

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/integrations/connections

Parameters

Query parameters

Name	Type	Required	Description
`page`	integer	No	Page number
`pageSize`	integer	No	Number of items per page
`search`	string	No	Search term
`order`	string	No	Sort order
`orgId`	string (uuid)	No	Organization ID to scope the request.
`filter`	string	No	Filter connections (general filter string)
`kind`	array of string	No	Filter by connection kind (e.g., kubernetes, prometheus, grafana)
`status`	array of string	No	Filter by connection status
`type`	array of string	No	Filter by connection type
`name`	string	No	Filter by connection name (partial match supported)

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Represents a page of connections with meta information about connections count

Field	Type	Required	Description
`connections`	array of object	Yes	List of connections on this page
`totalCount`	integer	Yes	Total number of connections on all pages
`page`	integer	Yes	Current page number
`pageSize`	integer	Yes	Number of elements per page
`statusSummary`	object	No	Aggregate count of connections grouped by status

Schema: string

Connection API Connections POST

/api/integrations/connections

Register a new connection

Register a new connection with credentials. Meshery Cloud reserves the GitHub App connection’s identity (name GitHub App, sub_type git): only its GitHub authorization flow creates that connection, so a request naming it is refused with a 409 MeshKit error that names the reserved GitHub App connection identity.

Every connection belongs to exactly one organization. The server assigns organizationId from the session (X-Current-Orgid, then the caller’s selected organization) and does not accept it in the body. When the session names none, the server may use the caller’s only organization (Meshery Cloud: the only live organization the caller belongs to, else the only one of those the caller owns); it must not guess between several, and answers 400 instead.

Desktop registration uses this shared operation, but kind desktop is implemented by Cloud: a server that does not support it rejects a desktop body with 400. The heartbeat and deregistration routes are Cloud-only. A client desktop app install registers itself on every connect to Cloud, sign-in included, with kind desktop, type platform, sub_type management, status connected, and metadata matching DesktopConnectionMetadata. Servers implementing this contract must take the organization from the X-Current-Orgid header, refuse a desktop registration without it with 400, and refuse a caller who is not a live member of that organization with 403. They must deduplicate on (organization, owner, metadata.installationId): registering the same install again updates that connection and returns 200, while a new connection returns 201. A desktop body whose metadata lacks installationId is refused with 400. Installs on one computer share metadata.computerId, so a server can group them by computer. The kind names the connection type, never the product that runs on the machine.

A desktop registration whose metadata.clientName and metadata.appVersion fall below the server’s minimum version for that client is refused with 426 and a ClientUpgradeRequiredError body; the connection, when it exists, is set to maintenance. Servers must link the API token that authenticated the registration to the connection (metadata.tokenId, server-written) and revoke that token when the connection is deregistered or deleted. When a later registration of the same connection authenticates with a different token, the server revokes the token previously linked to it. Registrations beyond the organization’s device limit are accepted; the organization is flagged through the capabilities document’s session.deviceUsage instead.

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/integrations/connections

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/integrations/connections

Parameters

Header parameters

Name	Type	Required	Description
`X-Current-Orgid`	string (uuid)	No	Session organization. The server assigns `Connection.organizationId` from this header when it is present, and from the caller’s selected organization when it is absent. Kind `desktop` requires the header: a desktop registration without it is refused with 400.

Request body

application/json Required

Payload for creating or updating a connection. organizationId is not a client field. The server assigns it from the session organization.

Field	Type	Required	Description
`credentialId`	string (uuid)	No	Associated credential ID
`credentialSecret`	object	No	Credential secret data
`id`	string (uuid)	No	Connection ID
`kind`	string	Yes	Connection kind
`metadata`	object	No	Connection metadata
`name`	string	Yes	Connection name
`status`	string	Yes	Connection status
`styles`	object	No	Visualization styles for the connection, including svgColor and svgWhite used for UI representation.
`subType`	string	Yes	Connection sub-type
`type`	string	Yes	Connection type

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Meshery Connections are managed and unmanaged resources that either through discovery or manual entry are tracked by Meshery. Learn more at https://docs.meshery.io/concepts/logical/connections

Field	Type	Required	Description
`id`	string (uuid)	Yes	Connection ID
`name`	string	Yes	Connection Name
`description`	string	No	Human-readable description of the connection and its purpose.
`url`	string (uri)	No	URL of the remote resource this connection points to (e.g. the Helm repository URL, the Kubernetes API server endpoint, the Grafana instance URL).
`credentialId`	string (uuid)	No	Associated Credential ID
`type`	string	Yes	Connection Type (platform, telemetry, collaboration)
`subType`	string	Yes	Connection Subtype (cloud, identity, metrics, chat, git, orchestration)
`kind`	string	Yes	Connection Kind (meshery, kubernetes, prometheus, grafana, gke, aws, azure, slack, github, desktop)
`modelReference`	object	No	Reference to the specific registered model to which the component belongs and from which model version, category, and other properties may be referenced. Learn more at https://docs.meshery.io/concepts/models
`connectionSchema`	object	No	Schema for the connection
`credentialSchema`	object	No	Schema for the credential Associated with the connection
`metadata`	object	No	Additional connection metadata
`status`	string	Yes	Connection Status
`owner`	string (uuid)	No	User ID who owns this connection
`createdAt`	string (date-time)	No	Timestamp when the connection was created.
`updatedAt`	string (date-time)	No	Timestamp when the connection was last updated.
`deletedAt`	string \| null (date-time)	No	Timestamp when the connection was soft-deleted, if applicable.
`environments`	array of object	No	Associated environments for this connection
`schemaVersion`	string	Yes	Specifies the version of the schema used for the definition.
`styles`	object	No	Visualization styles for the connection, including svgColor and svgWhite used for UI representation.
`transitionMap`	object	No	Map describing the connection state machine. Each key is a current connection status and its value is the list of states the connection may transition to from that status, along with a description of each transition.
`organizationId`	string (uuid)	Yes	The organization the connection belongs to. The server sets it from the session organization (`X-Current-Orgid`, or the caller’s selected organization when that header is absent) when the connection is registered, and keeps it on later updates. Never accepted from clients on connection write payloads. Not marked readOnly: `RegistrantData` inlines this entity into registry registration requests, and readOnly there drops the connection field from the generated RTK client. A value sent on that inlined connection is ignored. With the owner and `metadata.installationId`, it is the deduplication key for `desktop` connections.

Meshery Connections are managed and unmanaged resources that either through discovery or manual entry are tracked by Meshery. Learn more at https://docs.meshery.io/concepts/logical/connections

Field	Type	Required	Description
`id`	string (uuid)	Yes	Connection ID
`name`	string	Yes	Connection Name
`description`	string	No	Human-readable description of the connection and its purpose.
`url`	string (uri)	No	URL of the remote resource this connection points to (e.g. the Helm repository URL, the Kubernetes API server endpoint, the Grafana instance URL).
`credentialId`	string (uuid)	No	Associated Credential ID
`type`	string	Yes	Connection Type (platform, telemetry, collaboration)
`subType`	string	Yes	Connection Subtype (cloud, identity, metrics, chat, git, orchestration)
`kind`	string	Yes	Connection Kind (meshery, kubernetes, prometheus, grafana, gke, aws, azure, slack, github, desktop)
`modelReference`	object	No	Reference to the specific registered model to which the component belongs and from which model version, category, and other properties may be referenced. Learn more at https://docs.meshery.io/concepts/models
`connectionSchema`	object	No	Schema for the connection
`credentialSchema`	object	No	Schema for the credential Associated with the connection
`metadata`	object	No	Additional connection metadata
`status`	string	Yes	Connection Status
`owner`	string (uuid)	No	User ID who owns this connection
`createdAt`	string (date-time)	No	Timestamp when the connection was created.
`updatedAt`	string (date-time)	No	Timestamp when the connection was last updated.
`deletedAt`	string \| null (date-time)	No	Timestamp when the connection was soft-deleted, if applicable.
`environments`	array of object	No	Associated environments for this connection
`schemaVersion`	string	Yes	Specifies the version of the schema used for the definition.
`styles`	object	No	Visualization styles for the connection, including svgColor and svgWhite used for UI representation.
`transitionMap`	object	No	Map describing the connection state machine. Each key is a current connection status and its value is the list of states the connection may transition to from that status, along with a description of each transition.
`organizationId`	string (uuid)	Yes	The organization the connection belongs to. The server sets it from the session organization (`X-Current-Orgid`, or the caller’s selected organization when that header is absent) when the connection is registered, and keeps it on later updates. Never accepted from clients on connection write payloads. Not marked readOnly: `RegistrantData` inlines this entity into registry registration requests, and readOnly there drops the connection field from the generated RTK client. A value sent on that inlined connection is ignored. With the owner and `metadata.installationId`, it is the deduplication key for `desktop` connections.

Schema: string

A MeshKit error answered as a JSON body. error is the sentence the caller is shown; MeshKit’s long description is never serialized. Use the MeshkitError400, MeshkitError403, MeshkitError404, MeshkitError409, MeshkitError429, MeshkitError500 and MeshkitError502 responses for an operation whose server answers its refusals this way.

Field	Type	Required	Description
`code`	string	No	MeshKit error code, a component-scoped identifier allocated by the emitting service (e.g. `<component>-<number>`); it is not a stable part of this contract. Omitted for an error that is not a MeshKit error.
`error`	string	Yes	The sentence the caller is shown.
`probableCause`	array of string	No	MeshKit’s probable causes of the error.
`severity`	string	No	MeshKit severity name. Omitted when MeshKit reports none.
`suggestedRemediation`	array of string	No	MeshKit’s suggested remediations for the error.

Body of a 426 answer: a MeshKit error sentence plus the client’s compatibility, so the client can show the minimum and where to update.

Field	Type	Required	Description
`code`	string	No	MeshKit error code allocated by the emitting service; not a stable part of this contract.
`compatibility`	object	Yes	Whether a client application’s version meets the provider’s minimum for that client. A client whose `compatible` is false must update before it registers or keeps a connection alive; the provider answers those calls with 426. A client the provider has no minimum for is compatible and has no `minimumVersion`.
`error`	string	Yes	The sentence the caller is shown.

A MeshKit error answered as a JSON body. error is the sentence the caller is shown; MeshKit’s long description is never serialized. Use the MeshkitError400, MeshkitError403, MeshkitError404, MeshkitError409, MeshkitError429, MeshkitError500 and MeshkitError502 responses for an operation whose server answers its refusals this way.

Field	Type	Required	Description
`code`	string	No	MeshKit error code, a component-scoped identifier allocated by the emitting service (e.g. `<component>-<number>`); it is not a stable part of this contract. Omitted for an error that is not a MeshKit error.
`error`	string	Yes	The sentence the caller is shown.
`probableCause`	array of string	No	MeshKit’s probable causes of the error.
`severity`	string	No	MeshKit severity name. Omitted when MeshKit reports none.
`suggestedRemediation`	array of string	No	MeshKit’s suggested remediations for the error.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/integrations/connections/kubernetes/{connectionId}/context

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/integrations/connections/kubernetes/{connectionId}/context

Parameters

Path parameters

Name	Type	Required	Description
`connectionId`	string (uuid)	Yes	Connection ID

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Paginated list of Kubernetes contexts.

Field	Type	Required	Description
`contexts`	array of object	Yes	Kubernetes contexts in this page.
`page`	integer	Yes	Zero-based page index returned in this response.
`pageSize`	integer	Yes	Maximum number of items returned on each page.
`totalCount`	integer	Yes	Total number of items across all pages.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/integrations/connections/meshery/{mesheryServerId}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/integrations/connections/meshery/{mesheryServerId}

Parameters

Path parameters

Name	Type	Required	Description
`mesheryServerId`	string (uuid)	Yes	Meshery server ID

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Schema: string

Connection API Connections POST

/api/integrations/connections/register

Drive the connection registration state machine

Dispatches a lifecycle event for an in-progress connection registration. With status initialize, responds with the registration bootstrap - the kind’s connection (and credential, when one exists) registry component definitions plus a tracker id the client echoes on subsequent events. Every other status is forwarded to the tracked registration’s state machine and the response body is empty.

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/integrations/connections/register

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/integrations/connections/register

Request body

application/json Required

Lifecycle event for the connection registration state machine (POST /api/integrations/connections/register). Unlike ConnectionPayload, only kind and status are always present: an initialize event carries just the kind, while register / connect events carry the connection details assembled so far.

Field	Type	Required	Description
`credentialId`	string (uuid)	No	Existing credential to associate instead of a new secret.
`credentialSecret`	object	No	Credential secret material for the connection.
`id`	string (uuid)	No	Registration process tracker. Returned by the `initialize` bootstrap or minted client-side; echoed on every subsequent event for the same registration.
`kind`	string	Yes	Connection kind (e.g. `kubernetes`, `grafana`, `prometheus`).
`metadata`	object	No	Connection metadata gathered so far in the flow.
`model`	string	No	Registry model the connection’s definition belongs to.
`name`	string	No	Connection name.
`skipCredentialVerification`	boolean	No	When true the server registers the connection without verifying the supplied credential first.
`status`	string	Yes	State-machine event to dispatch. `initialize` returns the registration bootstrap; every other event advances the tracked registration. `not found` is the machine’s literal event name.
`subType`	string	No	Connection sub-type.
`type`	string	No	Connection type.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Response to an initialize registration event: the registry component definitions describing the kind’s connection and credential, plus the tracker id for the registration process. Component definitions carry their RJSF form schema as a JSON-encoded string under schema.

Field	Type	Required	Description
`connection`	object	Yes	Registry component definition (`{Kind}Connection`) describing the connection, including its JSON-encoded `schema`.
`credential`	object	No	Registry component definition (`{Kind}Credential`) describing the credential, including its JSON-encoded `schema`. Absent when the kind defines no credential component.
`id`	string (uuid)	Yes	Registration process tracker to echo on subsequent events.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/integrations/connections/register/{registrationId}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/integrations/connections/register/{registrationId}

Parameters

Path parameters

Name	Type	Required	Description
`registrationId`	string (uuid)	Yes	Registration process tracker id to discard.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/integrations/connections/{connectionId}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/integrations/connections/{connectionId}

Parameters

Path parameters

Name	Type	Required	Description
`connectionId`	string (uuid)	Yes	Connection ID

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Meshery Connections are managed and unmanaged resources that either through discovery or manual entry are tracked by Meshery. Learn more at https://docs.meshery.io/concepts/logical/connections

Field	Type	Required	Description
`id`	string (uuid)	Yes	Connection ID
`name`	string	Yes	Connection Name
`description`	string	No	Human-readable description of the connection and its purpose.
`url`	string (uri)	No	URL of the remote resource this connection points to (e.g. the Helm repository URL, the Kubernetes API server endpoint, the Grafana instance URL).
`credentialId`	string (uuid)	No	Associated Credential ID
`type`	string	Yes	Connection Type (platform, telemetry, collaboration)
`subType`	string	Yes	Connection Subtype (cloud, identity, metrics, chat, git, orchestration)
`kind`	string	Yes	Connection Kind (meshery, kubernetes, prometheus, grafana, gke, aws, azure, slack, github, desktop)
`modelReference`	object	No	Reference to the specific registered model to which the component belongs and from which model version, category, and other properties may be referenced. Learn more at https://docs.meshery.io/concepts/models
`connectionSchema`	object	No	Schema for the connection
`credentialSchema`	object	No	Schema for the credential Associated with the connection
`metadata`	object	No	Additional connection metadata
`status`	string	Yes	Connection Status
`owner`	string (uuid)	No	User ID who owns this connection
`createdAt`	string (date-time)	No	Timestamp when the connection was created.
`updatedAt`	string (date-time)	No	Timestamp when the connection was last updated.
`deletedAt`	string \| null (date-time)	No	Timestamp when the connection was soft-deleted, if applicable.
`environments`	array of object	No	Associated environments for this connection
`schemaVersion`	string	Yes	Specifies the version of the schema used for the definition.
`styles`	object	No	Visualization styles for the connection, including svgColor and svgWhite used for UI representation.
`transitionMap`	object	No	Map describing the connection state machine. Each key is a current connection status and its value is the list of states the connection may transition to from that status, along with a description of each transition.
`organizationId`	string (uuid)	Yes	The organization the connection belongs to. The server sets it from the session organization (`X-Current-Orgid`, or the caller’s selected organization when that header is absent) when the connection is registered, and keeps it on later updates. Never accepted from clients on connection write payloads. Not marked readOnly: `RegistrantData` inlines this entity into registry registration requests, and readOnly there drops the connection field from the generated RTK client. A value sent on that inlined connection is ignored. With the owner and `metadata.installationId`, it is the deduplication key for `desktop` connections.

Schema: string

Connection API Connections PUT

/api/integrations/connections/{connectionId}

Update a connection

Update an existing connection. Meshery Cloud refuses, with a 409 MeshKit error naming the reserved identity, an edit that would give a connection the GitHub App connection’s identity (name GitHub App, sub_type git). On the GitHub App connection itself, the server-written metadata keys installations, installationId and installationsVerifiedAt are carried forward from the stored row: a client edit can neither set nor erase them (other metadata keys are written as sent). Their shape is GithubConnectionMetadata in the v1beta3 github construct. organizationId is not in the body. The server keeps the organization assigned at registration.

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/integrations/connections/{connectionId}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/integrations/connections/{connectionId}

Parameters

Path parameters

Name	Type	Required	Description
`connectionId`	string (uuid)	Yes	Connection ID

Request body

application/json Required

Payload for creating or updating a connection. organizationId is not a client field. The server assigns it from the session organization.

Field	Type	Required	Description
`credentialId`	string (uuid)	No	Associated credential ID
`credentialSecret`	object	No	Credential secret data
`id`	string (uuid)	No	Connection ID
`kind`	string	Yes	Connection kind
`metadata`	object	No	Connection metadata
`name`	string	Yes	Connection name
`status`	string	Yes	Connection status
`styles`	object	No	Visualization styles for the connection, including svgColor and svgWhite used for UI representation.
`subType`	string	Yes	Connection sub-type
`type`	string	Yes	Connection type

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Meshery Connections are managed and unmanaged resources that either through discovery or manual entry are tracked by Meshery. Learn more at https://docs.meshery.io/concepts/logical/connections

Field	Type	Required	Description
`id`	string (uuid)	Yes	Connection ID
`name`	string	Yes	Connection Name
`description`	string	No	Human-readable description of the connection and its purpose.
`url`	string (uri)	No	URL of the remote resource this connection points to (e.g. the Helm repository URL, the Kubernetes API server endpoint, the Grafana instance URL).
`credentialId`	string (uuid)	No	Associated Credential ID
`type`	string	Yes	Connection Type (platform, telemetry, collaboration)
`subType`	string	Yes	Connection Subtype (cloud, identity, metrics, chat, git, orchestration)
`kind`	string	Yes	Connection Kind (meshery, kubernetes, prometheus, grafana, gke, aws, azure, slack, github, desktop)
`modelReference`	object	No	Reference to the specific registered model to which the component belongs and from which model version, category, and other properties may be referenced. Learn more at https://docs.meshery.io/concepts/models
`connectionSchema`	object	No	Schema for the connection
`credentialSchema`	object	No	Schema for the credential Associated with the connection
`metadata`	object	No	Additional connection metadata
`status`	string	Yes	Connection Status
`owner`	string (uuid)	No	User ID who owns this connection
`createdAt`	string (date-time)	No	Timestamp when the connection was created.
`updatedAt`	string (date-time)	No	Timestamp when the connection was last updated.
`deletedAt`	string \| null (date-time)	No	Timestamp when the connection was soft-deleted, if applicable.
`environments`	array of object	No	Associated environments for this connection
`schemaVersion`	string	Yes	Specifies the version of the schema used for the definition.
`styles`	object	No	Visualization styles for the connection, including svgColor and svgWhite used for UI representation.
`transitionMap`	object	No	Map describing the connection state machine. Each key is a current connection status and its value is the list of states the connection may transition to from that status, along with a description of each transition.
`organizationId`	string (uuid)	Yes	The organization the connection belongs to. The server sets it from the session organization (`X-Current-Orgid`, or the caller’s selected organization when that header is absent) when the connection is registered, and keeps it on later updates. Never accepted from clients on connection write payloads. Not marked readOnly: `RegistrantData` inlines this entity into registry registration requests, and readOnly there drops the connection field from the generated RTK client. A value sent on that inlined connection is ignored. With the owner and `metadata.installationId`, it is the deduplication key for `desktop` connections.

Schema: string

A MeshKit error answered as a JSON body. error is the sentence the caller is shown; MeshKit’s long description is never serialized. Use the MeshkitError400, MeshkitError403, MeshkitError404, MeshkitError409, MeshkitError429, MeshkitError500 and MeshkitError502 responses for an operation whose server answers its refusals this way.

Field	Type	Required	Description
`code`	string	No	MeshKit error code, a component-scoped identifier allocated by the emitting service (e.g. `<component>-<number>`); it is not a stable part of this contract. Omitted for an error that is not a MeshKit error.
`error`	string	Yes	The sentence the caller is shown.
`probableCause`	array of string	No	MeshKit’s probable causes of the error.
`severity`	string	No	MeshKit severity name. Omitted when MeshKit reports none.
`suggestedRemediation`	array of string	No	MeshKit’s suggested remediations for the error.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/integrations/connections/{connectionId}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/integrations/connections/{connectionId}

Parameters

Path parameters

Name	Type	Required	Description
`connectionId`	string (uuid)	Yes	Connection ID

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Schema: string

Connection API Connections POST

/api/integrations/connections/{connectionId}/actions

Perform an action on a connection

Perform a side-effecting operation on a connection (as opposed to a field update via PUT). The action is selected by the action discriminator in the request body. Currently supports switching the MeshSync deployment mode for a kubernetes connection, which redeploys MeshSync (operator vs embedded) for the connection’s cluster; the server owns the connection metadata merge so callers only send the intent.

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/integrations/connections/{connectionId}/actions

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/integrations/connections/{connectionId}/actions

Parameters

Path parameters

Name	Type	Required	Description
`connectionId`	string (uuid)	Yes	Connection ID

Request body

application/json Required

A side-effecting operation to perform on a connection via POST /api/integrations/connections/{connectionId}/actions. The action field selects the operation; operation-specific fields carry its parameters. Unlike PUT (which updates resource fields), the server owns any resulting metadata merge and cluster-side effects.

Field	Type	Required	Description
`action`	string	Yes	The operation to perform on the connection.
`mode`	string	No	Target MeshSync deployment mode. Required when `action` is `setMeshsyncMode`; the server redeploys MeshSync (operator vs embedded) for the connection’s cluster.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Meshery Connections are managed and unmanaged resources that either through discovery or manual entry are tracked by Meshery. Learn more at https://docs.meshery.io/concepts/logical/connections

Field	Type	Required	Description
`id`	string (uuid)	Yes	Connection ID
`name`	string	Yes	Connection Name
`description`	string	No	Human-readable description of the connection and its purpose.
`url`	string (uri)	No	URL of the remote resource this connection points to (e.g. the Helm repository URL, the Kubernetes API server endpoint, the Grafana instance URL).
`credentialId`	string (uuid)	No	Associated Credential ID
`type`	string	Yes	Connection Type (platform, telemetry, collaboration)
`subType`	string	Yes	Connection Subtype (cloud, identity, metrics, chat, git, orchestration)
`kind`	string	Yes	Connection Kind (meshery, kubernetes, prometheus, grafana, gke, aws, azure, slack, github, desktop)
`modelReference`	object	No	Reference to the specific registered model to which the component belongs and from which model version, category, and other properties may be referenced. Learn more at https://docs.meshery.io/concepts/models
`connectionSchema`	object	No	Schema for the connection
`credentialSchema`	object	No	Schema for the credential Associated with the connection
`metadata`	object	No	Additional connection metadata
`status`	string	Yes	Connection Status
`owner`	string (uuid)	No	User ID who owns this connection
`createdAt`	string (date-time)	No	Timestamp when the connection was created.
`updatedAt`	string (date-time)	No	Timestamp when the connection was last updated.
`deletedAt`	string \| null (date-time)	No	Timestamp when the connection was soft-deleted, if applicable.
`environments`	array of object	No	Associated environments for this connection
`schemaVersion`	string	Yes	Specifies the version of the schema used for the definition.
`styles`	object	No	Visualization styles for the connection, including svgColor and svgWhite used for UI representation.
`transitionMap`	object	No	Map describing the connection state machine. Each key is a current connection status and its value is the list of states the connection may transition to from that status, along with a description of each transition.
`organizationId`	string (uuid)	Yes	The organization the connection belongs to. The server sets it from the session organization (`X-Current-Orgid`, or the caller’s selected organization when that header is absent) when the connection is registered, and keeps it on later updates. Never accepted from clients on connection write payloads. Not marked readOnly: `RegistrantData` inlines this entity into registry registration requests, and readOnly there drops the connection field from the generated RTK client. A value sent on that inlined connection is ignored. With the owner and `metadata.installationId`, it is the deduplication key for `desktop` connections.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/integrations/connections/{connectionId}/console/capabilities

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/integrations/connections/{connectionId}/console/capabilities

Parameters

Path parameters

Name	Type	Required	Description
`connectionId`	string (uuid)	Yes	The connection whose resources the console addresses.

Query parameters

Name	Type	Required	Description
`resource`	string	Yes	The driver-specific resource type, e.g. `pod` for a kubernetes connection.
`name`	string	Yes	The resource’s name within its scope.
`namespace`	string	No	The resource’s parent scope, where it has one. Required for namespaced Kubernetes resources.
`container`	string	No	A sub-target within the resource, e.g. a container within a pod. The driver’s default sub-target is used when omitted.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

What a driver can do with one specific target. Resolved against live state rather than a static table, because whether a target admits a terminal generally depends on its current status.

Field	Type	Required	Description
`containers`	array of string	No	The addressable sub-targets, if the resource has any.
`defaultContainer`	string	No	The sub-target used when ConsoleTarget.container is empty.
`logs`	boolean	Yes	Whether a log stream can be opened.
`reason`	string	No	Explains, for a human, why an unsupported console kind is unsupported — e.g. that the pod is not running.
`terminal`	boolean	Yes	Whether an interactive terminal can be opened.

Schema: string

Console GET

/api/integrations/connections/{connectionId}/console/logs

Stream a resource's logs over a WebSocket

Upgrade to a WebSocket carrying the target resource’s log output. With follow=true the socket stays open until the client leaves; otherwise it closes once the available history has been sent. Consume with a native WebSocket client, not a generated RTK hook. The stream parameters below are fixed when the remote log stream is created and cannot be renegotiated on a live socket: changing any of them means opening a new console. See ConsoleControlMessage for the frame protocol.

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/integrations/connections/{connectionId}/console/logs

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/integrations/connections/{connectionId}/console/logs

Parameters

Path parameters

Name	Type	Required	Description
`connectionId`	string (uuid)	Yes	The connection whose resources the console addresses.

Query parameters

Name	Type	Required	Description
`resource`	string	Yes	The driver-specific resource type, e.g. `pod` for a kubernetes connection.
`name`	string	Yes	The resource’s name within its scope.
`namespace`	string	No	The resource’s parent scope, where it has one. Required for namespaced Kubernetes resources.
`container`	string	No	A sub-target within the resource, e.g. a container within a pod. The driver’s default sub-target is used when omitted.
`follow`	boolean	No	Keep the stream open and append new output as it is produced.
`previous`	boolean	No	Return the logs of the target’s prior instance, if any.
`timestamps`	boolean	No	Prefix each line with an RFC 3339 timestamp.
`tailLines`	integer (int64)	No	Cap how many lines of history are replayed before following. Omit for no limit.
`sinceSeconds`	integer (int64)	No	Bound history to output produced within the last N seconds. Omit for no bound; a value of 0 is treated as omitted.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Schema: string

Console GET

/api/integrations/connections/{connectionId}/console/terminal

Open an interactive terminal over a WebSocket

Upgrade to a WebSocket carrying an interactive, TTY-backed shell in the target resource. Consume with a native WebSocket client, not a generated RTK hook. Everything that can fail with a useful HTTP status — an unknown target, an unsupported console kind, an exhausted per-user console budget — is settled before the upgrade, so those failures arrive as ordinary HTTP responses rather than as a socket that opens and immediately closes. The handshake enforces a same-origin check: it is authenticated by an ambient session cookie, so accepting any Origin would let any page the user visits open a shell as them. The console runs with the requesting user’s own credential, so the target’s native authorization (Kubernetes RBAC, for a kubernetes connection) governs it unchanged. See ConsoleControlMessage for the frame protocol.

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/integrations/connections/{connectionId}/console/terminal

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/integrations/connections/{connectionId}/console/terminal

Parameters

Path parameters

Name	Type	Required	Description
`connectionId`	string (uuid)	Yes	The connection whose resources the console addresses.

Query parameters

Name	Type	Required	Description
`resource`	string	Yes	The driver-specific resource type, e.g. `pod` for a kubernetes connection.
`name`	string	Yes	The resource’s name within its scope.
`namespace`	string	No	The resource’s parent scope, where it has one. Required for namespaced Kubernetes resources.
`container`	string	No	A sub-target within the resource, e.g. a container within a pod. The driver’s default sub-target is used when omitted.
`command`	array of string	No	The argv to execute, one query parameter per element. When omitted the driver picks a sensible interactive shell for the target.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/integrations/connections/{connectionId}/controllers/config

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/integrations/connections/{connectionId}/controllers/config

Parameters

Path parameters

Name	Type	Required	Description
`connectionId`	string (uuid)	Yes	Kubernetes connection ID.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Layered view of the controllers configuration for a single Kubernetes connection. Exposes each precedence layer so clients can indicate, per field, whether the effective value is inherited from the server-wide default or overridden on the connection.

Field	Type	Required	Description
`override`	object	No	Deployment and runtime configuration for the Meshery controllers that manage a Kubernetes connection: Meshery Operator, MeshSync, and Meshery Broker. The same document shape is used at two layers. As a server-wide default it declares how Meshery Server deploys and configures the controllers for every managed cluster. As a per-connection override, stored in the connection’s metadata, it overrides the server-wide default for a single connection. Every configuration field is optional: an absent field inherits the value from the next layer (per-connection override, then server-wide default, then built-in default). The only required field is the server-stamped schemaVersion discriminator, which identifies the document revision for future migrations. Learn more at https://docs.meshery.io/concepts/architecture
`default`	object	No	Deployment and runtime configuration for the Meshery controllers that manage a Kubernetes connection: Meshery Operator, MeshSync, and Meshery Broker. The same document shape is used at two layers. As a server-wide default it declares how Meshery Server deploys and configures the controllers for every managed cluster. As a per-connection override, stored in the connection’s metadata, it overrides the server-wide default for a single connection. Every configuration field is optional: an absent field inherits the value from the next layer (per-connection override, then server-wide default, then built-in default). The only required field is the server-stamped schemaVersion discriminator, which identifies the document revision for future migrations. Learn more at https://docs.meshery.io/concepts/architecture
`effective`	object	Yes	Deployment and runtime configuration for the Meshery controllers that manage a Kubernetes connection: Meshery Operator, MeshSync, and Meshery Broker. The same document shape is used at two layers. As a server-wide default it declares how Meshery Server deploys and configures the controllers for every managed cluster. As a per-connection override, stored in the connection’s metadata, it overrides the server-wide default for a single connection. Every configuration field is optional: an absent field inherits the value from the next layer (per-connection override, then server-wide default, then built-in default). The only required field is the server-stamped schemaVersion discriminator, which identifies the document revision for future migrations. Learn more at https://docs.meshery.io/concepts/architecture

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/integrations/connections/{connectionId}/controllers/config

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/integrations/connections/{connectionId}/controllers/config

Parameters

Path parameters

Name	Type	Required	Description
`connectionId`	string (uuid)	Yes	Kubernetes connection ID.

Request body

application/json Required

Controllers configuration document. Absent fields inherit from the next precedence layer.

Client-settable controllers configuration document, used as the body of update requests at both layers (server-wide defaults and per-connection override). Identical to MesheryControllersConfig minus the server-stamped schemaVersion. Every field is optional: an absent field inherits from the next precedence layer, and an empty document clears the layer entirely.

Field	Type	Required	Description
`operator`	object	No	Configuration for the Meshery Operator on the managed cluster.
`meshsync`	object	No	Configuration for the MeshSync agent on the managed cluster.
`broker`	object	No	Configuration for the Meshery Broker (NATS) on the managed cluster.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Layered view of the controllers configuration for a single Kubernetes connection. Exposes each precedence layer so clients can indicate, per field, whether the effective value is inherited from the server-wide default or overridden on the connection.

Field	Type	Required	Description
`override`	object	No	Deployment and runtime configuration for the Meshery controllers that manage a Kubernetes connection: Meshery Operator, MeshSync, and Meshery Broker. The same document shape is used at two layers. As a server-wide default it declares how Meshery Server deploys and configures the controllers for every managed cluster. As a per-connection override, stored in the connection’s metadata, it overrides the server-wide default for a single connection. Every configuration field is optional: an absent field inherits the value from the next layer (per-connection override, then server-wide default, then built-in default). The only required field is the server-stamped schemaVersion discriminator, which identifies the document revision for future migrations. Learn more at https://docs.meshery.io/concepts/architecture
`default`	object	No	Deployment and runtime configuration for the Meshery controllers that manage a Kubernetes connection: Meshery Operator, MeshSync, and Meshery Broker. The same document shape is used at two layers. As a server-wide default it declares how Meshery Server deploys and configures the controllers for every managed cluster. As a per-connection override, stored in the connection’s metadata, it overrides the server-wide default for a single connection. Every configuration field is optional: an absent field inherits the value from the next layer (per-connection override, then server-wide default, then built-in default). The only required field is the server-stamped schemaVersion discriminator, which identifies the document revision for future migrations. Learn more at https://docs.meshery.io/concepts/architecture
`effective`	object	Yes	Deployment and runtime configuration for the Meshery controllers that manage a Kubernetes connection: Meshery Operator, MeshSync, and Meshery Broker. The same document shape is used at two layers. As a server-wide default it declares how Meshery Server deploys and configures the controllers for every managed cluster. As a per-connection override, stored in the connection’s metadata, it overrides the server-wide default for a single connection. Every configuration field is optional: an absent field inherits the value from the next layer (per-connection override, then server-wide default, then built-in default). The only required field is the server-stamped schemaVersion discriminator, which identifies the document revision for future migrations. Learn more at https://docs.meshery.io/concepts/architecture

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/integrations/credentials

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/integrations/credentials

Parameters

Query parameters

Name	Type	Required	Description
`page`	integer	No	Get responses by page
`pageSize`	integer	No	Number of responses to return per page. Canonical camelCase pagination parameter; prefer this over the deprecated all-lowercase `pagesize`.
`pagesize`	integer	No	Get responses by pagesize. Deprecated alias of pageSize.
`search`	string	No	Get responses that match search param value
`order`	string	No	Get ordered responses

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

A paginated list of credentials.

Field	Type	Required	Description
`credentials`	array of object	Yes	The credentials returned on the current page.
`totalCount`	integer	Yes	Total number of credentials across all pages.
`page`	integer	Yes	Current page number (zero-based).
`pageSize`	integer	Yes	Number of credentials per page.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/integrations/credentials

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/integrations/credentials

Request body

application/json Required

Payload for creating or updating a credential.

Field	Type	Required	Description
`id`	string (uuid)	No	Existing credential ID for updates; omit on create.
`name`	string	Yes	Human-readable name for the credential.
`userId`	string (uuid)	No	UUID of the user who owns this credential.
`orgOwner`	string (uuid)	No	UUID of the organization to designate as the owner of this credential. A caller may supply this field; the server authorizes it against the authenticated principal and rejects the request when that principal may not write for the named organization.
`type`	string	Yes	Credential type (e.g. token, basic, AWS).
`secret`	object	No	Key-value pairs containing the sensitive credential data.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Meshery Credentials store sensitive information such as API keys, tokens, and passwords used by connections to external systems.

Field	Type	Required	Description
`id`	string (uuid)	Yes	Unique identifier for the credential.
`name`	string	Yes	Human-readable name for the credential.
`userId`	string (uuid)	Yes	UUID of the user who owns this credential.
`orgOwner`	string (uuid)	No	UUID of the organization designated as the owner of this credential, for credentials that belong to a brand profile rather than to a person. Optional and independent of userId: userId continues to identify the user who created and owns the record, while orgOwner designates the organization the credential is for.
`type`	string	Yes	Credential type (e.g. token, basic, AWS).
`secret`	object	No	Key-value pairs containing the sensitive credential data.
`createdAt`	string (date-time)	Yes	Timestamp when the credential was created.
`updatedAt`	string (date-time)	Yes	Timestamp when the credential was last updated.
`deletedAt`	string (date-time)	No	Timestamp when the credential was soft-deleted.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/integrations/credentials

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/integrations/credentials

Request body

application/json Required

Payload for creating or updating a credential.

Field	Type	Required	Description
`id`	string (uuid)	No	Existing credential ID for updates; omit on create.
`name`	string	Yes	Human-readable name for the credential.
`userId`	string (uuid)	No	UUID of the user who owns this credential.
`orgOwner`	string (uuid)	No	UUID of the organization to designate as the owner of this credential. A caller may supply this field; the server authorizes it against the authenticated principal and rejects the request when that principal may not write for the named organization.
`type`	string	Yes	Credential type (e.g. token, basic, AWS).
`secret`	object	No	Key-value pairs containing the sensitive credential data.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Meshery Credentials store sensitive information such as API keys, tokens, and passwords used by connections to external systems.

Field	Type	Required	Description
`id`	string (uuid)	Yes	Unique identifier for the credential.
`name`	string	Yes	Human-readable name for the credential.
`userId`	string (uuid)	Yes	UUID of the user who owns this credential.
`orgOwner`	string (uuid)	No	UUID of the organization designated as the owner of this credential, for credentials that belong to a brand profile rather than to a person. Optional and independent of userId: userId continues to identify the user who created and owns the record, while orgOwner designates the organization the credential is for.
`type`	string	Yes	Credential type (e.g. token, basic, AWS).
`secret`	object	No	Key-value pairs containing the sensitive credential data.
`createdAt`	string (date-time)	Yes	Timestamp when the credential was created.
`updatedAt`	string (date-time)	Yes	Timestamp when the credential was last updated.
`deletedAt`	string (date-time)	No	Timestamp when the credential was soft-deleted.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/integrations/credentials

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/integrations/credentials

Parameters

Query parameters

Name	Type	Required	Description
`credentialId`	string (uuid)	Yes	Credential ID

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/integrations/credentials/{credentialId}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/integrations/credentials/{credentialId}

Parameters

Path parameters

Name	Type	Required	Description
`credentialId`	string (uuid)	Yes	Credential ID

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Meshery Credentials store sensitive information such as API keys, tokens, and passwords used by connections to external systems.

Field	Type	Required	Description
`id`	string (uuid)	Yes	Unique identifier for the credential.
`name`	string	Yes	Human-readable name for the credential.
`userId`	string (uuid)	Yes	UUID of the user who owns this credential.
`orgOwner`	string (uuid)	No	UUID of the organization designated as the owner of this credential, for credentials that belong to a brand profile rather than to a person. Optional and independent of userId: userId continues to identify the user who created and owns the record, while orgOwner designates the organization the credential is for.
`type`	string	Yes	Credential type (e.g. token, basic, AWS).
`secret`	object	No	Key-value pairs containing the sensitive credential data.
`createdAt`	string (date-time)	Yes	Timestamp when the credential was created.
`updatedAt`	string (date-time)	Yes	Timestamp when the credential was last updated.
`deletedAt`	string (date-time)	No	Timestamp when the credential was soft-deleted.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/pattern/import

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/pattern/import

Request body

application/json Required

Body for POST /api/pattern/import. Consumed by the server as application/json. Exactly one of two variants must be supplied: a File Import carrying base64-encoded bytes plus a file name, or a URL Import naming a remote location the server will fetch. Sending both variants at once, or neither, is rejected with 400.

File Import

Upload a design file from the local system. Both file and fileName are required; the server uses the file name to identify the file type (Kubernetes Manifest, Helm Chart, Docker Compose, or Meshery Design).

Field	Type	Required	Description
`file`	string (byte)	Yes	Base64-encoded file bytes. Supported formats: Kubernetes Manifests, Helm Charts, Docker Compose, and Meshery Designs. See Import Designs Documentation for details.
`fileName`	string	Yes	The name of the pattern file being imported. Include the extension (e.g. `design.yaml`), as the server uses it to identify the file type.
`name`	string	No	Provide a name for your design. This name will help you identify the design later. You can also change the name of your design after importing it.

URL Import

Import a design by URL. The server will fetch the resource and derive the file type from the response.

Field	Type	Required	Description
`name`	string	No	Provide a name for your design. This name will help you identify the design later. You can also change the name of your design after importing it.
`url`	string (uri)	Yes	A direct URL to a single file, for example: https://raw.github.com/your-design-file.yaml. Ensure the resource is in a supported format: Kubernetes Manifest, Helm Chart, Docker Compose, or Meshery Design. See Import Designs Documentation for details.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Designs persisted by the import, in the order they were saved. Always a single element on this path.

Field	Type	Required	Description
`catalogData`	object	No	Catalog metadata attached to the design when published.
`cloneCount`	integer	No	Server-aggregated count of times this design has been cloned from the catalog. Server-managed and ignored on writes.
`createdAt`	string (date-time)	No	Timestamp of design creation.
`deploymentCount`	integer	No	Server-aggregated count of deployments originated from this design. Server-managed and ignored on writes.
`designType`	string \| null	No	Discriminator identifying the source format of the design body, persisted in the meshery_patterns table’s `source_type` column (nullable; null for legacy rows imported before the column was introduced). For catalog listings the server may also project this field from the attached catalog metadata. Use this field to branch rendering between native Meshery designs and imported Helm charts, Kubernetes manifests, and Docker Compose files.
`downloadCount`	integer	No	Server-aggregated count of downloads of this design from the catalog. Server-managed and ignored on writes.
`id`	string (uuid)	No	Server-generated design ID.
`location`	object	No	Optional structured location metadata (branch, host, path, …). For a design bound to a GitHub source the keys are those of DesignSourceLocation, including commitSha.
`name`	string	No	Human-readable design name.
`organizationId`	string (uuid)	Yes	The organization the design belongs to. The server sets it from the session organization (`X-Current-Orgid`, or the caller’s selected organization) on create, including import. Never accepted from clients. A workspace this design is assigned to must belong to this same organization.
`patternFile`	string	No	Raw design body as it is persisted in the meshery_patterns table’s `pattern_file` column. The wire form is the YAML/JSON string the server stores verbatim; consumers that need the structured form transcode at the boundary by parsing the string into a PatternFile (see #/components/schemas/PatternFile) and marshalling it back when they write. Keeping the wire shape as a string mirrors the column’s actual representation and avoids forcing every consumer through the structured-vs- string union that the previous *PatternFile typing implied.
`shareCount`	integer	No	Server-aggregated count of share events for this design. Server-managed and ignored on writes.
`sourceContent`	string \| null (byte)	No	Raw bytes of the imported source artifact (Helm chart tarball, Kubernetes manifest, Docker Compose file, etc.) preserved in the meshery_patterns table’s `source_content` column for non-Meshery-Design imports. Empty / null for native Meshery designs. Server-managed: populated by the import and upload handlers and scrubbed to null on most read responses, so clients should treat this as opaque base64-encoded bytes when it does appear on the wire.
`updatedAt`	string (date-time)	No	Timestamp of last design modification.
`user`	object \| null	No	Owning user record, joined inline by the catalog list/get handlers when shaping responses. Server-projected from the users table via the design’s userId; not a column on the meshery_patterns table itself, so the generated Go field is tagged `db:"-"` to keep it out of ORM column scans.
`userId`	string (uuid)	No	Owning user ID.
`viewCount`	integer	No	Server-aggregated count of views on this design in the catalog. Present on list/catalog responses; server-managed and ignored on writes.
`visibility`	string	No	Visibility scope of the design — controls whether non-owners may read or list it. `private` is owner-only, `public` is readable by anyone in the org, and `published` is visible in the catalog.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/performance/profiles

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/performance/profiles

Parameters

Query parameters

Name	Type	Required	Description
`page`	integer	No	Get responses by page
`pagesize`	string	No	Get responses by pagesize
`search`	string	No	Get responses that match search param value
`order`	string	No	Get ordered responses

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Paginated list of performance profiles.

Field	Type	Required	Description
`page`	integer	Yes	Zero-based page index returned in this response.
`pageSize`	integer	Yes	Maximum number of items returned on each page.
`profiles`	array of object	Yes	Performance profiles in this page.
`totalCount`	integer	Yes	Total number of performance profiles across all pages.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/performance/profiles

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/performance/profiles

Request body

application/json Required

Body for creating or updating a performance profile.

Payload for creating or updating a performance profile. Includes only client-settable fields; server-generated fields (id on create, createdAt, updatedAt, lastRun, totalResults) are populated by the server.

Field	Type	Required	Description
`concurrentRequest`	integer	No	Number of concurrent requests issued by the load generator.
`contentType`	string	No	Content-Type header value applied to each load-test request body (e.g. “application/json”).
`duration`	string	Yes	Duration of the load test, expressed as a Go duration string (e.g. “30s”, “5m”, “1h”).
`endpoints`	array of string	Yes	Endpoints (URLs) targeted by the performance profile’s load test.
`id`	string (uuid)	No	Existing performance-profile ID for updates; omit on create.
`loadGenerators`	array of string	Yes	Load generators (e.g. fortio, wrk2, nighthawk) to drive the profile’s load test.
`metadata`	object	No	Free-form metadata associated with the performance profile.
`name`	string	Yes	Human-readable name of the performance profile.
`owner`	string (uuid)	No	Owner user ID. When omitted, the server infers it from the authenticated user.
`qps`	integer	No	Target queries-per-second rate for the load generator. Zero indicates the generator runs unthrottled.
`requestBody`	string	No	HTTP request body sent on each load-test request.
`requestCookies`	string	No	HTTP request cookies, serialized as JSON, sent on each load-test request.
`requestHeaders`	string	No	HTTP request headers, serialized as JSON, sent on each load-test request.
`schedule`	string \| null (uuid)	No	Optional schedule ID associating the profile with a recurring run.
`serviceMesh`	string	No	Service mesh under test for the profile (e.g. istio, linkerd, consul). Empty string when the profile is mesh-agnostic.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

A performance profile captures the configuration for a load test run by Meshery against one or more service-mesh endpoints. Profiles are owned by a user and can optionally be associated with a recurring schedule. Learn more at https://docs.meshery.io/tasks/performance-management

Field	Type	Required	Description
`id`	string (uuid)	Yes	Unique identifier for the performance profile.
`name`	string	Yes	Human-readable name of the performance profile.
`owner`	string (uuid)	Yes	User ID of the profile owner.
`schedule`	string \| null (uuid)	No	Optional schedule ID associated with this performance profile. Null when the profile is not bound to a recurring schedule.
`loadGenerators`	array of string	No	Load generators (e.g. fortio, wrk2, nighthawk) to drive the profile’s load test.
`endpoints`	array of string	No	Endpoints (URLs) targeted by the performance profile’s load test.
`serviceMesh`	string	No	Service mesh under test for the profile (e.g. istio, linkerd, consul). Empty string when the profile is mesh-agnostic.
`concurrentRequest`	integer	No	Number of concurrent requests issued by the load generator.
`qps`	integer	No	Target queries-per-second rate for the load generator. Zero indicates the generator runs unthrottled.
`duration`	string	No	Duration of the load test, expressed as a Go duration string (e.g. “30s”, “5m”, “1h”).
`requestHeaders`	string	No	HTTP request headers, serialized as JSON, sent on each load-test request. Empty string when no headers are configured.
`requestCookies`	string	No	HTTP request cookies, serialized as JSON, sent on each load-test request. Empty string when no cookies are configured.
`requestBody`	string	No	HTTP request body sent on each load-test request. Empty string when no body is configured.
`contentType`	string	No	Content-Type header value applied to each load-test request body (e.g. “application/json”). Empty string when no body is configured.
`metadata`	object	No	Free-form metadata associated with the performance profile.
`lastRun`	string \| null (date-time)	No	Server-computed timestamp of the most recent load-test run that used this profile. Null until the first run completes. Server-managed; clients must not set this on create/update.
`totalResults`	integer	No	Server-computed count of load-test results recorded for this profile. Server-managed; clients must not set this on create/update.
`createdAt`	string (date-time)	Yes	Timestamp when the performance profile was created.
`updatedAt`	string (date-time)	Yes	Timestamp when the performance profile was last updated.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/performance/profiles/{performanceProfileId}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/performance/profiles/{performanceProfileId}

Parameters

Path parameters

Name	Type	Required	Description
`performanceProfileId`	string (uuid)	Yes	Performance profile ID.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

A performance profile captures the configuration for a load test run by Meshery against one or more service-mesh endpoints. Profiles are owned by a user and can optionally be associated with a recurring schedule. Learn more at https://docs.meshery.io/tasks/performance-management

Field	Type	Required	Description
`id`	string (uuid)	Yes	Unique identifier for the performance profile.
`name`	string	Yes	Human-readable name of the performance profile.
`owner`	string (uuid)	Yes	User ID of the profile owner.
`schedule`	string \| null (uuid)	No	Optional schedule ID associated with this performance profile. Null when the profile is not bound to a recurring schedule.
`loadGenerators`	array of string	No	Load generators (e.g. fortio, wrk2, nighthawk) to drive the profile’s load test.
`endpoints`	array of string	No	Endpoints (URLs) targeted by the performance profile’s load test.
`serviceMesh`	string	No	Service mesh under test for the profile (e.g. istio, linkerd, consul). Empty string when the profile is mesh-agnostic.
`concurrentRequest`	integer	No	Number of concurrent requests issued by the load generator.
`qps`	integer	No	Target queries-per-second rate for the load generator. Zero indicates the generator runs unthrottled.
`duration`	string	No	Duration of the load test, expressed as a Go duration string (e.g. “30s”, “5m”, “1h”).
`requestHeaders`	string	No	HTTP request headers, serialized as JSON, sent on each load-test request. Empty string when no headers are configured.
`requestCookies`	string	No	HTTP request cookies, serialized as JSON, sent on each load-test request. Empty string when no cookies are configured.
`requestBody`	string	No	HTTP request body sent on each load-test request. Empty string when no body is configured.
`contentType`	string	No	Content-Type header value applied to each load-test request body (e.g. “application/json”). Empty string when no body is configured.
`metadata`	object	No	Free-form metadata associated with the performance profile.
`lastRun`	string \| null (date-time)	No	Server-computed timestamp of the most recent load-test run that used this profile. Null until the first run completes. Server-managed; clients must not set this on create/update.
`totalResults`	integer	No	Server-computed count of load-test results recorded for this profile. Server-managed; clients must not set this on create/update.
`createdAt`	string (date-time)	Yes	Timestamp when the performance profile was created.
`updatedAt`	string (date-time)	Yes	Timestamp when the performance profile was last updated.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/performance/profiles/{performanceProfileId}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/performance/profiles/{performanceProfileId}

Parameters

Path parameters

Name	Type	Required	Description
`performanceProfileId`	string (uuid)	Yes	Performance profile ID.

Request body

application/json Required

Body for creating or updating a performance profile.

Payload for creating or updating a performance profile. Includes only client-settable fields; server-generated fields (id on create, createdAt, updatedAt, lastRun, totalResults) are populated by the server.

Field	Type	Required	Description
`concurrentRequest`	integer	No	Number of concurrent requests issued by the load generator.
`contentType`	string	No	Content-Type header value applied to each load-test request body (e.g. “application/json”).
`duration`	string	Yes	Duration of the load test, expressed as a Go duration string (e.g. “30s”, “5m”, “1h”).
`endpoints`	array of string	Yes	Endpoints (URLs) targeted by the performance profile’s load test.
`id`	string (uuid)	No	Existing performance-profile ID for updates; omit on create.
`loadGenerators`	array of string	Yes	Load generators (e.g. fortio, wrk2, nighthawk) to drive the profile’s load test.
`metadata`	object	No	Free-form metadata associated with the performance profile.
`name`	string	Yes	Human-readable name of the performance profile.
`owner`	string (uuid)	No	Owner user ID. When omitted, the server infers it from the authenticated user.
`qps`	integer	No	Target queries-per-second rate for the load generator. Zero indicates the generator runs unthrottled.
`requestBody`	string	No	HTTP request body sent on each load-test request.
`requestCookies`	string	No	HTTP request cookies, serialized as JSON, sent on each load-test request.
`requestHeaders`	string	No	HTTP request headers, serialized as JSON, sent on each load-test request.
`schedule`	string \| null (uuid)	No	Optional schedule ID associating the profile with a recurring run.
`serviceMesh`	string	No	Service mesh under test for the profile (e.g. istio, linkerd, consul). Empty string when the profile is mesh-agnostic.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

A performance profile captures the configuration for a load test run by Meshery against one or more service-mesh endpoints. Profiles are owned by a user and can optionally be associated with a recurring schedule. Learn more at https://docs.meshery.io/tasks/performance-management

Field	Type	Required	Description
`id`	string (uuid)	Yes	Unique identifier for the performance profile.
`name`	string	Yes	Human-readable name of the performance profile.
`owner`	string (uuid)	Yes	User ID of the profile owner.
`schedule`	string \| null (uuid)	No	Optional schedule ID associated with this performance profile. Null when the profile is not bound to a recurring schedule.
`loadGenerators`	array of string	No	Load generators (e.g. fortio, wrk2, nighthawk) to drive the profile’s load test.
`endpoints`	array of string	No	Endpoints (URLs) targeted by the performance profile’s load test.
`serviceMesh`	string	No	Service mesh under test for the profile (e.g. istio, linkerd, consul). Empty string when the profile is mesh-agnostic.
`concurrentRequest`	integer	No	Number of concurrent requests issued by the load generator.
`qps`	integer	No	Target queries-per-second rate for the load generator. Zero indicates the generator runs unthrottled.
`duration`	string	No	Duration of the load test, expressed as a Go duration string (e.g. “30s”, “5m”, “1h”).
`requestHeaders`	string	No	HTTP request headers, serialized as JSON, sent on each load-test request. Empty string when no headers are configured.
`requestCookies`	string	No	HTTP request cookies, serialized as JSON, sent on each load-test request. Empty string when no cookies are configured.
`requestBody`	string	No	HTTP request body sent on each load-test request. Empty string when no body is configured.
`contentType`	string	No	Content-Type header value applied to each load-test request body (e.g. “application/json”). Empty string when no body is configured.
`metadata`	object	No	Free-form metadata associated with the performance profile.
`lastRun`	string \| null (date-time)	No	Server-computed timestamp of the most recent load-test run that used this profile. Null until the first run completes. Server-managed; clients must not set this on create/update.
`totalResults`	integer	No	Server-computed count of load-test results recorded for this profile. Server-managed; clients must not set this on create/update.
`createdAt`	string (date-time)	Yes	Timestamp when the performance profile was created.
`updatedAt`	string (date-time)	Yes	Timestamp when the performance profile was last updated.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/performance/profiles/{performanceProfileId}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/performance/profiles/{performanceProfileId}

Parameters

Path parameters

Name	Type	Required	Description
`performanceProfileId`	string (uuid)	Yes	Performance profile ID.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/performance/profiles/{performanceProfileId}/results

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/performance/profiles/{performanceProfileId}/results

Parameters

Path parameters

Name	Type	Required	Description
`performanceProfileId`	string (uuid)	Yes	Performance profile ID.

Query parameters

Name	Type	Required	Description
`page`	integer	No	Get responses by page
`pagesize`	string	No	Get responses by pagesize
`search`	string	No	Get responses that match search param value
`order`	string	No	Get ordered responses

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Paginated list of performance results.

Field	Type	Required	Description
`page`	integer	Yes	Zero-based page index returned in this response.
`pageSize`	integer	Yes	Maximum number of items returned on each page.
`results`	array of object	Yes	Performance results in this page.
`totalCount`	integer	Yes	Total number of performance results across all pages.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/performance/results

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/performance/results

Parameters

Query parameters

Name	Type	Required	Description
`page`	integer	No	Get responses by page
`pagesize`	string	No	Get responses by pagesize
`search`	string	No	Get responses that match search param value
`order`	string	No	Get ordered responses
`from`	string (date)	No	Start date for filtering results by test start time, in YYYY-MM-DD format.
`to`	string (date)	No	End date for filtering results by test start time, in YYYY-MM-DD format.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Paginated list of performance results.

Field	Type	Required	Description
`page`	integer	Yes	Zero-based page index returned in this response.
`pageSize`	integer	Yes	Maximum number of items returned on each page.
`results`	array of object	Yes	Performance results in this page.
`totalCount`	integer	Yes	Total number of performance results across all pages.

Schema: string

Authentication

No authentication required

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/registry/categories

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/registry/categories

Parameters

Query parameters

Name	Type	Required	Description
`page`	integer	No	Zero-indexed page number of the result set.
`pageSize`	string	No	Number of items per page, or `all` to return every item.
`search`	string	No	Filter results by a case-insensitive substring match on name.
`order`	string	No	Field to order the results by.
`sort`	string	No	Sort direction (`asc` or `desc`).

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

A page of registry categories.

Schema: object

Authentication

No authentication required

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/registry/categories/{category}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/registry/categories/{category}

Parameters

Path parameters

Name	Type	Required	Description
`category`	string	Yes	Name of the category.

Query parameters

Name	Type	Required	Description
`page`	integer	No	Zero-indexed page number of the result set.
`pageSize`	string	No	Number of items per page, or `all` to return every item.
`search`	string	No	When `true`, the category name is matched greedily (substring match).
`order`	string	No	Field to order the results by.
`sort`	string	No	Sort direction (`asc` or `desc`).

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

A page of registry categories.

Schema: object

Authentication

No authentication required

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/registry/categories/{category}/components

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/registry/categories/{category}/components

Parameters

Path parameters

Name	Type	Required	Description
`category`	string	Yes	Name of the category.

Query parameters

Name	Type	Required	Description
`page`	integer	No	Zero-indexed page number of the result set.
`pageSize`	string	No	Number of items per page, or `all` to return every item.
`search`	string	No	Filter results by a case-insensitive substring match on name.
`order`	string	No	Field to order the results by.
`sort`	string	No	Sort direction (`asc` or `desc`).
`version`	string	No	Filter by model version.
`apiVersion`	string	No	Filter components by their API version.
`trim`	string	No	When `true`, omits large schema payloads from the returned definitions.
`annotations`	string	No	Annotation filter: `true` returns only annotation entities, `false` excludes them, and `include` returns both.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

A page of registered components.

Schema: object

Authentication

No authentication required

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/registry/categories/{category}/components/{name}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/registry/categories/{category}/components/{name}

Parameters

Path parameters

Name	Type	Required	Description
`category`	string	Yes	Name of the category.
`name`	string	Yes	Kind of the component (e.g. `Deployment`).

Query parameters

Name	Type	Required	Description
`page`	integer	No	Zero-indexed page number of the result set.
`pageSize`	string	No	Number of items per page, or `all` to return every item.
`search`	string	No	Filter results by a case-insensitive substring match on name.
`order`	string	No	Field to order the results by.
`sort`	string	No	Sort direction (`asc` or `desc`).
`version`	string	No	Filter by model version.
`apiVersion`	string	No	Filter components by their API version.
`trim`	string	No	When `true`, omits large schema payloads from the returned definitions.
`annotations`	string	No	Annotation filter: `true` returns only annotation entities, `false` excludes them, and `include` returns both.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

A page of registered components.

Schema: object

Authentication

No authentication required

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/registry/categories/{category}/models

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/registry/categories/{category}/models

Parameters

Path parameters

Name	Type	Required	Description
`category`	string	Yes	Name of the category.

Query parameters

Name	Type	Required	Description
`page`	integer	No	Zero-indexed page number of the result set.
`pageSize`	string	No	Number of items per page, or `all` to return every item.
`search`	string	No	Filter results by a case-insensitive substring match on name.
`order`	string	No	Field to order the results by.
`sort`	string	No	Sort direction (`asc` or `desc`).
`version`	string	No	Filter by model version.
`annotations`	string	No	Annotation filter: `true` returns only annotation entities, `false` excludes them, and `include` returns both.
`components`	string	No	When `true`, embeds the model’s component definitions in the response.
`relationships`	string	No	When `true`, embeds the model’s relationship definitions in the response.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

A page of registered models.

Schema: object

Authentication

No authentication required

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/registry/categories/{category}/models/{model}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/registry/categories/{category}/models/{model}

Parameters

Path parameters

Name	Type	Required	Description
`category`	string	Yes	Name of the category.
`model`	string	Yes	Name of the model (for `DELETE /api/registry/models/{model}`, the model’s ID).

Query parameters

Name	Type	Required	Description
`page`	integer	No	Zero-indexed page number of the result set.
`pageSize`	string	No	Number of items per page, or `all` to return every item.
`search`	string	No	When `true`, the model name is matched greedily (substring match).
`order`	string	No	Field to order the results by.
`sort`	string	No	Sort direction (`asc` or `desc`).
`version`	string	No	Filter by model version.
`annotations`	string	No	Annotation filter: `true` returns only annotation entities, `false` excludes them, and `include` returns both.
`components`	string	No	When `true`, embeds the model’s component definitions in the response.
`relationships`	string	No	When `true`, embeds the model’s relationship definitions in the response.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

A page of registered models.

Schema: object

Authentication

No authentication required

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/registry/categories/{category}/models/{model}/components

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/registry/categories/{category}/models/{model}/components

Parameters

Path parameters

Name	Type	Required	Description
`category`	string	Yes	Name of the category.
`model`	string	Yes	Name of the model (for `DELETE /api/registry/models/{model}`, the model’s ID).

Query parameters

Name	Type	Required	Description
`page`	integer	No	Zero-indexed page number of the result set.
`pageSize`	string	No	Number of items per page, or `all` to return every item.
`search`	string	No	Filter results by a case-insensitive substring match on name.
`order`	string	No	Field to order the results by.
`sort`	string	No	Sort direction (`asc` or `desc`).
`version`	string	No	Filter by model version.
`apiVersion`	string	No	Filter components by their API version.
`trim`	string	No	When `true`, omits large schema payloads from the returned definitions.
`annotations`	string	No	Annotation filter: `true` returns only annotation entities, `false` excludes them, and `include` returns both.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

A page of registered components.

Schema: object

Authentication

No authentication required

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/registry/categories/{category}/models/{model}/components/{name}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/registry/categories/{category}/models/{model}/components/{name}

Parameters

Path parameters

Name	Type	Required	Description
`category`	string	Yes	Name of the category.
`model`	string	Yes	Name of the model (for `DELETE /api/registry/models/{model}`, the model’s ID).
`name`	string	Yes	Kind of the component (e.g. `Deployment`).

Query parameters

Name	Type	Required	Description
`page`	integer	No	Zero-indexed page number of the result set.
`pageSize`	string	No	Number of items per page, or `all` to return every item.
`search`	string	No	Filter results by a case-insensitive substring match on name.
`order`	string	No	Field to order the results by.
`sort`	string	No	Sort direction (`asc` or `desc`).
`version`	string	No	Filter by model version.
`apiVersion`	string	No	Filter components by their API version.
`trim`	string	No	When `true`, omits large schema payloads from the returned definitions.
`annotations`	string	No	Annotation filter: `true` returns only annotation entities, `false` excludes them, and `include` returns both.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

A page of registered components.

Schema: object

Authentication

No authentication required

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/registry/components

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/registry/components

Parameters

Query parameters

Name	Type	Required	Description
`page`	integer	No	Zero-indexed page number of the result set.
`pageSize`	string	No	Number of items per page, or `all` to return every item.
`search`	string	No	Filter results by a case-insensitive substring match on name.
`order`	string	No	Field to order the results by.
`sort`	string	No	Sort direction (`asc` or `desc`).
`version`	string	No	Filter by model version.
`apiVersion`	string	No	Filter components by their API version.
`trim`	string	No	When `true`, omits large schema payloads from the returned definitions.
`annotations`	string	No	Annotation filter: `true` returns only annotation entities, `false` excludes them, and `include` returns both.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

A page of registered components.

Schema: object

Authentication

No authentication required

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/registry/components

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/registry/components

Request body

application/json Required

Envelope with which a registrant submits an entity definition for registration into the capabilities registry.

Field	Type	Required	Description
`connection`	object	Yes	Connection identifying the registrant.
`entity`	string (byte)	Yes	Base64-encoded JSON definition of the entity being registered.
`entityType`	string	Yes	Type of the entity being registered (e.g. `component`, `relationship`).

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Authentication

No authentication required

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/registry/components/{name}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/registry/components/{name}

Parameters

Path parameters

Name	Type	Required	Description
`name`	string	Yes	Kind of the component (e.g. `Deployment`).

Query parameters

Name	Type	Required	Description
`page`	integer	No	Zero-indexed page number of the result set.
`pageSize`	string	No	Number of items per page, or `all` to return every item.
`search`	string	No	When `true`, the component name is matched greedily (substring match).
`order`	string	No	Field to order the results by.
`sort`	string	No	Sort direction (`asc` or `desc`).
`version`	string	No	Filter by model version.
`apiVersion`	string	No	Filter components by their API version.
`trim`	string	No	When `true`, omits large schema payloads from the returned definitions.
`annotations`	string	No	Annotation filter: `true` returns only annotation entities, `false` excludes them, and `include` returns both.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

A page of registered components.

Schema: object

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/registry/connections

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/registry/connections

Parameters

Query parameters

Name	Type	Required	Description
`page`	integer	No	Page number
`pageSize`	integer	No	Number of items per page
`search`	string	No	Search term
`order`	string	No	Sort order
`model`	string	No	Filter by the name of the model the connection definition belongs to
`kind`	array of string	No	Filter by connection kind (e.g., kubernetes, prometheus, grafana)

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Represents a page of connection definitions with meta information about the total count

Field	Type	Required	Description
`connectionDefinitions`	array of schema	Yes	List of connection definitions on this page
`totalCount`	integer	Yes	Total number of connection definitions on all pages
`page`	integer	Yes	Current page number
`pageSize`	integer	Yes	Number of elements per page

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/registry/connections

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/registry/connections

Request body

application/json Required

Payload for registering (creating) or updating a connection definition. Contains only client-settable fields; server-generated fields such as createdAt, updatedAt, and deletedAt are excluded.

Field	Type	Required	Description
`connectionSchema`	object	No	Schema for connections of this kind.
`credentialSchema`	object	No	Schema for the credential associated with connections of this kind.
`description`	string	No	Human-readable description of the connection definition and its purpose.
`id`	string (uuid)	No	Existing connection definition ID for updates; omit on create.
`kind`	string	Yes	Connection kind (e.g., kubernetes, prometheus, grafana)
`metadata`	object	No	Kind-specific connection metadata
`modelReference`	object	No	Reference to the registered model that owns this connection definition.
`name`	string	Yes	Connection definition name
`schemaVersion`	string	No	Specifies the version of the schema the definition conforms to.
`status`	string	Yes	Connection Status Value
`styles`	object	No	Visualization styles for the connection, including svgColor and svgWhite used for UI representation.
`subType`	string	Yes	Connection sub-type (cloud, identity, metrics, chat, git, orchestration)
`transitionMap`	object	No	Map describing the connection state machine. Each key is a current connection status and its value is the list of states the connection may transition to from that status.
`type`	string	Yes	Connection type (platform, telemetry, collaboration)
`url`	string (uri)	No	URL of the remote resource connections of this kind point to.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

A connection definition is an uninitialized connection, authored per-model (in a model’s connections/ folder) and registered into the registry alongside components and relationships. It conforms to the connection schema; the dynamic, kind-specific shape is carried in metadata. The model association scopes the definition to its owning model.

Schema: schema

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/registry/connections/{connectionDefinitionId}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/registry/connections/{connectionDefinitionId}

Parameters

Path parameters

Name	Type	Required	Description
`connectionDefinitionId`	string (uuid)	Yes	Connection definition ID

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

A connection definition is an uninitialized connection, authored per-model (in a model’s connections/ folder) and registered into the registry alongside components and relationships. It conforms to the connection schema; the dynamic, kind-specific shape is carried in metadata. The model association scopes the definition to its owning model.

Schema: schema

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/registry/connections/{connectionDefinitionId}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/registry/connections/{connectionDefinitionId}

Parameters

Path parameters

Name	Type	Required	Description
`connectionDefinitionId`	string (uuid)	Yes	Connection definition ID

Request body

application/json Required

Payload for registering (creating) or updating a connection definition. Contains only client-settable fields; server-generated fields such as createdAt, updatedAt, and deletedAt are excluded.

Field	Type	Required	Description
`connectionSchema`	object	No	Schema for connections of this kind.
`credentialSchema`	object	No	Schema for the credential associated with connections of this kind.
`description`	string	No	Human-readable description of the connection definition and its purpose.
`id`	string (uuid)	No	Existing connection definition ID for updates; omit on create.
`kind`	string	Yes	Connection kind (e.g., kubernetes, prometheus, grafana)
`metadata`	object	No	Kind-specific connection metadata
`modelReference`	object	No	Reference to the registered model that owns this connection definition.
`name`	string	Yes	Connection definition name
`schemaVersion`	string	No	Specifies the version of the schema the definition conforms to.
`status`	string	Yes	Connection Status Value
`styles`	object	No	Visualization styles for the connection, including svgColor and svgWhite used for UI representation.
`subType`	string	Yes	Connection sub-type (cloud, identity, metrics, chat, git, orchestration)
`transitionMap`	object	No	Map describing the connection state machine. Each key is a current connection status and its value is the list of states the connection may transition to from that status.
`type`	string	Yes	Connection type (platform, telemetry, collaboration)
`url`	string (uri)	No	URL of the remote resource connections of this kind point to.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

A connection definition is an uninitialized connection, authored per-model (in a model’s connections/ folder) and registered into the registry alongside components and relationships. It conforms to the connection schema; the dynamic, kind-specific shape is carried in metadata. The model association scopes the definition to its owning model.

Schema: schema

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/registry/connections/{connectionDefinitionId}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/registry/connections/{connectionDefinitionId}

Parameters

Path parameters

Name	Type	Required	Description
`connectionDefinitionId`	string (uuid)	Yes	Connection definition ID

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Schema: string

Authentication

No authentication required

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/registry/export

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/registry/export

Parameters

Query parameters

Name	Type	Required	Description
`id`	string	No	ID of the model to export.
`name`	string	No	Name of the model to export.
`version`	string	No	Version of the model to export.
`outputFormat`	string	No	Format of the definitions inside the exported artifact.
`fileType`	string	No	Type of artifact to produce.
`components`	boolean	No	Whether to include component definitions in the export.
`relationships`	boolean	No	Whether to include relationship definitions in the export.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Schema: string (binary)

Authentication

No authentication required

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/registry/generate

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/registry/generate

Request body

application/json Required

Request to generate components for a set of packages.

Field	Type	Required	Description
`data`	array of object	Yes	Packages for which to generate components.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Schema: array of object

Field	Type	Required	Description
`components`	array of object	No	The generated component definitions.
`errors`	array of string	No	Errors encountered while generating components for this package.
`name`	string	No	Name of the package the components were generated for.

Authentication

No authentication required

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/registry/models

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/registry/models

Parameters

Query parameters

Name	Type	Required	Description
`page`	integer	No	Zero-indexed page number of the result set.
`pageSize`	string	No	Number of items per page, or `all` to return every item.
`search`	string	No	Filter results by a case-insensitive substring match on name.
`order`	string	No	Field to order the results by.
`sort`	string	No	Sort direction (`asc` or `desc`).
`status`	string	No	Filter by model status (e.g. `registered`, `ignored`, `duplicate`).
`id`	string	No	Filter by model ID.
`registrant`	string	No	Filter by the registrant (host) that registered the model.
`version`	string	No	Filter by model version.
`annotations`	string	No	Annotation filter: `true` returns only annotation entities, `false` excludes them, and `include` returns both.
`components`	string	No	When `true`, embeds the model’s component definitions in the response.
`relationships`	string	No	When `true`, embeds the model’s relationship definitions in the response.
`trim`	string	No	When `true`, omits large schema payloads from the returned definitions.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

A page of registered models.

Schema: object

Authentication

No authentication required

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/registry/models/{model}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/registry/models/{model}

Parameters

Path parameters

Name	Type	Required	Description
`model`	string	Yes	Name of the model (for `DELETE /api/registry/models/{model}`, the model’s ID).

Query parameters

Name	Type	Required	Description
`page`	integer	No	Zero-indexed page number of the result set.
`pageSize`	string	No	Number of items per page, or `all` to return every item.
`search`	string	No	When `true`, the model name is matched greedily (substring match).
`order`	string	No	Field to order the results by.
`sort`	string	No	Sort direction (`asc` or `desc`).
`version`	string	No	Filter by model version.
`annotations`	string	No	Annotation filter: `true` returns only annotation entities, `false` excludes them, and `include` returns both.
`components`	string	No	When `true`, embeds the model’s component definitions in the response.
`relationships`	string	No	When `true`, embeds the model’s relationship definitions in the response.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

A page of registered models.

Schema: object

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/registry/models/{model}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/registry/models/{model}

Parameters

Path parameters

Name	Type	Required	Description
`model`	string	Yes	Name of the model (for `DELETE /api/registry/models/{model}`, the model’s ID).

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Schema: string

Authentication

No authentication required

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/registry/models/{model}/components

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/registry/models/{model}/components

Parameters

Path parameters

Name	Type	Required	Description
`model`	string	Yes	Name of the model (for `DELETE /api/registry/models/{model}`, the model’s ID).

Query parameters

Name	Type	Required	Description
`page`	integer	No	Zero-indexed page number of the result set.
`pageSize`	string	No	Number of items per page, or `all` to return every item.
`search`	string	No	Filter results by a case-insensitive substring match on name.
`order`	string	No	Field to order the results by.
`sort`	string	No	Sort direction (`asc` or `desc`).
`version`	string	No	Filter by model version.
`apiVersion`	string	No	Filter components by their API version.
`trim`	string	No	When `true`, omits large schema payloads from the returned definitions.
`annotations`	string	No	Annotation filter: `true` returns only annotation entities, `false` excludes them, and `include` returns both.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

A page of registered components.

Schema: object

Authentication

No authentication required

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/registry/models/{model}/components/{name}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/registry/models/{model}/components/{name}

Parameters

Path parameters

Name	Type	Required	Description
`model`	string	Yes	Name of the model (for `DELETE /api/registry/models/{model}`, the model’s ID).
`name`	string	Yes	Kind of the component (e.g. `Deployment`).

Query parameters

Name	Type	Required	Description
`page`	integer	No	Zero-indexed page number of the result set.
`pageSize`	string	No	Number of items per page, or `all` to return every item.
`search`	string	No	Filter results by a case-insensitive substring match on name.
`order`	string	No	Field to order the results by.
`sort`	string	No	Sort direction (`asc` or `desc`).
`version`	string	No	Filter by model version.
`apiVersion`	string	No	Filter components by their API version.
`trim`	string	No	When `true`, omits large schema payloads from the returned definitions.
`annotations`	string	No	Annotation filter: `true` returns only annotation entities, `false` excludes them, and `include` returns both.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

A page of registered components.

Schema: object

Authentication

No authentication required

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/registry/models/{model}/policies

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/registry/models/{model}/policies

Parameters

Path parameters

Name	Type	Required	Description
`model`	string	Yes	Name of the model (for `DELETE /api/registry/models/{model}`, the model’s ID).

Query parameters

Name	Type	Required	Description
`page`	integer	No	Zero-indexed page number of the result set.
`pageSize`	string	No	Number of items per page, or `all` to return every item.
`search`	string	No	Filter results by a case-insensitive substring match on name.
`order`	string	No	Field to order the results by.
`sort`	string	No	Sort direction (`asc` or `desc`).

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

A page of registered policies.

Schema: object

Authentication

No authentication required

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/registry/models/{model}/policies/{name}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/registry/models/{model}/policies/{name}

Parameters

Path parameters

Name	Type	Required	Description
`model`	string	Yes	Name of the model (for `DELETE /api/registry/models/{model}`, the model’s ID).
`name`	string	Yes	Name of the policy.

Query parameters

Name	Type	Required	Description
`page`	integer	No	Zero-indexed page number of the result set.
`pageSize`	string	No	Number of items per page, or `all` to return every item.
`search`	string	No	Filter results by a case-insensitive substring match on name.
`order`	string	No	Field to order the results by.
`sort`	string	No	Sort direction (`asc` or `desc`).

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

A page of registered policies.

Schema: object

Authentication

No authentication required

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/registry/models/{model}/relationships

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/registry/models/{model}/relationships

Parameters

Path parameters

Name	Type	Required	Description
`model`	string	Yes	Name of the model (for `DELETE /api/registry/models/{model}`, the model’s ID).

Query parameters

Name	Type	Required	Description
`page`	integer	No	Zero-indexed page number of the result set.
`pageSize`	string	No	Number of items per page, or `all` to return every item.
`search`	string	No	Filter results by a case-insensitive substring match on name.
`order`	string	No	Field to order the results by.
`sort`	string	No	Sort direction (`asc` or `desc`).
`version`	string	No	Filter by model version.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

A page of registered relationships.

Schema: object

Authentication

No authentication required

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/registry/models/{model}/relationships/{name}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/registry/models/{model}/relationships/{name}

Parameters

Path parameters

Name	Type	Required	Description
`model`	string	Yes	Name of the model (for `DELETE /api/registry/models/{model}`, the model’s ID).
`name`	string	Yes	Kind of the relationship (e.g. `hierarchical`, `edge`, `sibling`).

Query parameters

Name	Type	Required	Description
`page`	integer	No	Zero-indexed page number of the result set.
`pageSize`	string	No	Number of items per page, or `all` to return every item.
`search`	string	No	Filter results by a case-insensitive substring match on name.
`order`	string	No	Field to order the results by.
`sort`	string	No	Sort direction (`asc` or `desc`).
`version`	string	No	Filter by model version.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

A page of registered relationships.

Schema: object

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/registry/register

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/registry/register

Request body

application/json Required

Schema: object

Field	Type	Required	Description
`importBody`	one of File Import, URL Import, CSV Import, Model Create	Yes	No description provided.
`register`	boolean	Yes	The register of the importrequest.
`uploadType`	string	Yes	Choose the method you prefer to upload your model file. Select ‘File Import’ or ‘CSV Import’ if you have the file on your local system or ‘URL Import’ if you have the file hosted online.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Summary of an import into the capabilities registry.

Field	Type	Required	Description
`entityCount`	object	No	Counts of imported and failed entities by type.
`entityTypeSummary`	object	No	Per-type summaries of imported entities and failures.
`errMsg`	string	No	Aggregated, human-readable description of import failures, if any.
`modelName`	array of string	No	Names of the models processed by the import.

Schema: string

Authentication

No authentication required

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/registry/registrants

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/registry/registrants

Parameters

Query parameters

Name	Type	Required	Description
`page`	integer	No	Zero-indexed page number of the result set.
`pageSize`	string	No	Number of items per page, or `all` to return every item.
`search`	string	No	Filter results by a case-insensitive substring match on name.
`order`	string	No	Field to order the results by.
`sort`	string	No	Sort direction (`asc` or `desc`).

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

A page of registrants.

Schema: object

Authentication

No authentication required

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/registry/relationships

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/registry/relationships

Parameters

Query parameters

Name	Type	Required	Description
`page`	integer	No	Zero-indexed page number of the result set.
`pageSize`	string	No	Number of items per page, or `all` to return every item.
`search`	string	No	Filter results by a case-insensitive substring match on name.
`order`	string	No	Field to order the results by.
`sort`	string	No	Sort direction (`asc` or `desc`).
`version`	string	No	Filter by model version.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

A page of registered relationships.

Schema: object

Authentication

No authentication required

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/registry/relationships

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/registry/relationships

Request body

application/json Required

Envelope with which a registrant submits an entity definition for registration into the capabilities registry.

Field	Type	Required	Description
`connection`	object	Yes	Connection identifying the registrant.
`entity`	string (byte)	Yes	Base64-encoded JSON definition of the entity being registered.
`entityType`	string	Yes	Type of the entity being registered (e.g. `component`, `relationship`).

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Evaluation POST

/api/registry/relationships/evaluate

Evaluate relationships in a design

Performs relationship evaluation on a given design, applying policies and updating components and relationships as needed. This EvaluationResponse contract is engine-agnostic: it is produced either by this server operation or by an equivalent in-browser WebAssembly engine implementing the same contract. See docs/relationship-evaluation-engine-contract.md for the authoritative engine contract, the in-browser engine surface, and the registry-independent hydration boundary.

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/registry/relationships/evaluate

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/registry/relationships/evaluate

Request body

application/json Required

Schema: object

Field	Type	Required	Description
`design`	object	Yes	Designs are your primary tool for collaborative authorship of your infrastructure, workflow, and processes.
`options`	object	No	The options of the evaluationrequest.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Schema for the response of a relationship evaluation process in Meshery

Field	Type	Required	Description
`actions`	array of object	Yes	The actions of the evaluationresponse.
`design`	object	Yes	The final evaluated design, including all updated components and relationships. This can be either the complete updated design or only a diff of changes. The version of the design will be automatically incremented if any modifications are made during the evaluation process. This field provides a comprehensive view of the design state after all relationship evaluations and policy applications have been completed.
`evaluationHash`	string	No	Hash of the input parameters and configuration used for this evaluation. Useful for identifying duplicate evaluations or caching results.
`schemaVersion`	string	Yes	Specifies the version of the schema to which the evaluation response conforms.
`timestamp`	string (date-time)	No	ISO 8601 formatted timestamp of when the evaluation was completed.

Schema: string

Authentication

No authentication required

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/registry/validate

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/registry/validate

Request body

application/json Required

Batch of values to validate against their schemas.

Field	Type	Required	Description
`validationItems`	object	Yes	Items to validate, keyed by a caller-chosen identifier.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Validation verdicts keyed by the request item identifiers.

Field	Type	Required	Description
`result`	object	Yes	No description provided.

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/registry/{entityType}/status

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/registry/{entityType}/status

Parameters

Path parameters

Name	Type	Required	Description
`entityType`	string	Yes	Type of the registered entity whose status is being updated.

Request body

application/json Required

Request to update the lifecycle status of a registered entity.

Field	Type	Required	Description
`displayName`	string	No	Display name of the entity, used in the resulting status-change event.
`id`	string	No	ID of the registered entity whose status is being updated.
`status`	string	Yes	New status of the entity (e.g. `registered`, `ignored`).

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/system/controllers/broker/status

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/system/controllers/broker/status

Parameters

Query parameters

Name	Type	Required	Description
`connectionId`	string (uuid)	Yes	The kubernetes connection ID whose broker status is requested.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Detailed status of a named Meshery controller (MeshSync or Broker) for a kubernetes connection.

Field	Type	Required	Description
`connectionId`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`name`	string	Yes	Controller name (e.g. MeshSync, MesheryBroker).
`status`	string	Yes	Current controller status. May be composed, e.g. “Connected ”.
`version`	string	Yes	Deployed controller version, when known.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/system/controllers/config

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/system/controllers/config

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Deployment and runtime configuration for the Meshery controllers that manage a Kubernetes connection: Meshery Operator, MeshSync, and Meshery Broker. The same document shape is used at two layers. As a server-wide default it declares how Meshery Server deploys and configures the controllers for every managed cluster. As a per-connection override, stored in the connection’s metadata, it overrides the server-wide default for a single connection. Every configuration field is optional: an absent field inherits the value from the next layer (per-connection override, then server-wide default, then built-in default). The only required field is the server-stamped schemaVersion discriminator, which identifies the document revision for future migrations. Learn more at https://docs.meshery.io/concepts/architecture

Field	Type	Required	Description
`operator`	object	No	Configuration for the Meshery Operator on the managed cluster.
`meshsync`	object	No	Configuration for the MeshSync agent on the managed cluster.
`broker`	object	No	Configuration for the Meshery Broker (NATS) on the managed cluster.
`schemaVersion`	string	Yes	Specifies the version of the schema used for this configuration document.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/system/controllers/config

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/system/controllers/config

Request body

application/json Required

Controllers configuration document. Absent fields inherit from the next precedence layer.

Client-settable controllers configuration document, used as the body of update requests at both layers (server-wide defaults and per-connection override). Identical to MesheryControllersConfig minus the server-stamped schemaVersion. Every field is optional: an absent field inherits from the next precedence layer, and an empty document clears the layer entirely.

Field	Type	Required	Description
`operator`	object	No	Configuration for the Meshery Operator on the managed cluster.
`meshsync`	object	No	Configuration for the MeshSync agent on the managed cluster.
`broker`	object	No	Configuration for the Meshery Broker (NATS) on the managed cluster.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Deployment and runtime configuration for the Meshery controllers that manage a Kubernetes connection: Meshery Operator, MeshSync, and Meshery Broker. The same document shape is used at two layers. As a server-wide default it declares how Meshery Server deploys and configures the controllers for every managed cluster. As a per-connection override, stored in the connection’s metadata, it overrides the server-wide default for a single connection. Every configuration field is optional: an absent field inherits the value from the next layer (per-connection override, then server-wide default, then built-in default). The only required field is the server-stamped schemaVersion discriminator, which identifies the document revision for future migrations. Learn more at https://docs.meshery.io/concepts/architecture

Field	Type	Required	Description
`operator`	object	No	Configuration for the Meshery Operator on the managed cluster.
`meshsync`	object	No	Configuration for the MeshSync agent on the managed cluster.
`broker`	object	No	Configuration for the Meshery Broker (NATS) on the managed cluster.
`schemaVersion`	string	Yes	Specifies the version of the schema used for this configuration document.

Schema: string

System GET

/api/system/controllers/diagnostics

Get controller diagnostics and remediation for a connection

Returns human-actionable diagnostics for a kubernetes connection’s Meshery controllers (operator, MeshSync, broker), derived from their current status and Meshery’s live broker connection. Each diagnostic carries a severity, a summary, an explanation, and concrete remediation steps so the UI can render a “Diagnostics” section in the connection detail view. An empty diagnostics list (with healthy=true) means no problems were detected.

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/system/controllers/diagnostics

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/system/controllers/diagnostics

Parameters

Query parameters

Name	Type	Required	Description
`connectionId`	string (uuid)	Yes	The kubernetes connection ID whose diagnostics are requested.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Diagnostics for a kubernetes connection’s Meshery controllers, for rendering a “Diagnostics” section in the connection detail view.

Field	Type	Required	Description
`connectionId`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`diagnostics`	array of object	Yes	The diagnostics detected for this connection (possibly empty).
`healthy`	boolean	Yes	True when no warning/error diagnostics were detected (informational diagnostics do not affect health).

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/system/controllers/meshsync/status

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/system/controllers/meshsync/status

Parameters

Query parameters

Name	Type	Required	Description
`connectionId`	string (uuid)	Yes	The kubernetes connection ID whose MeshSync status is requested.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Detailed status of a named Meshery controller (MeshSync or Broker) for a kubernetes connection.

Field	Type	Required	Description
`connectionId`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`name`	string	Yes	Controller name (e.g. MeshSync, MesheryBroker).
`status`	string	Yes	Current controller status. May be composed, e.g. “Connected ”.
`version`	string	Yes	Deployed controller version, when known.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/system/controllers/operator/status

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/system/controllers/operator/status

Parameters

Query parameters

Name	Type	Required	Description
`connectionId`	string (uuid)	Yes	The kubernetes connection ID whose operator status is requested.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Status of a single Meshery controller (operator, MeshSync, or broker) for a kubernetes connection. Element type of the controller-status SSE stream and the operator status response.

Field	Type	Required	Description
`connectionId`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`controller`	string	Yes	The controller this status describes.
`status`	string	Yes	Current controller status.
`version`	string	Yes	Deployed controller version, when known.

Schema: string

System GET

Stream Meshery controller status over Server-Sent Events

Server-Sent Events (SSE) stream of controller status (operator, MeshSync, broker) for the requested kubernetes connections. Replaces the subscribeMesheryControllersStatus GraphQL subscription. The server emits the full status array as an unnamed SSE event (data: <json> followed by a blank line) on subscribe and again whenever any controller’s status changes; a comment keepalive is sent periodically. Consume with a native EventSource, not a buffered JSON client.

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/system/controllers/status/subscribe

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/system/controllers/status/subscribe

Query parameters

Name	Type	Required	Description
`connectionIds`	array of string (uuid)	No	Kubernetes connection IDs to watch. Repeatable (connectionIds=&connectionIds=).

Returned data

Status codes, content types, and response schemas returned by this endpoint.

SSE frames. Each data: line is a JSON array of ControllerStatus items.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/system/database

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/system/database

Parameters

Query parameters

Name	Type	Required	Description
`page`	integer	No	Zero-based page index for the table list.
`pageSize`	integer	No	Number of tables to include per page.
`search`	string	No	Substring filter applied to table names.
`sort`	string	No	Column to order the table list by.
`order`	string	No	Sort direction for the `sort` column.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Paginated summary of the Meshery server’s embedded database.

Field	Type	Required	Description
`page`	integer	Yes	Zero-based page index of the returned table slice.
`pageSize`	integer	Yes	Number of tables included in this page.
`recordCount`	integer	Yes	Aggregate row count across the tables returned in this page.
`tables`	array of object	Yes	Tables included in this page, with per-table row counts.
`totalTables`	integer	Yes	Total number of tables in the database matching the search filter.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/system/database/reset

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/system/database/reset

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Status message response.

Field	Type	Required	Description
`message`	string	Yes	Human-readable status message.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/system/kubernetes

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/system/kubernetes

Request body

multipart/form-data Required

Multipart form payload for importing a kubeconfig. contexts and selectedContexts are JSON-encoded strings because they travel as multipart form fields alongside the file.

Field	Type	Required	Description
`contexts`	string	No	JSON-encoded object mapping a discovered context ID to per-context import options, e.g. `{"<contextId>": {"meshsyncDeploymentMode": "operator", "name": "my-cluster"}}`. `meshsyncDeploymentMode` selects how MeshSync runs for the resulting connection; `name` overrides the connection name.
`k8sfile`	string (binary)	Yes	Kubeconfig file contents.
`selectedContexts`	string	No	JSON-encoded array of discovered context IDs to import. When absent, every context discovered in the kubeconfig is imported.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Discovered kubeconfig contexts bucketed by import outcome. Every bucket is always present (empty when no context landed in it).

Field	Type	Required	Description
`connectedContexts`	array of object	Yes	Contexts whose connection already exists in (or transitioned to) the connected state.
`erroredContexts`	array of object	Yes	Contexts that could not be saved as connections. The failure detail is recorded in the emitted event’s metadata, not on the context object.
`ignoredContexts`	array of object	Yes	Contexts whose connection is in the ignored state.
`registeredContexts`	array of object	Yes	Contexts newly registered as discovered connections.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/system/kubernetes/contexts

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/system/kubernetes/contexts

Request body

multipart/form-data Required

Multipart form payload for kubeconfig context discovery.

Field	Type	Required	Description
`k8sfile`	string (binary)	Yes	Kubeconfig file contents.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Schema: array of object

Field	Type	Required	Description
`auth`	object	No	Authentication material for the context (token or kubeconfig reference), sourced from the connection’s credential secret.
`cluster`	object	No	Cluster definition for the context (certificate authority and server details), sourced from the connection’s credential secret.
`connectionId`	string (uuid)	No	ID of the connection this context was projected from.
`createdAt`	string (date-time)	No	Timestamp when the underlying connection was created.
`createdBy`	string (uuid)	No	ID of the user who registered the context.
`deploymentType`	string	No	How Meshery is deployed relative to the cluster (e.g. in_cluster, out_of_cluster).
`id`	string	No	Stable identifier of the Kubernetes context, assigned when the context is registered. Not a UUID; carried in connection metadata.
`kubernetesServerId`	string (uuid)	No	ID of the Kubernetes server associated with the context.
`mesheryInstanceId`	string (uuid)	No	ID of the Meshery instance the context is registered with.
`name`	string	No	Human-readable name of the Kubernetes context.
`owner`	string (uuid)	No	ID of the user who owns the underlying connection.
`reachable`	boolean	No	Whether this context’s API server answered the probe run while its kubeconfig was processed. Discovery and import surface unreachable contexts too, so they can still be registered; reachability only gates the connected transition.
`server`	string	No	API server URL of the Kubernetes cluster.
`updatedAt`	string (date-time)	No	Timestamp when the underlying connection was last updated.
`version`	string	No	Kubernetes server version of the cluster.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/system/kubernetes/ping

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/system/kubernetes/ping

Parameters

Query parameters

Name	Type	Required	Description
`connectionId`	string (uuid)	Yes	ID of the Kubernetes connection whose cluster to ping.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Result of pinging a Kubernetes connection’s API server.

Field	Type	Required	Description
`server_version`	string	Yes	Version string reported by the cluster’s API server. The wire field is `server_version` - this endpoint’s published wire casing predates the camelCase convention and is preserved within this API version.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/system/sync

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/system/sync

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Session bootstrap payload for the authenticated user.

Field	Type	Required	Description
`k8sConfig`	array of object	No	Kubernetes contexts currently tracked by the Meshery server.

Schema: string

Authentication

No authentication required

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/system/version

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/system/version

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Version metadata for a running Meshery service.

Field	Type	Required	Description
`build`	string	No	Build identifier (typically the git tag of the running binary).
`commitsha`	string	No	Git commit SHA of the running service. The wire field is `commitsha`.
`latest`	string	No	Latest available Meshery release tag fetched from GitHub.
`outdated`	boolean	No	True when the running build is older than the latest available release.
`releaseChannel`	string	No	Release channel of the running binary (e.g. `stable`, `edge`).
`version`	string	No	Meshery Cloud deployment version.

Authentication

No authentication required

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/users

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/users

Parameters

Query parameters

Name	Type	Required	Description
`page`	integer	No	Get responses by page
`pageSize`	integer	No	Number of responses to return per page. Canonical camelCase pagination parameter; prefer this over the deprecated all-lowercase `pagesize`.
`search`	string	No	Get responses that match search param value
`order`	string	No	Get ordered responses
`filter`	string	No	Get filtered reponses

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Paginated list of publicly viewable user records

Field	Type	Required	Description
`data`	array of object	Yes	Public user records for the requested page.
`page`	integer	Yes	Current page number of the result set.
`pageSize`	integer	Yes	Number of items per page.
`totalCount`	integer	Yes	Total number of items available.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/workspaces

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/workspaces

Parameters

Query parameters

Name	Type	Required	Description
`orgId`	string (uuid)	No	Organization ID used to scope the workspace listing.
`search`	string	No	Get responses that match search param value
`order`	string	No	Get ordered responses
`page`	integer	No	Get responses by page
`pageSize`	integer	No	Number of responses to return per page. Canonical camelCase pagination parameter; prefer this over the deprecated all-lowercase `pagesize`.
`pagesize`	integer	No	Get responses by pagesize. Deprecated alias of pageSize.
`filter`	string	No	JSON-encoded filter string used for assignment and soft-delete filters.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Paginated list of workspaces.

Field	Type	Required	Description
`page`	integer	No	Zero-based page index returned in this response.
`pageSize`	integer	No	Maximum number of items returned on each page.
`totalCount`	integer	No	Total number of items across all pages.
`workspaces`	array of object	No	List of workspaces with resolved owner details.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/workspaces

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/workspaces

Request body

application/json Required

Body for creating a workspace

Payload for creating a workspace.

Field	Type	Required	Description
`description`	string	No	Description of the workspace.
`metadata`	object	No	Metadata associated with the workspace.
`name`	string	Yes	Name of the workspace.
`organizationId`	string (uuid)	Yes	Organization ID.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

A workspace is a logical grouping of resources within an organization. Workspaces provide a way to organize environments, designs, teams, and views. Learn more at https://docs.meshery.io/concepts/logical/workspaces

Field	Type	Required	Description
`createdAt`	string (date-time)	Yes	Timestamp when the workspace was created.
`deletedAt`	string (date-time)	No	Timestamp when the workspace was soft-deleted. Null while the workspace is active.
`description`	string	No	Description of the workspace.
`id`	string (uuid)	Yes	No description provided.
`metadata`	object	No	Metadata associated with the workspace.
`name`	string	Yes	Name of the workspace.
`organizationId`	string (uuid)	Yes	Organization to which this workspace belongs.
`owner`	string (uuid)	No	User ID of the workspace owner.
`updatedAt`	string (date-time)	Yes	Timestamp when the workspace was last updated.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/workspaces/{workspaceId}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/workspaces/{workspaceId}

Parameters

Path parameters

Name	Type	Required	Description
`workspaceId`	string (uuid)	Yes	Workspace ID

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

A workspace is a logical grouping of resources within an organization. Workspaces provide a way to organize environments, designs, teams, and views. Learn more at https://docs.meshery.io/concepts/logical/workspaces

Field	Type	Required	Description
`createdAt`	string (date-time)	Yes	Timestamp when the workspace was created.
`deletedAt`	string (date-time)	No	Timestamp when the workspace was soft-deleted. Null while the workspace is active.
`description`	string	No	Description of the workspace.
`id`	string (uuid)	Yes	No description provided.
`metadata`	object	No	Metadata associated with the workspace.
`name`	string	Yes	Name of the workspace.
`organizationId`	string (uuid)	Yes	Organization to which this workspace belongs.
`owner`	string (uuid)	No	User ID of the workspace owner.
`updatedAt`	string (date-time)	Yes	Timestamp when the workspace was last updated.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/workspaces/{workspaceId}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/workspaces/{workspaceId}

Parameters

Path parameters

Name	Type	Required	Description
`workspaceId`	string (uuid)	Yes	Workspace ID

Request body

application/json Required

Body for updating a workspace

Payload for updating a workspace.

Field	Type	Required	Description
`description`	string	No	Description of the workspace.
`metadata`	object	No	Metadata associated with the workspace.
`name`	string	No	Name of the workspace.
`organizationId`	string (uuid)	Yes	Organization ID.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

A workspace is a logical grouping of resources within an organization. Workspaces provide a way to organize environments, designs, teams, and views. Learn more at https://docs.meshery.io/concepts/logical/workspaces

Field	Type	Required	Description
`createdAt`	string (date-time)	Yes	Timestamp when the workspace was created.
`deletedAt`	string (date-time)	No	Timestamp when the workspace was soft-deleted. Null while the workspace is active.
`description`	string	No	Description of the workspace.
`id`	string (uuid)	Yes	No description provided.
`metadata`	object	No	Metadata associated with the workspace.
`name`	string	Yes	Name of the workspace.
`organizationId`	string (uuid)	Yes	Organization to which this workspace belongs.
`owner`	string (uuid)	No	User ID of the workspace owner.
`updatedAt`	string (date-time)	Yes	Timestamp when the workspace was last updated.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/workspaces/{workspaceId}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/workspaces/{workspaceId}

Parameters

Path parameters

Name	Type	Required	Description
`workspaceId`	string (uuid)	Yes	Workspace ID

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/workspaces/{workspaceId}/designs

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/workspaces/{workspaceId}/designs

Parameters

Path parameters

Name	Type	Required	Description
`workspaceId`	string (uuid)	Yes	Workspace ID

Query parameters

Name	Type	Required	Description
`search`	string	No	Get responses that match search param value
`order`	string	No	Get ordered responses
`page`	integer	No	Get responses by page
`pageSize`	integer	No	Number of responses to return per page. Canonical camelCase pagination parameter; prefer this over the deprecated all-lowercase `pagesize`.
`pagesize`	integer	No	Get responses by pagesize. Deprecated alias of pageSize.
`filter`	string	No	JSON-encoded filter string used for assignment and soft-delete filters.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Paginated list of designs.

Field	Type	Required	Description
`designs`	array of object	No	Designs in this page.
`page`	integer	No	Zero-based page index returned in this response.
`pageSize`	integer	No	Maximum number of items returned on each page.
`totalCount`	integer	No	Total number of items across all pages.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/workspaces/{workspaceId}/designs/{designId}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/workspaces/{workspaceId}/designs/{designId}

Parameters

Path parameters

Name	Type	Required	Description
`workspaceId`	string (uuid)	Yes	Workspace ID
`designId`	string (uuid)	Yes	Design ID

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Paginated list of workspace-design mappings.

Field	Type	Required	Description
`page`	integer	No	Zero-based page index returned in this response.
`pageSize`	integer	No	Maximum number of items returned on each page.
`totalCount`	integer	No	Total number of items across all pages.
`workspacesDesignsMapping`	array of object	No	Workspace-design mapping entries.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/workspaces/{workspaceId}/designs/{designId}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/workspaces/{workspaceId}/designs/{designId}

Parameters

Path parameters

Name	Type	Required	Description
`workspaceId`	string (uuid)	Yes	Workspace ID
`designId`	string (uuid)	Yes	Design ID

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/workspaces/{workspaceId}/environments

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/workspaces/{workspaceId}/environments

Parameters

Path parameters

Name	Type	Required	Description
`workspaceId`	string (uuid)	Yes	Workspace ID

Query parameters

Name	Type	Required	Description
`search`	string	No	Get responses that match search param value
`order`	string	No	Get ordered responses
`page`	integer	No	Get responses by page
`pageSize`	integer	No	Number of responses to return per page. Canonical camelCase pagination parameter; prefer this over the deprecated all-lowercase `pagesize`.
`pagesize`	integer	No	Get responses by pagesize. Deprecated alias of pageSize.
`filter`	string	No	JSON-encoded filter string used for assignment and soft-delete filters.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Paginated list of environments.

Field	Type	Required	Description
`environments`	array of object	No	Environments associated with this resource.
`page`	integer	No	Zero-based page index returned in this response.
`pageSize`	integer	No	Maximum number of items returned on each page.
`totalCount`	integer	No	Total number of items across all pages.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/workspaces/{workspaceId}/environments/{environmentId}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/workspaces/{workspaceId}/environments/{environmentId}

Parameters

Path parameters

Name	Type	Required	Description
`workspaceId`	string (uuid)	Yes	Workspace ID
`environmentId`	string (uuid)	Yes	Environment ID

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Paginated list of workspace-environment mappings.

Field	Type	Required	Description
`page`	integer	No	Zero-based page index returned in this response.
`pageSize`	integer	No	Maximum number of items returned on each page.
`totalCount`	integer	No	Total number of items across all pages.
`workspacesEnvironmentsMapping`	array of object	No	Workspace-environment mapping entries.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/workspaces/{workspaceId}/environments/{environmentId}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/workspaces/{workspaceId}/environments/{environmentId}

Parameters

Path parameters

Name	Type	Required	Description
`workspaceId`	string (uuid)	Yes	Workspace ID
`environmentId`	string (uuid)	Yes	Environment ID

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/workspaces/{workspaceId}/teams

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/workspaces/{workspaceId}/teams

Parameters

Path parameters

Name	Type	Required	Description
`workspaceId`	string (uuid)	Yes	Workspace ID

Query parameters

Name	Type	Required	Description
`search`	string	No	Get responses that match search param value
`order`	string	No	Get ordered responses
`page`	integer	No	Get responses by page
`pageSize`	integer	No	Number of responses to return per page. Canonical camelCase pagination parameter; prefer this over the deprecated all-lowercase `pagesize`.
`pagesize`	integer	No	Get responses by pagesize. Deprecated alias of pageSize.
`filter`	string	No	JSON-encoded filter string used for assignment and soft-delete filters.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Paginated list of teams

Field	Type	Required	Description
`page`	integer	No	Current page number of the result set.
`pageSize`	integer	No	Number of items per page.
`teams`	array of object	No	The teams of the teampage.
`totalCount`	integer	No	Total number of items available.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/workspaces/{workspaceId}/teams/{teamId}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/workspaces/{workspaceId}/teams/{teamId}

Parameters

Path parameters

Name	Type	Required	Description
`workspaceId`	string (uuid)	Yes	Workspace ID
`teamId`	string (uuid)	Yes	Team ID

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Paginated list of workspace-team mappings.

Field	Type	Required	Description
`page`	integer	No	Zero-based page index returned in this response.
`pageSize`	integer	No	Maximum number of items returned on each page.
`totalCount`	integer	No	Total number of items across all pages.
`workspacesTeamsMapping`	array of object	No	Workspace-team mapping entries.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/workspaces/{workspaceId}/teams/{teamId}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/workspaces/{workspaceId}/teams/{teamId}

Parameters

Path parameters

Name	Type	Required	Description
`workspaceId`	string (uuid)	Yes	Workspace ID
`teamId`	string (uuid)	Yes	Team ID

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/workspaces/{workspaceId}/views

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/workspaces/{workspaceId}/views

Parameters

Path parameters

Name	Type	Required	Description
`workspaceId`	string (uuid)	Yes	Workspace ID

Query parameters

Name	Type	Required	Description
`search`	string	No	Get responses that match search param value
`order`	string	No	Get ordered responses
`page`	integer	No	Get responses by page
`pageSize`	integer	No	Number of responses to return per page. Canonical camelCase pagination parameter; prefer this over the deprecated all-lowercase `pagesize`.
`pagesize`	integer	No	Get responses by pagesize. Deprecated alias of pageSize.
`filter`	string	No	JSON-encoded filter string used for assignment and soft-delete filters.

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Paginated list of views with location enrichment.

Field	Type	Required	Description
`page`	integer	No	No description provided.
`page_size`	integer	No	No description provided.
`total_count`	integer	No	No description provided.
`views`	array of object	No	Views in this page, enriched with workspace and organization context.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/workspaces/{workspaceId}/views/{viewId}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/workspaces/{workspaceId}/views/{viewId}

Parameters

Path parameters

Name	Type	Required	Description
`workspaceId`	string (uuid)	Yes	Workspace ID
`viewId`	string (uuid)	Yes	View ID

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Paginated list of workspace-view mappings.

Field	Type	Required	Description
`page`	integer	No	Zero-based page index returned in this response.
`pageSize`	integer	No	Maximum number of items returned on each page.
`totalCount`	integer	No	Total number of items across all pages.
`workspacesViewsMapping`	array of object	No	Workspace-view mapping entries.

Schema: string

Try this endpoint

Use your Meshery hostname or local server URL when calling this endpoint.

Meshery Playground server URL

https://playground.meshery.io/api/workspaces/{workspaceId}/views/{viewId}

Meshery Server URL (controlled via PORT environment variable)

http://localhost:9081/api/workspaces/{workspaceId}/views/{viewId}

Parameters

Path parameters

Name	Type	Required	Description
`workspaceId`	string (uuid)	Yes	Workspace ID
`viewId`	string (uuid)	Yes	View ID

Returned data

Responses

Status codes, content types, and response schemas returned by this endpoint.

Schema: string