API Reference

Ready to explore

Select an endpoint

Open a resource, choose a tag, and pick an endpoint to view its request and response details here.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/academy/admin/registrations

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/academy/admin/registrations

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/academy/admin/registrations

Parameters

Query parameters

Name	Type	Required	Description
`pageSize`	integer	No	Number of results per page
`pagesize`	integer	No	Number of results per page. Deprecated alias of pageSize.
`page`	integer	No	Page number
`contentType`	array of string	No	Filter by content types
`status`	array of string	No	Filter by registration status

Returned data

Responses

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

Field	Type	Required	Description
`data`	array of object	Yes	The data of the curricularegistrationsresponse.
`page`	integer	Yes	Current page number of the result set.
`pageSize`	integer	Yes	Number of items per page.
`totalCount`	integer (int64)	Yes	Total number of items available.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/academy/admin/summary

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/academy/admin/summary

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/academy/admin/summary

Returned data

Responses

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

Aggregate metrics for the instructor console, mirroring the deployed handler’s InstructorConsoleSummary struct.

Field	Type	Required	Description
`curricula`	array of object	No	Per-content-type registration counts.
`curriculaList`	object	No	Curricula with metrics for the organization.
`orgConfig`	object	No	Academy module configuration for the organization.
`registrationsSummary`	array of object	No	Per-status registration counts.
`tests`	array of object	No	Per-test outcome counts.
`testsSummary`	object	No	Aggregate test outcomes across the organization.
`totalActiveLearners`	integer	No	Learners with at least one active registration.
`totalLearners`	integer	No	Total distinct learners registered for the organization.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/academy/certificates/{certificateId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/academy/certificates/{certificateId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/academy/certificates/{certificateId}

Parameters

Path parameters

Name	Type	Required	Description
`certificateId`	string	Yes	The ID of the certificate to retrieve

Returned data

Responses

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

Field	Type	Required	Description
`description`	string	Yes	Description of the certificate
`expirationDate`	string (date-time)	No	Date when the certificate expires. Dynamically calculated from issued_date and expires_in; not specified by instructors.
`expiresIn`	integer	No	Number of months after which the certificate expires
`id`	string (uuid)	Yes	Unique identifier for the certificate
`issuedDate`	string (date-time)	Yes	Date when the certificate was issued
`issuingAuthorities`	array of object	Yes	List of issuing authorities for the certificate
`orgId`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`recipientId`	string (uuid)	Yes	ID of the recipient (user) who received the certificate
`recipientName`	string	Yes	Name of the recipient (user) who received the certificate
`title`	string	Yes	Title of the certificate

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/academy/curricula

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/academy/curricula

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/academy/curricula

Parameters

Query parameters

Name	Type	Required	Description
`contentType`	array of string	No	Filter content by content types
`visibility`	array of string	No	Filter content by visibility (public/private)
`level`	array of string	No	Filter content by difficulty level
`orgId`	array of string	No	Filter content by organization IDs
`category`	array of string	No	Filter content by categories
`status`	array of string	No	Filter by registration status
`search`	string	No	Search content by title
`sort`	string	No	Sort results by a specific field (e.g., title, createdAt)
`order`	string	No	Order of sorting (asc or desc)
`pageSize`	integer	No	Number of results per page
`pagesize`	integer	No	Number of results per page. Deprecated alias of pageSize.
`page`	integer	No	Page number

Returned data

Responses

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

Field	Type	Required	Description
`data`	array of object	Yes	The data of the academycurriculawithmetricslistresponse.
`total`	integer	Yes	Total number of Curricula

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/academy/curricula

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/academy/curricula

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/academy/curricula

Request body

application/json Required

Field	Type	Required	Description
`accessExpiresAt`	string	No	Expiry time for curricula access
`accessStatus`	string	Yes	Current access status of the curricula
`badgeId`	string (uuid)	No	ID of the badge to be awarded on completion of this curricula
`metadata`	object	Yes	Additional metadata about the Curricula
`orgId`	string	Yes	Organization ID that owns this learning path
`teamId`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`title`	string	Yes	Title of the curricula
`type`	string	Yes	Type of the curricula
`workspaceId`	string	Yes	ID of the workspace to which this Curricula belongs

Returned data

Responses

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

AcademyCurricula entity schema.

Field	Type	Required	Description
`badgeId`	string (uuid)	No	ID of the badge to be awarded on completion of this curricula
`createdAt`	string	Yes	When the Curricula item was created
`deletedAt`	string	Yes	No description provided.
`id`	string (uuid)	Yes	Id of the Curricula
`inviteId`	string	No	ID of the invite associated with this Curricula
`level`	string	Yes	Level of the Curricula
`metadata`	object	Yes	Additional metadata about the Curricula
`orgId`	string	Yes	Organization ID that owns this learning path
`slug`	string	Yes	slug of the Curricula
`status`	string	Yes	Status of the Curricula
`type`	string	Yes	No description provided.
`updatedAt`	string	Yes	When the Curricula was last updated
`visibility`	string	Yes	Visibility of the Curricula
`workspaceId`	string	No	ID of the workspace to which this Curricula belongs

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/academy/curricula/registered

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/academy/curricula/registered

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/academy/curricula/registered

Parameters

Query parameters

Name	Type	Required	Description
`contentType`	array of string	No	Filter content by content types
`orgId`	array of string	No	Filter content by organization IDs

Returned data

Responses

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

Field	Type	Required	Description
`data`	array of object	Yes	The data of the academycurriculalistresponse.
`total`	integer	Yes	Total number of Curricula

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/academy/curricula/registrations/{id}/withdraw

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/academy/curricula/registrations/{id}/withdraw

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/academy/curricula/registrations/{id}/withdraw

Parameters

Path parameters

Name	Type	Required	Description
`id`	string	Yes	The ID of the curricula

Returned data

Responses

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

Field	Type	Required	Description
`certificate`	object	Yes	Issued certificate for completing the curricula under registration
`contentId`	string (uuid)	Yes	ID of the course content
`createdAt`	string (date-time)	Yes	When the registration was created
`deletedAt`	string (date-time)	No	Timestamp when the resource was deleted.
`id`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`metadata`	object	Yes	Additional metadata about the registration
`orgId`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`status`	string	Yes	Status of the user’s course registration
`updatedAt`	string (date-time)	Yes	When the registration was updated
`userId`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/academy/curricula/{id}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/academy/curricula/{id}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/academy/curricula/{id}

Parameters

Path parameters

Name	Type	Required	Description
`id`	string	Yes	The ID of the curricula

Returned data

Responses

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

AcademyCurricula entity schema.

Field	Type	Required	Description
`badgeId`	string (uuid)	No	ID of the badge to be awarded on completion of this curricula
`createdAt`	string	Yes	When the Curricula item was created
`deletedAt`	string	Yes	No description provided.
`id`	string (uuid)	Yes	Id of the Curricula
`invitation`	object	No	Invitation entity schema.
`inviteId`	string	No	ID of the invite associated with this Curricula
`level`	string	Yes	Level of the Curricula
`metadata`	object	Yes	Additional metadata about the Curricula
`orgId`	string	Yes	Organization ID that owns this learning path
`registrationCount`	number	Yes	Number of registrations associated with this curriculum.
`slug`	string	Yes	slug of the Curricula
`status`	string	Yes	Status of the Curricula
`type`	string	Yes	No description provided.
`updatedAt`	string	Yes	When the Curricula was last updated
`visibility`	string	Yes	Visibility of the Curricula
`workspaceId`	string	No	ID of the workspace to which this Curricula belongs

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/academy/curricula/{id}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/academy/curricula/{id}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/academy/curricula/{id}

Parameters

Path parameters

Name	Type	Required	Description
`id`	string	Yes	The ID of the curricula

Request body

application/json Required

Field	Type	Required	Description
`accessExpiresAt`	string	No	Expiry time for curricula access
`accessStatus`	string	Yes	Current access status of the curricula
`badgeId`	string (uuid)	No	ID of the badge to be awarded on completion of this curricula
`metadata`	object	Yes	Additional metadata about the Curricula
`orgId`	string	Yes	Organization ID that owns this learning path
`teamId`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`title`	string	Yes	Title of the curricula
`type`	string	Yes	Type of the curricula
`workspaceId`	string	Yes	ID of the workspace to which this Curricula belongs

Returned data

Responses

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

AcademyCurricula entity schema.

Field	Type	Required	Description
`badgeId`	string (uuid)	No	ID of the badge to be awarded on completion of this curricula
`createdAt`	string	Yes	When the Curricula item was created
`deletedAt`	string	Yes	No description provided.
`id`	string (uuid)	Yes	Id of the Curricula
`invitation`	object	No	Invitation entity schema.
`inviteId`	string	No	ID of the invite associated with this Curricula
`level`	string	Yes	Level of the Curricula
`metadata`	object	Yes	Additional metadata about the Curricula
`orgId`	string	Yes	Organization ID that owns this learning path
`registrationCount`	number	Yes	Number of registrations associated with this curriculum.
`slug`	string	Yes	slug of the Curricula
`status`	string	Yes	Status of the Curricula
`type`	string	Yes	No description provided.
`updatedAt`	string	Yes	When the Curricula was last updated
`visibility`	string	Yes	Visibility of the Curricula
`workspaceId`	string	No	ID of the workspace to which this Curricula belongs

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/academy/curricula/{id}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/academy/curricula/{id}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/academy/curricula/{id}

Parameters

Path parameters

Name	Type	Required	Description
`id`	string	Yes	The ID of the curricula

Returned data

Responses

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

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/academy/register

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/academy/register

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/academy/register

Request body

application/json Required

Field	Type	Required	Description
`contentId`	string (uuid)	Yes	ID of the academy content to register for
`contentType`	string	No	No description provided.
`userId`	string (uuid)	Yes	ID of the user registering for the content.

Returned data

Responses

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

Field	Type	Required	Description
`certificate`	object	Yes	Issued certificate for completing the curricula under registration
`contentId`	string (uuid)	Yes	ID of the course content
`createdAt`	string (date-time)	Yes	When the registration was created
`deletedAt`	string (date-time)	No	Timestamp when the resource was deleted.
`id`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`metadata`	object	Yes	Additional metadata about the registration
`orgId`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`status`	string	Yes	Status of the user’s course registration
`updatedAt`	string (date-time)	Yes	When the registration was updated
`userId`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/academy/registrations/test-sessions/start

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/academy/registrations/test-sessions/start

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/academy/registrations/test-sessions/start

Request body

application/json Required

Field	Type	Required	Description
`registrationId`	string (uuid)	Yes	ID of the associated registration.
`testAbsPath`	string	Yes	The test abs path of the starttestrequest.

Returned data

Responses

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

Field	Type	Required	Description
`date`	string (date)	Yes	The date of the quiz.
`description`	string	Yes	Description of the quiz.
`draft`	boolean	Yes	The draft of the quiz.
`filePath`	string	Yes	The file path of the quiz.
`final`	boolean	Yes	Indicates if the quiz is final . i.e this quiz will used to evaluate the completion of parent section eg course , module , learning path
`id`	string	Yes	Quiz ID. Identifies a Hugo content page, not a database row, so it is an opaque content-scoped string. Not a UUID - stored records carry authored slugs.
`lastmod`	string (date)	Yes	The lastmod of the quiz.
`layout`	string	Yes	The layout of the quiz.
`maxAttempts`	integer	Yes	Maximum number of attempts allowed for the quiz. A value of 0 indicates unlimited attempts.
`nextPage`	object	Yes	No description provided.
`orgId`	string (uuid)	Yes	Organization ID that owns this quiz
`parent`	object	No	No description provided.
`passPercentage`	number (float)	Yes	The pass percentage of the quiz.
`permalink`	string	Yes	The permalink of the quiz.
`prerequisites`	array of object	Yes	The prerequisites of the quiz.
`questions`	array of object	Yes	The questions of the quiz.
`relPermalink`	string	Yes	The rel permalink of the quiz.
`section`	string	Yes	The section of the quiz.
`slug`	string	Yes	The slug of the quiz.
`timeLimit`	one of integer, string	Yes	Time limit for the quiz in minutes. A value of 0 indicates no time limit. Accepts a number or a string because both forms are real production data - the Hugo theme emits a JSON number, while payloads persisted by earlier revisions hold a string such as “25” or the non-numeric sentinel “infinite”. A string that does not parse to a positive number means “no time limit” and normalizes to 0.
`title`	string	Yes	The title of the quiz.
`totalMarks`	integer	Yes	The total marks of the quiz.
`totalQuestions`	integer	Yes	The total questions of the quiz.
`totalQuestionSets`	integer	Yes	The total question sets of the quiz.
`totalQuestionsInBank`	integer	Yes	The total questions in bank of the quiz.
`type`	string	Yes	Type of the resource.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/academy/registrations/test-sessions/submit

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/academy/registrations/test-sessions/submit

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/academy/registrations/test-sessions/submit

Request body

application/json Required

A learner’s answers to a quiz. Submitted as the submitQuiz request body and persisted verbatim as TestSubmission.submissionData. registrationId and userId are a convenience echo of the authoritative values on the enclosing TestSubmission (registrationId / userId, backed by the registration_id and owner uuid NOT NULL columns); read them from the enclosing submission, not from here.

Field	Type	Required	Description
`answers`	array of object	Yes	The answers of the quizsubmission.
`quizAbsPath`	string	Yes	The quiz abs path of the quizsubmission.
`registrationId`	string \| null (uuid)	No	ID of the associated registration. Optional, because a submission may not carry this echo; when it is absent the authoritative value is `TestSubmission.registrationId`. Absence MUST be expressed as `null` or an omitted property - the empty string is not a valid identifier.
`testSessionId`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`userId`	string \| null (uuid)	No	ID of the user who owns or created this resource. Optional, because a submission may not carry this echo; when it is absent the authoritative value is `TestSubmission.userId`. Absence MUST be expressed as `null` or an omitted property - the empty string is not a valid identifier.

Returned data

Responses

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

Field	Type	Required	Description
`attemptedAt`	string (date-time)	Yes	The attempted at of the quizevaluationresult.
`attempts`	integer	Yes	The attempts of the quizevaluationresult.
`correctSubmissions`	object	Yes	The correct submissions of the quizevaluationresult.
`passed`	boolean	Yes	The passed of the quizevaluationresult.
`passPercentage`	number (float)	Yes	The pass percentage of the quizevaluationresult.
`percentageScored`	number (float)	Yes	The percentage scored of the quizevaluationresult.
`quiz`	object	Yes	No description provided.
`score`	integer	Yes	The score of the quizevaluationresult.
`totalMarks`	integer	Yes	The total marks of the quizevaluationresult.

Field	Type	Required	Description
`details`	string	No	The details of the errorresponse.
`error`	string	No	The error of the errorresponse.

Field	Type	Required	Description
`details`	string	No	The details of the errorresponse.
`error`	string	No	The error of the errorresponse.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/academy/registrations/tests

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/academy/registrations/tests

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/academy/registrations/tests

Parameters

Query parameters

Name	Type	Required	Description
`absPath`	string	Yes	The absolute path of the test to retrieve

Returned data

Responses

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

Field	Type	Required	Description
`date`	string (date)	Yes	The date of the quiz.
`description`	string	Yes	Description of the quiz.
`draft`	boolean	Yes	The draft of the quiz.
`filePath`	string	Yes	The file path of the quiz.
`final`	boolean	Yes	Indicates if the quiz is final . i.e this quiz will used to evaluate the completion of parent section eg course , module , learning path
`id`	string	Yes	Quiz ID. Identifies a Hugo content page, not a database row, so it is an opaque content-scoped string. Not a UUID - stored records carry authored slugs.
`lastmod`	string (date)	Yes	The lastmod of the quiz.
`layout`	string	Yes	The layout of the quiz.
`maxAttempts`	integer	Yes	Maximum number of attempts allowed for the quiz. A value of 0 indicates unlimited attempts.
`nextPage`	object	Yes	No description provided.
`orgId`	string (uuid)	Yes	Organization ID that owns this quiz
`parent`	object	No	No description provided.
`passPercentage`	number (float)	Yes	The pass percentage of the quiz.
`permalink`	string	Yes	The permalink of the quiz.
`prerequisites`	array of object	Yes	The prerequisites of the quiz.
`questions`	array of object	Yes	The questions of the quiz.
`relPermalink`	string	Yes	The rel permalink of the quiz.
`section`	string	Yes	The section of the quiz.
`slug`	string	Yes	The slug of the quiz.
`timeLimit`	one of integer, string	Yes	Time limit for the quiz in minutes. A value of 0 indicates no time limit. Accepts a number or a string because both forms are real production data - the Hugo theme emits a JSON number, while payloads persisted by earlier revisions hold a string such as “25” or the non-numeric sentinel “infinite”. A string that does not parse to a positive number means “no time limit” and normalizes to 0.
`title`	string	Yes	The title of the quiz.
`totalMarks`	integer	Yes	The total marks of the quiz.
`totalQuestions`	integer	Yes	The total questions of the quiz.
`totalQuestionSets`	integer	Yes	The total question sets of the quiz.
`totalQuestionsInBank`	integer	Yes	The total questions in bank of the quiz.
`type`	string	Yes	Type of the resource.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/academy/registrations/{contentId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/academy/registrations/{contentId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/academy/registrations/{contentId}

Parameters

Path parameters

Name	Type	Required	Description
`contentId`	string	Yes	The ID of the content to retrieve registration data for

Query parameters

Name	Type	Required	Description
`status`	string	No	Filter registrations by status (e.g., registered, completed)

Returned data

Responses

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

Field	Type	Required	Description
`certificate`	object	Yes	Issued certificate for completing the curricula under registration
`contentId`	string (uuid)	Yes	ID of the course content
`createdAt`	string (date-time)	Yes	When the registration was created
`deletedAt`	string (date-time)	No	Timestamp when the resource was deleted.
`id`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`metadata`	object	Yes	Additional metadata about the registration
`orgId`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`status`	string	Yes	Status of the user’s course registration
`updatedAt`	string (date-time)	Yes	When the registration was updated
`userId`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/academy/registrations/{id}/test-sessions

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/academy/registrations/{id}/test-sessions

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/academy/registrations/{id}/test-sessions

Parameters

Path parameters

Name	Type	Required	Description
`id`	string	Yes	The ID of the registration to retrieve tests for

Query parameters

Name	Type	Required	Description
`page`	integer	No	Get responses by page
`pagesize`	integer	No	Get responses by pagesize
`testAbsPath`	string	No	Filter tests by absolute path

Returned data

Responses

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

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/academy/registrations/{registrationId}/progress-tracker/update-current-item

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/academy/registrations/{registrationId}/progress-tracker/update-current-item

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/academy/registrations/{registrationId}/progress-tracker/update-current-item

Parameters

Path parameters

Name	Type	Required	Description
`registrationId`	string	Yes	The ID of the registration

Request body

application/json Required

Field	Type	Required	Description
`contentType`	string	Yes	No description provided.
`itemData`	object	Yes	No description provided.

Returned data

Responses

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

Field	Type	Required	Description
`contentType`	string	No	No description provided.
`itemData`	object	No	No description provided.
`message`	string	No	The message of the updatecurrentitemprogressresponse.
`progressTracker`	object	No	No description provided.
`registrationId`	string (uuid)	No	ID of the associated registration.

Field	Type	Required	Description
`details`	string	No	The details of the errorresponse.
`error`	string	No	The error of the errorresponse.

Field	Type	Required	Description
`details`	string	No	The details of the errorresponse.
`error`	string	No	The error of the errorresponse.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/academy/{type}/{orgId}/{slug}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/academy/{type}/{orgId}/{slug}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/academy/{type}/{orgId}/{slug}

Parameters

Path parameters

Name	Type	Required	Description
`type`	string	Yes	No description provided.
`orgId`	string	Yes	No description provided.
`slug`	string	Yes	No description provided.

Returned data

Responses

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

AcademyCurricula entity schema.

Field	Type	Required	Description
`badgeId`	string (uuid)	No	ID of the badge to be awarded on completion of this curricula
`createdAt`	string	Yes	When the Curricula item was created
`deletedAt`	string	Yes	No description provided.
`id`	string (uuid)	Yes	Id of the Curricula
`inviteId`	string	No	ID of the invite associated with this Curricula
`level`	string	Yes	Level of the Curricula
`metadata`	object	Yes	Additional metadata about the Curricula
`orgId`	string	Yes	Organization ID that owns this learning path
`slug`	string	Yes	slug of the Curricula
`status`	string	Yes	Status of the Curricula
`type`	string	Yes	No description provided.
`updatedAt`	string	Yes	When the Curricula was last updated
`visibility`	string	Yes	Visibility of the Curricula
`workspaceId`	string	No	ID of the workspace to which this Curricula belongs

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/auth/keychains

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/auth/keychains

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/auth/keychains

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 keychains.

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.
`keychains`	array of object	Yes	Keychains returned on the current page.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/auth/keychains

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/auth/keychains

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/auth/keychains

Request body

application/json Required

Payload for creating or updating a keychain.

Field	Type	Required	Description
`name`	string	Yes	Name of the keychain.
`owner`	string (uuid)	No	Owner of the keychain.

Returned data

Responses

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

Represents a collection of keys.

Field	Type	Required	Description
`id`	string (uuid)	Yes	Unique identifier for the keychain.
`name`	string	Yes	Name of the keychain.
`owner`	string (uuid)	Yes	Owner of the keychain.
`createdAt`	string (date-time)	Yes	Timestamp when the keychain was created.
`updatedAt`	string (date-time)	Yes	Timestamp when the keychain was last updated.
`deletedAt`	string \| null (date-time)	No	Timestamp when the keychain was soft-deleted.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/auth/keychains/{keychainId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/auth/keychains/{keychainId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/auth/keychains/{keychainId}

Parameters

Path parameters

Name	Type	Required	Description
`keychainId`	string (uuid)	Yes	Keychain ID

Returned data

Responses

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

Represents a collection of keys.

Field	Type	Required	Description
`id`	string (uuid)	Yes	Unique identifier for the keychain.
`name`	string	Yes	Name of the keychain.
`owner`	string (uuid)	Yes	Owner of the keychain.
`createdAt`	string (date-time)	Yes	Timestamp when the keychain was created.
`updatedAt`	string (date-time)	Yes	Timestamp when the keychain was last updated.
`deletedAt`	string \| null (date-time)	No	Timestamp when the keychain was soft-deleted.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/auth/keychains/{keychainId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/auth/keychains/{keychainId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/auth/keychains/{keychainId}

Parameters

Path parameters

Name	Type	Required	Description
`keychainId`	string (uuid)	Yes	Keychain ID

Request body

application/json Required

Payload for creating or updating a keychain.

Field	Type	Required	Description
`name`	string	Yes	Name of the keychain.
`owner`	string (uuid)	No	Owner of the keychain.

Returned data

Responses

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

Represents a collection of keys.

Field	Type	Required	Description
`id`	string (uuid)	Yes	Unique identifier for the keychain.
`name`	string	Yes	Name of the keychain.
`owner`	string (uuid)	Yes	Owner of the keychain.
`createdAt`	string (date-time)	Yes	Timestamp when the keychain was created.
`updatedAt`	string (date-time)	Yes	Timestamp when the keychain was last updated.
`deletedAt`	string \| null (date-time)	No	Timestamp when the keychain was soft-deleted.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/auth/keychains/{keychainId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/auth/keychains/{keychainId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/auth/keychains/{keychainId}

Parameters

Path parameters

Name	Type	Required	Description
`keychainId`	string (uuid)	Yes	Keychain ID

Returned data

Responses

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

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/auth/keychains/{keychainId}/keys

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/auth/keychains/{keychainId}/keys

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/auth/keychains/{keychainId}/keys

Parameters

Path parameters

Name	Type	Required	Description
`keychainId`	string (uuid)	Yes	Keychain 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.
`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 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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/auth/keychains/{keychainId}/{keyId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/auth/keychains/{keychainId}/{keyId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/auth/keychains/{keychainId}/{keyId}

Parameters

Path parameters

Name	Type	Required	Description
`keychainId`	string (uuid)	Yes	Keychain ID
`keyId`	string (uuid)	Yes	Key ID

Returned data

Responses

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

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/auth/keychains/{keychainId}/{keyId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/auth/keychains/{keychainId}/{keyId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/auth/keychains/{keychainId}/{keyId}

Parameters

Path parameters

Name	Type	Required	Description
`keychainId`	string (uuid)	Yes	Keychain ID
`keyId`	string (uuid)	Yes	Key ID

Returned data

Responses

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

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/auth/keys

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/auth/keys

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/auth/keys

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 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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/auth/keys

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/auth/keys

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/auth/keys

Request body

application/json Required

Payload for creating or updating a key.

Field	Type	Required	Description
`id`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`function`	string	No	Operation permitted by the key.
`category`	string	No	Category for the key.
`subcategory`	string	No	Subcategory for the key.
`description`	string	No	Human readable description of the key.

Returned data

Responses

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

Represents an authorization key used for access control.

Field	Type	Required	Description
`id`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`owner`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`function`	string	Yes	Operation permitted by the key.
`category`	string	Yes	Category for the key.
`subcategory`	string	Yes	Subcategory for the key.
`description`	string	Yes	Human readable description of the key.
`createdAt`	string (date-time)	Yes	Timestamp when the key was created.
`updatedAt`	string (date-time)	Yes	Timestamp when the key was last updated.
`deletedAt`	string \| null (date-time)	No	Timestamp when the key was soft-deleted.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/auth/keys/{keyId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/auth/keys/{keyId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/auth/keys/{keyId}

Parameters

Path parameters

Name	Type	Required	Description
`keyId`	string (uuid)	Yes	Key ID

Returned data

Responses

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

Represents an authorization key used for access control.

Field	Type	Required	Description
`id`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`owner`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`function`	string	Yes	Operation permitted by the key.
`category`	string	Yes	Category for the key.
`subcategory`	string	Yes	Subcategory for the key.
`description`	string	Yes	Human readable description of the key.
`createdAt`	string (date-time)	Yes	Timestamp when the key was created.
`updatedAt`	string (date-time)	Yes	Timestamp when the key was last updated.
`deletedAt`	string \| null (date-time)	No	Timestamp when the key was soft-deleted.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/auth/keys/{keyId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/auth/keys/{keyId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/auth/keys/{keyId}

Parameters

Path parameters

Name	Type	Required	Description
`keyId`	string (uuid)	Yes	Key ID

Returned data

Responses

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

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/blowhorn/health

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/blowhorn/health

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/blowhorn/health

Returned data

Responses

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

Blowhorn contract version and organization binding status.

Field	Type	Required	Description
`bound`	boolean	Yes	Whether the organization is bound for Blowhorn operations.
`checkedAt`	string (date-time)	No	Time the binding was checked.
`contractVersion`	string	Yes	Frozen Blowhorn contract version the server speaks.
`organizationId`	string (uuid)	No	Organization whose binding was checked.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/catalog/content/classes

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/catalog/content/classes

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/catalog/content/classes

Parameters

Query parameters

Name	Type	Required	Description
`page`	integer	No	Get responses by page
`pageSize`	integer	No	Number of items per page (canonical camelCase form).

Returned data

Responses

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

Field	Type	Required	Description
`class`	string	No	The class of the catalogcontentclass.
`description`	string	No	Description of the catalogcontentclass.

Authentication

No authentication required

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/catalog/content/{type}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/catalog/content/{type}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/catalog/content/{type}

Parameters

Path parameters

Name	Type	Required	Description
`type`	string	Yes	No description provided.

Query parameters

Name	Type	Required	Description
`page`	integer	No	Get responses by page
`pageSize`	integer	No	Number of items per page (canonical camelCase form).
`search`	string	No	Get responses that match search param value
`order`	string	No	Get ordered responses
`type`	string	No	No description provided.
`technology`	string	No	No description provided.
`metrics`	boolean	No	No description provided.
`class`	string	No	No description provided.
`userId`	string	No	No description provided.
`orgId`	string	No	No description provided.
`workspaceId`	string	No	No description provided.
`teamId`	string	No	No description provided.
`populate`	boolean	No	No description provided.

Returned data

Responses

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

Paginated catalog content listing (designs, filters, aggregate counts).

Field	Type	Required	Description
`categoryCount`	array of object	No	Category-by-count aggregates for the catalog page.
`filters`	array of object	No	Published filters included on this page.
`modelsCount`	array of object	No	Model-by-count aggregates for the catalog page.
`page`	integer	No	Current page number of the result set.
`pageSize`	integer	No	Number of items per page.
`patterns`	array of object	No	Published designs included on this page.
`totalCount`	integer	No	Total number of items available.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/catalog/content/{type}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/catalog/content/{type}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/catalog/content/{type}

Parameters

Path parameters

Name	Type	Required	Description
`type`	string	Yes	No description provided.

Request body

application/json Required

Schema: object

Returned data

Responses

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

Server-returned catalog publish request as persisted by meshery-cloud (catalog_requests table). Records a user’s request to publish a design or filter to the catalog, along with the reviewer-visible requester identity and the request’s approval status.

Field	Type	Required	Description
`contentClass`	string \| null	No	Support-level classification of the content, stored in the `content_class` column (a Postgres enum). Nullable — legacy requests predate the column.
`contentId`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`contentName`	string	Yes	Human-readable name of the content at request time.
`contentType`	string	Yes	Kind of catalog content the request refers to.
`createdAt`	string (date-time)	Yes	Timestamp of request creation.
`email`	string (email)	Yes	Requesting user’s email address at request time.
`firstName`	string	Yes	Requesting user’s first name at request time.
`id`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`lastName`	string	Yes	Requesting user’s last name at request time.
`status`	string	Yes	Approval status of the request.
`updatedAt`	string (date-time)	Yes	Timestamp of last request modification (approval or denial).
`user`	object \| null	No	Requesting user record, joined inline by the catalog-request list handler when shaping responses. Server-projected from the users table; not a column on the catalog_requests table itself, so the generated Go field is tagged `db:"-"` to keep it out of ORM column scans.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/catalog/content/{type}/unpublish

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/catalog/content/{type}/unpublish

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/catalog/content/{type}/unpublish

Parameters

Path parameters

Name	Type	Required	Description
`type`	string	Yes	No description provided.

Request body

application/json Required

Schema: object

Returned data

Responses

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

Server-returned catalog publish request as persisted by meshery-cloud (catalog_requests table). Records a user’s request to publish a design or filter to the catalog, along with the reviewer-visible requester identity and the request’s approval status.

Field	Type	Required	Description
`contentClass`	string \| null	No	Support-level classification of the content, stored in the `content_class` column (a Postgres enum). Nullable — legacy requests predate the column.
`contentId`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`contentName`	string	Yes	Human-readable name of the content at request time.
`contentType`	string	Yes	Kind of catalog content the request refers to.
`createdAt`	string (date-time)	Yes	Timestamp of request creation.
`email`	string (email)	Yes	Requesting user’s email address at request time.
`firstName`	string	Yes	Requesting user’s first name at request time.
`id`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`lastName`	string	Yes	Requesting user’s last name at request time.
`status`	string	Yes	Approval status of the request.
`updatedAt`	string (date-time)	Yes	Timestamp of last request modification (approval or denial).
`user`	object \| null	No	Requesting user record, joined inline by the catalog-request list handler when shaping responses. Server-projected from the users table; not a column on the catalog_requests table itself, so the generated Go field is tagged `db:"-"` to keep it out of ORM column scans.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/catalog/requests

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/catalog/requests

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/catalog/requests

Parameters

Query parameters

Name	Type	Required	Description
`page`	integer	No	Get responses by page
`pageSize`	integer	No	Number of items per page (canonical camelCase form).
`search`	string	No	Get responses that match search param value
`order`	string	No	Get ordered responses
`filter`	string	No	No description provided.

Returned data

Responses

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

Paginated catalog-request listing (pending publish approvals).

Field	Type	Required	Description
`catalogRequests`	array of object	No	Catalog requests included on this page.
`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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/catalog/requests/approve

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/catalog/requests/approve

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/catalog/requests/approve

Request body

application/json Required

Schema: object

Returned data

Responses

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

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/catalog/requests/deny

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/catalog/requests/deny

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/catalog/requests/deny

Request body

application/json Required

Schema: object

Returned data

Responses

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

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/claims

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/claims

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/claims

Parameters

Query parameters

Name	Type	Required	Description
`page`	integer	No	Get responses by page
`pageSize`	integer	No	Number of items per page.
`order`	string	No	Get ordered responses
`resourceType`	string	No	Filter by claimed resource type.
`resourceId`	string (uuid)	No	Filter by claimed resource ID.
`claimantConnectionId`	string (uuid)	No	Filter by the connection that holds or held the claim.
`claimantUserId`	string (uuid)	No	Filter by the user whose session took the claim.
`status`	string	No	Filter by claim status, as read (a claim past `expiresAt` is `expired`).
`outcome`	string	No	Filter by the outcome reported on release.
`claimedSince`	string (date-time)	No	Only claims taken at or after this time.
`claimedUntil`	string (date-time)	No	Only claims taken before this time.

Returned data

Responses

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

Paginated collection of claims.

Field	Type	Required	Description
`claims`	array of object	Yes	Claims included on this page of results.
`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.

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.

Claim POST

/api/claims

Claim a resource

Takes a claim on the named resource for the connection connectionId, which must be the caller’s own live connection in the session organization. Succeeds with 201 when the resource has no active claim. When the same connection already holds the active claim the call is a replay and returns it unchanged with 200. An active claim held by another connection answers 409. A claim past expiresAt, or one whose holding connection was deleted, is marked expired and superseded. The resource must exist in the session organization; a server verifies the resource types it serves (for example content_item and schedule) and refuses any other type with 400. Decided in a single server-side statement, so of two racing claimants exactly one wins.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/claims

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/claims

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/claims

Request body

application/json Required

Payload for taking a claim. Contains only client-settable fields; the owning organizationId, claimantUserId, status, claimedAt, expiresAt and the timestamps are server-managed.

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.
`durationMinutes`	integer	No	Requested claim duration in minutes; the server applies its default (30) when omitted and may cap it.
`resourceId`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`resourceType`	string	Yes	Type of the resource to claim, for example `content_item`.

Returned data

Responses

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

Server-returned claim: a time-bound hold that one connection takes on one resource so that competing workers never act on it twice. A claim is generic: it names the resource it holds by type and ID, and any construct can be claimed. A claim is held by a connection (claimantConnectionId, for example the connection a desktop client registered for its machine) on behalf of the user whose session took it (claimantUserId). At most one claim per resource is active in an organization. A claim whose expiresAt has passed reads as expired and the resource may be claimed again, so a holder that disappears never strands the resource. Released and expired claims are kept as history: a handoff is an expired claim followed by an active claim on the same resource. The holder reports what happened (outcome) when it releases the claim. The race between claimants is decided server-side in a single statement.

Field	Type	Required	Description
`id`	string (uuid)	Yes	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.
`resourceType`	string	Yes	Type of the claimed resource, the construct name in snake_case, for example `content_item` or `schedule`.
`resourceId`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`claimantConnectionId`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`claimantUserId`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`status`	string	Yes	Lifecycle of the claim. `active` while held, `released` once the holder (or a member allowed to release it) lets it go, `expired` once `expiresAt` passed without a renewal or the holding connection was deleted. Expiry is evaluated when the claim is read, so a claim never reads `active` past its `expiresAt`.
`claimedAt`	string (date-time)	Yes	Time the claim was taken.
`expiresAt`	string (date-time)	Yes	Time the claim lapses unless the holder renews it. Always set by the server; a claim past this time is stale.
`renewedAt`	string \| null (date-time)	No	Time of the last renewal. Null until the claim is first renewed.
`releasedAt`	string \| null (date-time)	No	Time the claim was released. Null while the claim is active or after it expired.
`outcome`	string	No	What the releaser reported when the claim was released: `completed` when the work behind it finished, `failed` when it was attempted and did not succeed, `cancelled` when it was let go without the work being done (including a release by another member). Omitted while the claim is active and on an expired claim.
`outcomeError`	string	No	Error reported with a `failed` outcome. Omitted otherwise.
`outcomeEventId`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`releasedBy`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`createdAt`	string (date-time)	Yes	Timestamp of claim creation.
`updatedAt`	string (date-time)	Yes	Timestamp of last claim modification.

Server-returned claim: a time-bound hold that one connection takes on one resource so that competing workers never act on it twice. A claim is generic: it names the resource it holds by type and ID, and any construct can be claimed. A claim is held by a connection (claimantConnectionId, for example the connection a desktop client registered for its machine) on behalf of the user whose session took it (claimantUserId). At most one claim per resource is active in an organization. A claim whose expiresAt has passed reads as expired and the resource may be claimed again, so a holder that disappears never strands the resource. Released and expired claims are kept as history: a handoff is an expired claim followed by an active claim on the same resource. The holder reports what happened (outcome) when it releases the claim. The race between claimants is decided server-side in a single statement.

Field	Type	Required	Description
`id`	string (uuid)	Yes	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.
`resourceType`	string	Yes	Type of the claimed resource, the construct name in snake_case, for example `content_item` or `schedule`.
`resourceId`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`claimantConnectionId`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`claimantUserId`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`status`	string	Yes	Lifecycle of the claim. `active` while held, `released` once the holder (or a member allowed to release it) lets it go, `expired` once `expiresAt` passed without a renewal or the holding connection was deleted. Expiry is evaluated when the claim is read, so a claim never reads `active` past its `expiresAt`.
`claimedAt`	string (date-time)	Yes	Time the claim was taken.
`expiresAt`	string (date-time)	Yes	Time the claim lapses unless the holder renews it. Always set by the server; a claim past this time is stale.
`renewedAt`	string \| null (date-time)	No	Time of the last renewal. Null until the claim is first renewed.
`releasedAt`	string \| null (date-time)	No	Time the claim was released. Null while the claim is active or after it expired.
`outcome`	string	No	What the releaser reported when the claim was released: `completed` when the work behind it finished, `failed` when it was attempted and did not succeed, `cancelled` when it was let go without the work being done (including a release by another member). Omitted while the claim is active and on an expired claim.
`outcomeError`	string	No	Error reported with a `failed` outcome. Omitted otherwise.
`outcomeEventId`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`releasedBy`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`createdAt`	string (date-time)	Yes	Timestamp of claim creation.
`updatedAt`	string (date-time)	Yes	Timestamp of last claim modification.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/claims/{claimId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/claims/{claimId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/claims/{claimId}

Parameters

Path parameters

Name	Type	Required	Description
`claimId`	string (uuid)	Yes	Claim ID

Returned data

Responses

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

Server-returned claim: a time-bound hold that one connection takes on one resource so that competing workers never act on it twice. A claim is generic: it names the resource it holds by type and ID, and any construct can be claimed. A claim is held by a connection (claimantConnectionId, for example the connection a desktop client registered for its machine) on behalf of the user whose session took it (claimantUserId). At most one claim per resource is active in an organization. A claim whose expiresAt has passed reads as expired and the resource may be claimed again, so a holder that disappears never strands the resource. Released and expired claims are kept as history: a handoff is an expired claim followed by an active claim on the same resource. The holder reports what happened (outcome) when it releases the claim. The race between claimants is decided server-side in a single statement.

Field	Type	Required	Description
`id`	string (uuid)	Yes	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.
`resourceType`	string	Yes	Type of the claimed resource, the construct name in snake_case, for example `content_item` or `schedule`.
`resourceId`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`claimantConnectionId`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`claimantUserId`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`status`	string	Yes	Lifecycle of the claim. `active` while held, `released` once the holder (or a member allowed to release it) lets it go, `expired` once `expiresAt` passed without a renewal or the holding connection was deleted. Expiry is evaluated when the claim is read, so a claim never reads `active` past its `expiresAt`.
`claimedAt`	string (date-time)	Yes	Time the claim was taken.
`expiresAt`	string (date-time)	Yes	Time the claim lapses unless the holder renews it. Always set by the server; a claim past this time is stale.
`renewedAt`	string \| null (date-time)	No	Time of the last renewal. Null until the claim is first renewed.
`releasedAt`	string \| null (date-time)	No	Time the claim was released. Null while the claim is active or after it expired.
`outcome`	string	No	What the releaser reported when the claim was released: `completed` when the work behind it finished, `failed` when it was attempted and did not succeed, `cancelled` when it was let go without the work being done (including a release by another member). Omitted while the claim is active and on an expired claim.
`outcomeError`	string	No	Error reported with a `failed` outcome. Omitted otherwise.
`outcomeEventId`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`releasedBy`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`createdAt`	string (date-time)	Yes	Timestamp of claim creation.
`updatedAt`	string (date-time)	Yes	Timestamp of last claim modification.

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.

Claim POST

/api/claims/{claimId}/release

Release a claim

Ends an active claim and records what happened: sets status to released, releasedAt, releasedBy and the reported outcome, outcomeError and outcomeEventId. The holder may release its own claim from any of its connections (the claim’s claimantUserId is the caller); a member holding Release claims of other members may release anyone’s. Anyone else is answered 409. Releasing a claim that is already released is a no-op that returns the stored claim unchanged, whatever outcome is sent. A claim that expired cannot be released (409): the resource may already have been handed off. outcomeError is accepted only with outcome: failed; outcomeEventId must name a live event the claim’s holder owns, else 404.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/claims/{claimId}/release

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/claims/{claimId}/release

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/claims/{claimId}/release

Parameters

Path parameters

Name	Type	Required	Description
`claimId`	string (uuid)	Yes	Claim ID

Request body

application/json Required

Payload for releasing a claim with the outcome of the work it held. The releaser is the session user; no connection is needed, so a holder can release a stuck hold from another of its computers, and an authorized member can release someone else’s.

Field	Type	Required	Description
`outcome`	string	Yes	What happened to the work the claim held.
`outcomeError`	string	No	Error behind a `failed` outcome. Refused with any other outcome.
`outcomeEventId`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.

Returned data

Responses

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

Server-returned claim: a time-bound hold that one connection takes on one resource so that competing workers never act on it twice. A claim is generic: it names the resource it holds by type and ID, and any construct can be claimed. A claim is held by a connection (claimantConnectionId, for example the connection a desktop client registered for its machine) on behalf of the user whose session took it (claimantUserId). At most one claim per resource is active in an organization. A claim whose expiresAt has passed reads as expired and the resource may be claimed again, so a holder that disappears never strands the resource. Released and expired claims are kept as history: a handoff is an expired claim followed by an active claim on the same resource. The holder reports what happened (outcome) when it releases the claim. The race between claimants is decided server-side in a single statement.

Field	Type	Required	Description
`id`	string (uuid)	Yes	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.
`resourceType`	string	Yes	Type of the claimed resource, the construct name in snake_case, for example `content_item` or `schedule`.
`resourceId`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`claimantConnectionId`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`claimantUserId`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`status`	string	Yes	Lifecycle of the claim. `active` while held, `released` once the holder (or a member allowed to release it) lets it go, `expired` once `expiresAt` passed without a renewal or the holding connection was deleted. Expiry is evaluated when the claim is read, so a claim never reads `active` past its `expiresAt`.
`claimedAt`	string (date-time)	Yes	Time the claim was taken.
`expiresAt`	string (date-time)	Yes	Time the claim lapses unless the holder renews it. Always set by the server; a claim past this time is stale.
`renewedAt`	string \| null (date-time)	No	Time of the last renewal. Null until the claim is first renewed.
`releasedAt`	string \| null (date-time)	No	Time the claim was released. Null while the claim is active or after it expired.
`outcome`	string	No	What the releaser reported when the claim was released: `completed` when the work behind it finished, `failed` when it was attempted and did not succeed, `cancelled` when it was let go without the work being done (including a release by another member). Omitted while the claim is active and on an expired claim.
`outcomeError`	string	No	Error reported with a `failed` outcome. Omitted otherwise.
`outcomeEventId`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`releasedBy`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`createdAt`	string (date-time)	Yes	Timestamp of claim creation.
`updatedAt`	string (date-time)	Yes	Timestamp of last claim modification.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/claims/{claimId}/renew

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/claims/{claimId}/renew

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/claims/{claimId}/renew

Parameters

Path parameters

Name	Type	Required	Description
`claimId`	string (uuid)	Yes	Claim ID

Request body

application/json Required

Payload for renewing a claim. Only the holding connection may renew.

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.
`durationMinutes`	integer	No	Requested extension in minutes from now; the server applies its default (30) when omitted and may cap it.

Returned data

Responses

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

Server-returned claim: a time-bound hold that one connection takes on one resource so that competing workers never act on it twice. A claim is generic: it names the resource it holds by type and ID, and any construct can be claimed. A claim is held by a connection (claimantConnectionId, for example the connection a desktop client registered for its machine) on behalf of the user whose session took it (claimantUserId). At most one claim per resource is active in an organization. A claim whose expiresAt has passed reads as expired and the resource may be claimed again, so a holder that disappears never strands the resource. Released and expired claims are kept as history: a handoff is an expired claim followed by an active claim on the same resource. The holder reports what happened (outcome) when it releases the claim. The race between claimants is decided server-side in a single statement.

Field	Type	Required	Description
`id`	string (uuid)	Yes	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.
`resourceType`	string	Yes	Type of the claimed resource, the construct name in snake_case, for example `content_item` or `schedule`.
`resourceId`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`claimantConnectionId`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`claimantUserId`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`status`	string	Yes	Lifecycle of the claim. `active` while held, `released` once the holder (or a member allowed to release it) lets it go, `expired` once `expiresAt` passed without a renewal or the holding connection was deleted. Expiry is evaluated when the claim is read, so a claim never reads `active` past its `expiresAt`.
`claimedAt`	string (date-time)	Yes	Time the claim was taken.
`expiresAt`	string (date-time)	Yes	Time the claim lapses unless the holder renews it. Always set by the server; a claim past this time is stale.
`renewedAt`	string \| null (date-time)	No	Time of the last renewal. Null until the claim is first renewed.
`releasedAt`	string \| null (date-time)	No	Time the claim was released. Null while the claim is active or after it expired.
`outcome`	string	No	What the releaser reported when the claim was released: `completed` when the work behind it finished, `failed` when it was attempted and did not succeed, `cancelled` when it was let go without the work being done (including a release by another member). Omitted while the claim is active and on an expired claim.
`outcomeError`	string	No	Error reported with a `failed` outcome. Omitted otherwise.
`outcomeEventId`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`releasedBy`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`createdAt`	string (date-time)	Yes	Timestamp of claim creation.
`updatedAt`	string (date-time)	Yes	Timestamp of last claim modification.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/content-items

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/content-items

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/content-items

Parameters

Query parameters

Name	Type	Required	Description
`page`	integer	No	Get responses by page
`pageSize`	integer	No	Number of items per page (canonical camelCase form).
`pagesize`	integer	No	Number of items per page. Deprecated alias of pageSize; canonical `pageSize` wins when both are present.
`search`	string	No	Get responses that match search param value
`order`	string	No	Get ordered responses
`profile`	string	No	Filter by owning profile subject (exact match).
`threadId`	string (uuid)	No	Return one thread: the root item this ID names and every live item whose `threadId` names it.

Returned data

Responses

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

Paginated collection of content items.

Field	Type	Required	Description
`contentItems`	array of object	No	Content items included on this page of results.
`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.

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.

ContentItem POST

/api/content-items

Insert a content item

Inserts a new content item. Insert-only: any supplied id and expectedFingerprint are ignored; existing rows change only through the conditional updateContentItem. The fingerprint is server-computed. Row numbers are unique across the live content items of the organization, whatever their profile. When rowNumber is omitted the server assigns the next row number of the organization (one more than the highest row number the organization has used, counting soft-deleted content items so a deleted item’s number is not handed out again by assignment), atomically with the insert, so concurrent inserts never receive the same number. An organization that has never had a content item is assigned row number 1 first (an explicit rowNumber of 0 is still accepted). A supplied rowNumber that another live content item of the organization already holds refuses the insert with a 409. A rulesOfEngagement outside its schema (an unknown preset or dial, or a value out of range) is refused with a 400, on insert and on update alike. Each mediaAssetIds entry must name a media asset of the session organization, else 400 (the same 400 for a missing, another organization’s and a deleted asset), on insert and on update alike. The server does not require the asset to be ready at write time: deleting an asset does not check content item references, and such an item is refused by name when it posts, so the posting client checks readiness. Thread fields are checked against the organization’s live content items in the same transaction as the insert, and a violation is refused with a 400: threadId must name a live item of the organization that is not itself part of a thread; replyToId requires threadId and must name that root or a live item of the same thread; threadIndex is required exactly when threadId is given and must exceed the position of the item replyToId names (the root counts as 0). An item of another organization, a deleted item and a missing one receive the same 400. A threadIndex that another live item of the same thread already holds refuses the insert with a 409.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/content-items

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/content-items

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/content-items

Request body

application/json Required

Payload for inserting or updating a content item. Contains only client-settable fields; the owning organizationId (derived from the authenticated session), the server-computed fingerprint and the server-generated createdAt / updatedAt timestamps are intentionally excluded.

Field	Type	Required	Description
`data`	object	No	Content values, stored as a JSON blob.
`expectedFingerprint`	string	No	Optimistic-concurrency precondition for update: when supplied, the update applies only when the stored fingerprint still matches, and is refused with a 409 otherwise. Ignored on insert.
`id`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`mediaAssetIds`	array of string (uuid)	No	The media assets the item posts, in posting order. Omitted on insert means none; omitted on update keeps the stored list (old clients send the whole item without it); an empty array clears it.
`profile`	string	Yes	Subject of the owning profile.
`replyToId`	string (uuid)	No	ID of the item this item answers directly: the root named by `threadId` or an item of the same thread. Requires `threadId`. Read on insert; on update it must be omitted or equal the stored value.
`rowNumber`	integer	No	Row number of the content item, unique across the live content items of the organization. Optional: omitted on insert, the server assigns the next row number of the organization; omitted on update, the stored row number is kept.
`rulesOfEngagement`	object	No	The item’s own rules of engagement, which can only tighten the rules its profile and platform run under. Omitted on insert, the item has none; omitted on update, the stored rules are kept; `null` on update clears them.
`threadId`	string (uuid)	No	ID of the thread’s root item. Read on insert; on update it must be omitted or equal the stored value.
`threadIndex`	integer	No	Position of the item in its thread, the root counting as 0. Required exactly when `threadId` is given. Read on insert; on update it must be omitted or equal the stored value.

Returned data

Responses

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

Server-returned content item as persisted by the owning service. Content items carry a row number and a server-computed fingerprint over their canonical values; updates are conditional on the fingerprint the writer read, so stale writes are refused rather than silently applied. An item may carry its own rules of engagement, which can only tighten, and may belong to a thread through threadId, replyToId and threadIndex. See docs/content-item-contract.md.

Field	Type	Required	Description
`id`	string (uuid)	Yes	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.
`profile`	string	Yes	Subject of the owning profile.
`rowNumber`	integer	Yes	Row number of the content item, unique across the live content items of the organization.
`fingerprint`	string	Yes	Hex digest over the canonical content values (`data`, `profile`, `rowNumber` and, when set, `rulesOfEngagement` and `mediaAssetIds`), typed so null, empty string, zero and false differ. An item without them hashes exactly as it did before the fields existed. The thread fields are fixed at insert and are not part of it. Server-computed; used for conditional updates.
`data`	object	No	Content values, stored as a JSON blob.
`createdAt`	string (date-time)	Yes	Timestamp of content item creation.
`updatedAt`	string (date-time)	Yes	Timestamp of last content item modification.
`deletedAt`	string \| null (date-time)	No	Timestamp when the content item was soft-deleted.
`createdBy`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`rulesOfEngagement`	object	No	The item’s own rules of engagement, set by the order that wrote it. They can only tighten: the client that runs the item applies the stricter of these and the rules that apply to the item’s profile and platform without them, and the warm-up and the pause after a sign-in challenge always apply. The server validates the shape and stores the value; it does not resolve it. Omitted when the item has none, in which case the item runs under the rules that apply without them.
`threadId`	string (uuid)	No	ID of the root item of the thread this item belongs to: the first post of a split thread, or the first transmission of a conversation between profiles. Omitted on a standalone item and on a root itself; a root is the item other items name here. Set on insert only.
`replyToId`	string (uuid)	No	ID of the item this item answers directly: the thread root or another item of the same thread. A split thread’s part names the part before it; a reply in a conversation between profiles names the transmission above it. Omitted when the item answers nothing. Never set without `threadId`. Set on insert only.
`threadIndex`	integer	No	Position of the item in its thread, counting the root as 0. Present exactly when `threadId` is, unique among the live items of the thread, and greater than the position of the item named by `replyToId`. Set on insert only.
`mediaAssetIds`	array of string (uuid)	No	The media assets the item posts, in posting order. Ids only, never URLs. Omitted when the item posts no file.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/content-items/{contentItemId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/content-items/{contentItemId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/content-items/{contentItemId}

Parameters

Path parameters

Name	Type	Required	Description
`contentItemId`	string (uuid)	Yes	Content item ID

Returned data

Responses

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

Server-returned content item as persisted by the owning service. Content items carry a row number and a server-computed fingerprint over their canonical values; updates are conditional on the fingerprint the writer read, so stale writes are refused rather than silently applied. An item may carry its own rules of engagement, which can only tighten, and may belong to a thread through threadId, replyToId and threadIndex. See docs/content-item-contract.md.

Field	Type	Required	Description
`id`	string (uuid)	Yes	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.
`profile`	string	Yes	Subject of the owning profile.
`rowNumber`	integer	Yes	Row number of the content item, unique across the live content items of the organization.
`fingerprint`	string	Yes	Hex digest over the canonical content values (`data`, `profile`, `rowNumber` and, when set, `rulesOfEngagement` and `mediaAssetIds`), typed so null, empty string, zero and false differ. An item without them hashes exactly as it did before the fields existed. The thread fields are fixed at insert and are not part of it. Server-computed; used for conditional updates.
`data`	object	No	Content values, stored as a JSON blob.
`createdAt`	string (date-time)	Yes	Timestamp of content item creation.
`updatedAt`	string (date-time)	Yes	Timestamp of last content item modification.
`deletedAt`	string \| null (date-time)	No	Timestamp when the content item was soft-deleted.
`createdBy`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`rulesOfEngagement`	object	No	The item’s own rules of engagement, set by the order that wrote it. They can only tighten: the client that runs the item applies the stricter of these and the rules that apply to the item’s profile and platform without them, and the warm-up and the pause after a sign-in challenge always apply. The server validates the shape and stores the value; it does not resolve it. Omitted when the item has none, in which case the item runs under the rules that apply without them.
`threadId`	string (uuid)	No	ID of the root item of the thread this item belongs to: the first post of a split thread, or the first transmission of a conversation between profiles. Omitted on a standalone item and on a root itself; a root is the item other items name here. Set on insert only.
`replyToId`	string (uuid)	No	ID of the item this item answers directly: the thread root or another item of the same thread. A split thread’s part names the part before it; a reply in a conversation between profiles names the transmission above it. Omitted when the item answers nothing. Never set without `threadId`. Set on insert only.
`threadIndex`	integer	No	Position of the item in its thread, counting the root as 0. Present exactly when `threadId` is, unique among the live items of the thread, and greater than the position of the item named by `replyToId`. Set on insert only.
`mediaAssetIds`	array of string (uuid)	No	The media assets the item posts, in posting order. Ids only, never URLs. Omitted when the item posts no file.

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.

ContentItem PUT

/api/content-items/{contentItemId}

Update a content item

Conditionally updates the content item. When expectedFingerprint is supplied and stale, the update is refused with a 409, as is an update that would move the item onto a rowNumber another live content item of the organization holds. An omitted rowNumber keeps the stored one. An omitted rulesOfEngagement keeps the stored rules and null clears them, so a writer that does not know the field never erases it. An omitted mediaAssetIds keeps the stored list and [] clears it. The thread fields are fixed at insert: omitted, or equal to the stored values, they are kept; any other value is refused with a 400.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/content-items/{contentItemId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/content-items/{contentItemId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/content-items/{contentItemId}

Parameters

Path parameters

Name	Type	Required	Description
`contentItemId`	string (uuid)	Yes	Content item ID

Request body

application/json Required

Payload for inserting or updating a content item. Contains only client-settable fields; the owning organizationId (derived from the authenticated session), the server-computed fingerprint and the server-generated createdAt / updatedAt timestamps are intentionally excluded.

Field	Type	Required	Description
`data`	object	No	Content values, stored as a JSON blob.
`expectedFingerprint`	string	No	Optimistic-concurrency precondition for update: when supplied, the update applies only when the stored fingerprint still matches, and is refused with a 409 otherwise. Ignored on insert.
`id`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`mediaAssetIds`	array of string (uuid)	No	The media assets the item posts, in posting order. Omitted on insert means none; omitted on update keeps the stored list (old clients send the whole item without it); an empty array clears it.
`profile`	string	Yes	Subject of the owning profile.
`replyToId`	string (uuid)	No	ID of the item this item answers directly: the root named by `threadId` or an item of the same thread. Requires `threadId`. Read on insert; on update it must be omitted or equal the stored value.
`rowNumber`	integer	No	Row number of the content item, unique across the live content items of the organization. Optional: omitted on insert, the server assigns the next row number of the organization; omitted on update, the stored row number is kept.
`rulesOfEngagement`	object	No	The item’s own rules of engagement, which can only tighten the rules its profile and platform run under. Omitted on insert, the item has none; omitted on update, the stored rules are kept; `null` on update clears them.
`threadId`	string (uuid)	No	ID of the thread’s root item. Read on insert; on update it must be omitted or equal the stored value.
`threadIndex`	integer	No	Position of the item in its thread, the root counting as 0. Required exactly when `threadId` is given. Read on insert; on update it must be omitted or equal the stored value.

Returned data

Responses

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

Server-returned content item as persisted by the owning service. Content items carry a row number and a server-computed fingerprint over their canonical values; updates are conditional on the fingerprint the writer read, so stale writes are refused rather than silently applied. An item may carry its own rules of engagement, which can only tighten, and may belong to a thread through threadId, replyToId and threadIndex. See docs/content-item-contract.md.

Field	Type	Required	Description
`id`	string (uuid)	Yes	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.
`profile`	string	Yes	Subject of the owning profile.
`rowNumber`	integer	Yes	Row number of the content item, unique across the live content items of the organization.
`fingerprint`	string	Yes	Hex digest over the canonical content values (`data`, `profile`, `rowNumber` and, when set, `rulesOfEngagement` and `mediaAssetIds`), typed so null, empty string, zero and false differ. An item without them hashes exactly as it did before the fields existed. The thread fields are fixed at insert and are not part of it. Server-computed; used for conditional updates.
`data`	object	No	Content values, stored as a JSON blob.
`createdAt`	string (date-time)	Yes	Timestamp of content item creation.
`updatedAt`	string (date-time)	Yes	Timestamp of last content item modification.
`deletedAt`	string \| null (date-time)	No	Timestamp when the content item was soft-deleted.
`createdBy`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`rulesOfEngagement`	object	No	The item’s own rules of engagement, set by the order that wrote it. They can only tighten: the client that runs the item applies the stricter of these and the rules that apply to the item’s profile and platform without them, and the warm-up and the pause after a sign-in challenge always apply. The server validates the shape and stores the value; it does not resolve it. Omitted when the item has none, in which case the item runs under the rules that apply without them.
`threadId`	string (uuid)	No	ID of the root item of the thread this item belongs to: the first post of a split thread, or the first transmission of a conversation between profiles. Omitted on a standalone item and on a root itself; a root is the item other items name here. Set on insert only.
`replyToId`	string (uuid)	No	ID of the item this item answers directly: the thread root or another item of the same thread. A split thread’s part names the part before it; a reply in a conversation between profiles names the transmission above it. Omitted when the item answers nothing. Never set without `threadId`. Set on insert only.
`threadIndex`	integer	No	Position of the item in its thread, counting the root as 0. Present exactly when `threadId` is, unique among the live items of the thread, and greater than the position of the item named by `replyToId`. Set on insert only.
`mediaAssetIds`	array of string (uuid)	No	The media assets the item posts, in posting order. Ids only, never URLs. Omitted when the item posts no file.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/content-items/{contentItemId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/content-items/{contentItemId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/content-items/{contentItemId}

Parameters

Path parameters

Name	Type	Required	Description
`contentItemId`	string (uuid)	Yes	Content item ID

Query parameters

Name	Type	Required	Description
`expectedFingerprint`	string	No	Optional optimistic-concurrency precondition for delete: the delete applies only when the stored fingerprint still matches.

Returned data

Responses

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

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.

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/content/design/share

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/content/design/share

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/content/design/share

application/json Required

Body for sharing a design, filter, or view with recipients by email.

Payload for sharing a piece of content (design, filter, or view) with one or more recipients by email. This schema backs both POST /api/content/design/share and POST /api/content/view/share; the server dispatches on contentType to decide which entity to mutate.

Field	Type	Required	Description
`contentId`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`contentType`	string	Yes	The kind of content being shared. Must match the entity the handler expects — `pattern` and `filter` are valid on the design share endpoint; `view` is valid on the view share endpoint.
`emails`	array of string (email)	Yes	Email addresses of the recipients to share this content with.
`share`	boolean	Yes	When true, flip visibility to public and send invitation emails to the recipients. When false, revert visibility to private.

Returned data

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

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/content/filters

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/content/filters

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/content/filters

Parameters

Query parameters

Name	Type	Required	Description
`page`	integer	No	Get responses by page
`pageSize`	integer	No	Number of items per page (canonical camelCase form).
`search`	string	No	Get responses that match search param value
`order`	string	No	Get ordered responses
`orgId`	string (uuid)	No	User’s organization ID
`visibility`	array of string	No	Filter by visibility (public, private, published). May be repeated.
`owner`	string (uuid)	No	UUID of the owning user. Pass when fetching public/published filters for a specific user (public-profile lookups).

Returned data

Responses

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

Paginated collection of filters.

Field	Type	Required	Description
`filters`	array of object	No	Filters included on this page of results.
`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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/content/filters

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/content/filters

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/content/filters

Request body

application/json Required

Payload for upserting a filter via POST /api/content/filters. Mirrors meshery-cloud’s MesheryFilterRequestBody and meshery’s MesheryFilterRequestBody — the wrapper carries an optional source URL/path plus a save toggle and an embedded filterData payload. Wire form for the embedded payload field is canonical camelCase (filterData); legacy snake_case (filter_data) is accepted by the existing handlers for the deprecation window but new clients MUST emit filterData.

Field	Type	Required	Description
`config`	string	No	Optional opaque configuration string passed through to the underlying filter runtime. Persisted only on the local meshery `MesheryFilterPayload` shape; meshery-cloud currently ignores the field, but it is documented here so the canonical contract is single-sourced.
`filterData`	object	No	Filter body to persist.
`path`	string	No	Optional source path the filter was loaded from.
`save`	boolean	No	When true, persist the filter in addition to parsing it. When false, the server returns the parsed payload without committing it to the database.
`url`	string (uri)	No	Optional source URL the filter was fetched from.

Returned data

Responses

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

Server-returned Meshery filter resource as persisted by meshery-cloud (meshery_filters table) and consumed by meshery’s models.MesheryFilter. Filters carry an opaque body (filterFile) plus catalog and visibility metadata, and follow the same content-resource shape as designs minus the catalog engagement counters (the meshery_filters table has no view_count / download_count columns).

Field	Type	Required	Description
`id`	string (uuid)	Yes	Server-generated filter ID.
`name`	string	Yes	Human-readable filter name; required, used for catalog listings.
`owner`	string (uuid)	Yes	Owning user ID.
`filterFile`	string (byte)	No	Raw filter source persisted as a byte array (`bytea` column `filter_file`). Wire form is base64 per OpenAPI `format: byte`.
`filterResource`	string	No	Filter resource discriminator describing the filter body’s source format (e.g. WASM module identifier or external resource path). Stored in the `filter_resource` text column.
`location`	object	No	Optional structured location metadata (branch, host, path, …).
`visibility`	string	No	Visibility scope (private, public, published).
`catalogData`	object	No	Catalog metadata attached to the filter when published.
`createdAt`	string (date-time)	Yes	Timestamp of filter creation.
`updatedAt`	string (date-time)	Yes	Timestamp of last filter modification.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/content/filters/clone/{filterId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/content/filters/clone/{filterId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/content/filters/clone/{filterId}

Parameters

Path parameters

Name	Type	Required	Description
`filterId`	string (uuid)	Yes	Filter ID

Request body

application/json Required

Payload for POST /api/content/filters/clone/{filterId}. The only client-settable field is the optional name applied to the cloned filter; the server derives ownership and visibility from the request context.

Field	Type	Required	Description
`name`	string	No	Optional name to apply to the cloned filter. Defaults to a server-generated derivative of the source filter’s name.

Returned data

Responses

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

Server-returned Meshery filter resource as persisted by meshery-cloud (meshery_filters table) and consumed by meshery’s models.MesheryFilter. Filters carry an opaque body (filterFile) plus catalog and visibility metadata, and follow the same content-resource shape as designs minus the catalog engagement counters (the meshery_filters table has no view_count / download_count columns).

Field	Type	Required	Description
`id`	string (uuid)	Yes	Server-generated filter ID.
`name`	string	Yes	Human-readable filter name; required, used for catalog listings.
`owner`	string (uuid)	Yes	Owning user ID.
`filterFile`	string (byte)	No	Raw filter source persisted as a byte array (`bytea` column `filter_file`). Wire form is base64 per OpenAPI `format: byte`.
`filterResource`	string	No	Filter resource discriminator describing the filter body’s source format (e.g. WASM module identifier or external resource path). Stored in the `filter_resource` text column.
`location`	object	No	Optional structured location metadata (branch, host, path, …).
`visibility`	string	No	Visibility scope (private, public, published).
`catalogData`	object	No	Catalog metadata attached to the filter when published.
`createdAt`	string (date-time)	Yes	Timestamp of filter creation.
`updatedAt`	string (date-time)	Yes	Timestamp of last filter modification.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/content/filters/delete

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/content/filters/delete

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/content/filters/delete

Request body

application/json Required

Payload for bulk deleting filters by ID.

Field	Type	Required	Description
`filters`	array of object	Yes	Filters targeted for deletion.

Returned data

Responses

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

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/content/filters/download/{filterId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/content/filters/download/{filterId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/content/filters/download/{filterId}

Parameters

Path parameters

Name	Type	Required	Description
`filterId`	string (uuid)	Yes	Filter ID

Returned data

Responses

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

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/content/filters/{filterId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/content/filters/{filterId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/content/filters/{filterId}

Parameters

Path parameters

Name	Type	Required	Description
`filterId`	string (uuid)	Yes	Filter ID

Returned data

Responses

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

Server-returned Meshery filter resource as persisted by meshery-cloud (meshery_filters table) and consumed by meshery’s models.MesheryFilter. Filters carry an opaque body (filterFile) plus catalog and visibility metadata, and follow the same content-resource shape as designs minus the catalog engagement counters (the meshery_filters table has no view_count / download_count columns).

Field	Type	Required	Description
`id`	string (uuid)	Yes	Server-generated filter ID.
`name`	string	Yes	Human-readable filter name; required, used for catalog listings.
`owner`	string (uuid)	Yes	Owning user ID.
`filterFile`	string (byte)	No	Raw filter source persisted as a byte array (`bytea` column `filter_file`). Wire form is base64 per OpenAPI `format: byte`.
`filterResource`	string	No	Filter resource discriminator describing the filter body’s source format (e.g. WASM module identifier or external resource path). Stored in the `filter_resource` text column.
`location`	object	No	Optional structured location metadata (branch, host, path, …).
`visibility`	string	No	Visibility scope (private, public, published).
`catalogData`	object	No	Catalog metadata attached to the filter when published.
`createdAt`	string (date-time)	Yes	Timestamp of filter creation.
`updatedAt`	string (date-time)	Yes	Timestamp of last filter modification.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/content/filters/{filterId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/content/filters/{filterId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/content/filters/{filterId}

Parameters

Path parameters

Name	Type	Required	Description
`filterId`	string (uuid)	Yes	Filter ID

Request body

application/json Required

Payload for creating or updating a filter via POST /api/content/filters or PUT /api/content/filters/{filterId}. Contains only client-settable fields; server-generated createdAt / updatedAt and the owning userId (which the server derives from the authenticated session) are intentionally excluded.

Field	Type	Required	Description
`catalogData`	object	No	Catalog metadata to attach when publishing.
`filterFile`	string (byte)	No	Raw filter source as base64-encoded bytes (`format: byte`). Optional on update — the server preserves the existing body when omitted.
`filterResource`	string	No	Filter resource discriminator describing the body’s source format (e.g. WASM module identifier or external resource path).
`id`	string (uuid)	No	Existing filter ID for updates; omit on create. Wrapped in an `allOf` so we can attach the `json:"id,omitempty"` tag for upsert ergonomics without recursing into the underlying UUID definition.
`location`	object	No	Optional structured location metadata.
`name`	string	Yes	Human-readable filter name.
`visibility`	string	No	Requested visibility scope. The server may downgrade a requested `published` value to `private` for callers that do not own the filter.

Returned data

Responses

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

Server-returned Meshery filter resource as persisted by meshery-cloud (meshery_filters table) and consumed by meshery’s models.MesheryFilter. Filters carry an opaque body (filterFile) plus catalog and visibility metadata, and follow the same content-resource shape as designs minus the catalog engagement counters (the meshery_filters table has no view_count / download_count columns).

Field	Type	Required	Description
`id`	string (uuid)	Yes	Server-generated filter ID.
`name`	string	Yes	Human-readable filter name; required, used for catalog listings.
`owner`	string (uuid)	Yes	Owning user ID.
`filterFile`	string (byte)	No	Raw filter source persisted as a byte array (`bytea` column `filter_file`). Wire form is base64 per OpenAPI `format: byte`.
`filterResource`	string	No	Filter resource discriminator describing the filter body’s source format (e.g. WASM module identifier or external resource path). Stored in the `filter_resource` text column.
`location`	object	No	Optional structured location metadata (branch, host, path, …).
`visibility`	string	No	Visibility scope (private, public, published).
`catalogData`	object	No	Catalog metadata attached to the filter when published.
`createdAt`	string (date-time)	Yes	Timestamp of filter creation.
`updatedAt`	string (date-time)	Yes	Timestamp of last filter modification.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/content/filters/{filterId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/content/filters/{filterId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/content/filters/{filterId}

Parameters

Path parameters

Name	Type	Required	Description
`filterId`	string (uuid)	Yes	Filter ID

Returned data

Responses

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

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/content/patterns

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/content/patterns

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/content/patterns

Parameters

Query parameters

Name	Type	Required	Description
`page`	integer	No	Get responses by page
`pageSize`	integer	No	Number of items per page (canonical camelCase form).
`search`	string	No	Get responses that match search param value
`order`	string	No	Get ordered responses
`orgId`	string (uuid)	No	User’s organization ID
`visibility`	string	No	Filter by visibility (public, private, published)
`userId`	string (uuid)	No	UUID of User. Pass userId for fetching public and published designs.
`metrics`	boolean	No	Whether to include usage metrics in the response.
`workspaceId`	string (uuid)	No	Filter designs by workspace ID.
`populate`	boolean	No	Populate additional nested fields in the response.
`shared`	boolean	No	Include designs shared with the caller.

Returned data

Responses

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

Paginated collection of designs.

Field	Type	Required	Description
`page`	integer	No	Current page number of the result set.
`pageSize`	integer	No	Number of items per page.
`patterns`	array of object	No	Designs included on this page of results.
`resultType`	string	No	Optional discriminator describing which collection the page represents.
`totalCount`	integer	No	Total number of items available.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/content/patterns

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/content/patterns

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/content/patterns

Request body

application/json Required

Payload for upserting a design via POST /api/content/patterns.

Field	Type	Required	Description
`name`	string	No	Human-readable design name.
`path`	string	No	Optional source path the design was loaded from.
`patternData`	object	No	Design body to persist.
`save`	boolean	No	When true, persist the design in addition to parsing it.
`url`	string (uri)	No	Optional source URL the design was fetched from.

Returned data

Responses

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

Server-returned design (pattern) resource as persisted in meshery_patterns. organizationId is required and read-only: the server assigns it from the session organization and clients never send it.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/content/patterns/clone/{designId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/content/patterns/clone/{designId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/content/patterns/clone/{designId}

Parameters

Path parameters

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

Request body

application/json Required

Payload for cloning a design. The optional name is applied to the cloned design; the server derives ownership and visibility from the request context.

Field	Type	Required	Description
`name`	string	No	Optional name to apply to the cloned design.

Returned data

Responses

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

Server-returned design (pattern) resource as persisted in meshery_patterns. organizationId is required and read-only: the server assigns it from the session organization and clients never send it.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/content/patterns/delete

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/content/patterns/delete

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/content/patterns/delete

Request body

application/json Required

Payload for bulk deleting designs by ID.

Field	Type	Required	Description
`patterns`	array of object	No	Designs targeted for deletion.

Returned data

Responses

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

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/content/patterns/download/{designId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/content/patterns/download/{designId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/content/patterns/download/{designId}

Parameters

Path parameters

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

Returned data

Responses

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

Design Designs POST

/api/content/patterns/refresh/{designId}

Refresh design from its source

Re-fetches the source file recorded in the design’s location (type: github, host: github.com/<owner>/<repo>, path, optional branch; an empty branch means the repository’s default branch), re-identifies it, and rewrites the design’s content in place under the same design ID. A Meshery Design source replaces patternFile; any other source type (Helm Chart, Kubernetes Manifest, Docker Compose) replaces sourceContent and clears patternFile, so Meshery reconverts it the next time the design is opened - exactly the state a first import leaves. Only the design’s owner may refresh it. No request body. Denials: 404 answers both “no such design” and “not the caller’s design” with the same body by design, so the route is not an existence oracle; 403 means the repository is not reachable through one of the caller’s verified GitHub App installations - the installations GitHub lists for the caller’s own GitHub account when they authorize the App. The refusal is deliberately uniform: the App not being installed on the repository’s account and its being installed there for someone else answer the same body, so the route does not reveal where the App is installed. A distinct 403 whose MeshKit error asks for re-authorization means the caller’s GitHub connection predates verification; re-authorize it (see startGithubAuthorization) before use; 409 means the design has no refreshable source (location.type is not github, or host/path is missing) or its source path no longer resolves to an importable file; 502 means GitHub could not be reached or rejected the request. The server resolves the tracked ref to a commit, reads the file at that commit, and records it in location.commitSha.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/content/patterns/refresh/{designId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/content/patterns/refresh/{designId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/content/patterns/refresh/{designId}

Parameters

Path parameters

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

Returned data

Responses

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

Server-returned design (pattern) resource as persisted in meshery_patterns. organizationId is required and read-only: the server assigns it from the session organization and clients never send it.

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.

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.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/content/patterns/resource

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/content/patterns/resource

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/content/patterns/resource

Parameters

Query parameters

Name	Type	Required	Description
`page`	integer	No	Get responses by page
`pageSize`	integer	No	Number of items per page (canonical camelCase form).
`pagesize`	integer	No	Number of items per page. Deprecated alias of pageSize kept for the meshery server’s remote provider, which still sends the lowercase form; canonical `pageSize` wins when both are present.
`search`	string	No	Get responses that match search param value
`order`	string	No	Get ordered responses
`name`	string	No	Filter by resource name.
`namespace`	string	No	Filter by Kubernetes namespace.
`type`	string	No	Filter by resource type discriminator.
`oamType`	string	No	Filter by OAM categorization (e.g. workload, trait, scope).
`orgId`	string (uuid)	No	Scope results to an organization.
`workspaceId`	string (uuid)	No	Scope results to a workspace.

Returned data

Responses

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

Paginated collection of pattern resources.

Field	Type	Required	Description
`page`	integer	No	Current page number of the result set.
`pageSize`	integer	No	Number of items per page.
`resources`	array of object	No	Pattern resources included on this page of results.
`totalCount`	integer	No	Total number of items available.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/content/patterns/resource

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/content/patterns/resource

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/content/patterns/resource

Request body

application/json Required

Payload for creating or updating a pattern resource via POST /api/content/patterns/resource. Contains only client-settable fields; the owning userId (derived from the authenticated session), the deleted marker, and the server-generated createdAt / updatedAt timestamps are intentionally excluded.

Field	Type	Required	Description
`id`	string (uuid)	No	Existing pattern resource ID for updates; omit on create.
`name`	string	Yes	Name of the provisioned resource.
`namespace`	string	Yes	Kubernetes namespace the resource was provisioned into.
`oamType`	string	Yes	OAM categorization of the resource (e.g. workload, trait, scope).
`type`	string	Yes	Resource type discriminator (e.g. the Kubernetes kind).

Returned data

Responses

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

Server-returned Meshery pattern resource as persisted by meshery-cloud (meshery_pattern_resources table). A pattern resource records the Kubernetes-addressable identity (name, namespace, type, OAM type) of a resource provisioned from a design, and is used by the design engine to deduplicate provisioned resources. This v1beta3 shape supersedes the legacy v1alpha2 snake_case wire form and corrects its Namepace typo to namespace.

Field	Type	Required	Description
`id`	string (uuid)	Yes	Server-generated pattern resource ID.
`userId`	string (uuid)	Yes	Owning user ID. Persisted in the `owner` column of the `meshery_pattern_resources` table (confirmed against the production schema dump); the wire identifier stays camelCase `userId` per the identifier-naming contract.
`name`	string	Yes	Name of the provisioned resource.
`namespace`	string	Yes	Kubernetes namespace the resource was provisioned into. Corrects the legacy v1alpha2 `Namepace` typo.
`type`	string	Yes	Resource type discriminator (e.g. the Kubernetes kind).
`oamType`	string	Yes	OAM (Open Application Model) categorization of the resource, stored in the `oam_type` column (e.g. `workload`, `trait`, `scope`).
`deleted`	boolean	Yes	Soft-delete marker. Server-managed; rows are flagged rather than removed so the design engine can reconcile prior provisions.
`createdAt`	string (date-time)	Yes	Timestamp of pattern resource creation.
`updatedAt`	string (date-time)	Yes	Timestamp of last pattern resource modification.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/content/patterns/resource/{patternResourceId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/content/patterns/resource/{patternResourceId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/content/patterns/resource/{patternResourceId}

Parameters

Path parameters

Name	Type	Required	Description
`patternResourceId`	string (uuid)	Yes	Pattern resource ID

Returned data

Responses

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

Server-returned Meshery pattern resource as persisted by meshery-cloud (meshery_pattern_resources table). A pattern resource records the Kubernetes-addressable identity (name, namespace, type, OAM type) of a resource provisioned from a design, and is used by the design engine to deduplicate provisioned resources. This v1beta3 shape supersedes the legacy v1alpha2 snake_case wire form and corrects its Namepace typo to namespace.

Field	Type	Required	Description
`id`	string (uuid)	Yes	Server-generated pattern resource ID.
`userId`	string (uuid)	Yes	Owning user ID. Persisted in the `owner` column of the `meshery_pattern_resources` table (confirmed against the production schema dump); the wire identifier stays camelCase `userId` per the identifier-naming contract.
`name`	string	Yes	Name of the provisioned resource.
`namespace`	string	Yes	Kubernetes namespace the resource was provisioned into. Corrects the legacy v1alpha2 `Namepace` typo.
`type`	string	Yes	Resource type discriminator (e.g. the Kubernetes kind).
`oamType`	string	Yes	OAM (Open Application Model) categorization of the resource, stored in the `oam_type` column (e.g. `workload`, `trait`, `scope`).
`deleted`	boolean	Yes	Soft-delete marker. Server-managed; rows are flagged rather than removed so the design engine can reconcile prior provisions.
`createdAt`	string (date-time)	Yes	Timestamp of pattern resource creation.
`updatedAt`	string (date-time)	Yes	Timestamp of last pattern resource modification.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/content/patterns/resource/{patternResourceId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/content/patterns/resource/{patternResourceId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/content/patterns/resource/{patternResourceId}

Parameters

Path parameters

Name	Type	Required	Description
`patternResourceId`	string (uuid)	Yes	Pattern resource ID

Returned data

Responses

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

Server-returned Meshery pattern resource as persisted by meshery-cloud (meshery_pattern_resources table). A pattern resource records the Kubernetes-addressable identity (name, namespace, type, OAM type) of a resource provisioned from a design, and is used by the design engine to deduplicate provisioned resources. This v1beta3 shape supersedes the legacy v1alpha2 snake_case wire form and corrects its Namepace typo to namespace.

Field	Type	Required	Description
`id`	string (uuid)	Yes	Server-generated pattern resource ID.
`userId`	string (uuid)	Yes	Owning user ID. Persisted in the `owner` column of the `meshery_pattern_resources` table (confirmed against the production schema dump); the wire identifier stays camelCase `userId` per the identifier-naming contract.
`name`	string	Yes	Name of the provisioned resource.
`namespace`	string	Yes	Kubernetes namespace the resource was provisioned into. Corrects the legacy v1alpha2 `Namepace` typo.
`type`	string	Yes	Resource type discriminator (e.g. the Kubernetes kind).
`oamType`	string	Yes	OAM (Open Application Model) categorization of the resource, stored in the `oam_type` column (e.g. `workload`, `trait`, `scope`).
`deleted`	boolean	Yes	Soft-delete marker. Server-managed; rows are flagged rather than removed so the design engine can reconcile prior provisions.
`createdAt`	string (date-time)	Yes	Timestamp of pattern resource creation.
`updatedAt`	string (date-time)	Yes	Timestamp of last pattern resource modification.

Design Designs POST

/api/content/patterns/upload/{designId}

Upload design source content

Replaces the raw source content blob stored alongside a design. The server (meshery-cloud’s UpsertPatternSourceContent handler) reads the entire request body as opaque bytes via io.ReadAll and persists them without interpretation, so the content-type is whatever the uploader sent — application/octet-stream is the canonical choice. The previous declaration reused MesheryPatternImportRequestBody under multipart/form-data, which the handler never parses; it remained wired up solely to share a schema ref with /api/pattern/import. See meshery/schemas#771 for the drift analysis.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/content/patterns/upload/{designId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/content/patterns/upload/{designId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/content/patterns/upload/{designId}

Parameters

Path parameters

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

Request body

application/octet-stream Required

Opaque design source bytes (yaml, tarball, etc.)

Schema: string (binary)

Returned data

Responses

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

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/content/patterns/{designId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/content/patterns/{designId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/content/patterns/{designId}

Parameters

Path parameters

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

Query parameters

Name	Type	Required	Description
`metrics`	boolean	No	Whether to include usage metrics in the response.

Returned data

Responses

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

Server-returned design (pattern) resource as persisted in meshery_patterns. organizationId is required and read-only: the server assigns it from the session organization and clients never send it.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/content/patterns/{designId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/content/patterns/{designId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/content/patterns/{designId}

Parameters

Path parameters

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

Returned data

Responses

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

Design Designs PATCH

/api/content/patterns/{designId}/source

Remap a design's GitHub source

Re-points the design’s source binding - the GitHub file its location records and refreshPatternFromSource re-reads - at another repository, path or ref. The design’s content is not changed: call refreshPatternFromSource afterwards to replace it from the new source. The server resolves ref to a commit and confirms that path names an importable file at that commit before it writes anything, so a binding that a refresh could not read is never stored. It writes location as type: github, host, path and branch (= ref). When the binding changes, location.commitSha is removed, because the stored content was not read from the new source; it is kept when the request names the binding the design already has. A design with no GitHub source (an upload or URL import) may be bound to one; it becomes refreshable. Only the design’s owner may remap it. Denials: 404 answers “no such design”, “not the caller’s design” and “connectionId is not the caller’s own live GitHub connection” with the same body, so the route is not an existence oracle; 403 means the repository is not reachable through one of the caller’s verified GitHub App installations - the installations GitHub lists for the caller’s own GitHub account when they authorize the App. The refusal is deliberately uniform: the App not being installed on the repository’s account and its being installed there for someone else answer the same body, so the route does not reveal where the App is installed. A distinct 403 whose MeshKit error asks for re-authorization means the caller’s GitHub connection predates verification; re-authorize it (see startGithubAuthorization) before use; 409 means ref does not resolve to a commit, or path does not name an importable file at it (missing, a directory, or not a supported format); 502 means GitHub could not be reached or rejected the request.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/content/patterns/{designId}/source

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/content/patterns/{designId}/source

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/content/patterns/{designId}/source

Parameters

Path parameters

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

Request body

application/json Required

The GitHub file a design is bound to - what refreshPatternFromSource re-reads.

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.
`host`	string	Yes	Repository as `github.com/<owner>/<repo>` - the same form `location.host` stores.
`path`	string	Yes	Repository-relative path of a file (not a directory), with no leading slash.
`ref`	string	No	Branch or tag the binding tracks, stored as `location.branch`. Empty or omitted means the repository’s default branch.

Returned data

Responses

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

Server-returned design (pattern) resource as persisted in meshery_patterns. organizationId is required and read-only: the server assigns it from the session organization and clients never send it.

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.

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.

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.

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/content/view/share

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/content/view/share

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/content/view/share

application/json Required

Body for sharing a view with recipients by email.

Payload for sharing a view with one or more recipients by email. The wire format matches the canonical design share payload (design.ContentSharePayload in v1beta2/design), restricted to the view content type since that is all this endpoint accepts.

Field	Type	Required	Description
`contentId`	string (uuid)	Yes	Identifier of the view being shared.
`contentType`	string	Yes	The kind of content being shared. Only `view` is accepted on this endpoint.
`emails`	array of string (email)	Yes	Email addresses of the recipients to share this view with.
`share`	boolean	Yes	When true, flip the view’s visibility to public and send invitation emails to the recipients. When false, revert visibility to private.

Returned data

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

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/content/views

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/content/views

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/content/views

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.
`filter`	string	No	JSON-encoded filter string for assignment and soft-delete filters.
`shared`	boolean	No	When true, include views shared with the user.
`visibility`	string	No	Filter by visibility level (public, private).
`orgId`	string	No	Organization ID to scope the request.
`userId`	string	No	UUID of the user whose views to retrieve.

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	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.
`views`	array of object	No	Views in this page, enriched with workspace and organization context.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/content/views

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/content/views

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/content/views

Request body

application/json Required

Body for creating or updating a view

Payload for creating or updating a view.

Field	Type	Required	Description
`filters`	object	No	Filter configuration for this view.
`metadata`	object	No	Metadata associated with the view.
`name`	string	Yes	Display name of the view.
`visibility`	string	No	Visibility level of the view.

Returned data

Responses

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

A saved view with filters and metadata that defines a customized perspective of Meshery resources. Learn more at https://docs.meshery.io/concepts/logical/views

Field	Type	Required	Description
`id`	string (uuid)	Yes	Unique identifier for the view.
`name`	string	Yes	Display name of the view.
`visibility`	string	Yes	Visibility level of the view.
`filters`	object	No	Filter configuration that defines which resources this view displays.
`metadata`	object	No	Additional metadata associated with the view.
`userId`	string (uuid)	Yes	ID of the user who created the view.
`createdAt`	string (date-time)	Yes	Timestamp when the view was created.
`updatedAt`	string (date-time)	Yes	Timestamp when the view was last updated.
`deletedAt`	string \| null (date-time)	No	Timestamp when the view was soft deleted. Null while the view remains active.

Example response

{
  "createdAt": "0001-01-01T00:00:00Z",
  "deletedAt": null,
  "filters": {},
  "id": "00000000-0000-0000-0000-000000000000",
  "metadata": {},
  "name": "My Kubernetes View",
  "updatedAt": "0001-01-01T00:00:00Z",
  "userId": "00000000-0000-0000-0000-000000000000",
  "visibility": "private"
}

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/content/views/{viewId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/content/views/{viewId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/content/views/{viewId}

Parameters

Path parameters

Name	Type	Required	Description
`viewId`	string (uuid)	Yes	View ID

Returned data

Responses

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

A saved view with filters and metadata that defines a customized perspective of Meshery resources. Learn more at https://docs.meshery.io/concepts/logical/views

Field	Type	Required	Description
`id`	string (uuid)	Yes	Unique identifier for the view.
`name`	string	Yes	Display name of the view.
`visibility`	string	Yes	Visibility level of the view.
`filters`	object	No	Filter configuration that defines which resources this view displays.
`metadata`	object	No	Additional metadata associated with the view.
`userId`	string (uuid)	Yes	ID of the user who created the view.
`createdAt`	string (date-time)	Yes	Timestamp when the view was created.
`updatedAt`	string (date-time)	Yes	Timestamp when the view was last updated.
`deletedAt`	string \| null (date-time)	No	Timestamp when the view was soft deleted. Null while the view remains active.

Example response

{
  "createdAt": "0001-01-01T00:00:00Z",
  "deletedAt": null,
  "filters": {},
  "id": "00000000-0000-0000-0000-000000000000",
  "metadata": {},
  "name": "My Kubernetes View",
  "updatedAt": "0001-01-01T00:00:00Z",
  "userId": "00000000-0000-0000-0000-000000000000",
  "visibility": "private"
}

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/content/views/{viewId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/content/views/{viewId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/content/views/{viewId}

Parameters

Path parameters

Name	Type	Required	Description
`viewId`	string (uuid)	Yes	View ID

Request body

application/json Required

Body for creating or updating a view

Payload for creating or updating a view.

Field	Type	Required	Description
`filters`	object	No	Filter configuration for this view.
`metadata`	object	No	Metadata associated with the view.
`name`	string	Yes	Display name of the view.
`visibility`	string	No	Visibility level of the view.

Returned data

Responses

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

A saved view with filters and metadata that defines a customized perspective of Meshery resources. Learn more at https://docs.meshery.io/concepts/logical/views

Field	Type	Required	Description
`id`	string (uuid)	Yes	Unique identifier for the view.
`name`	string	Yes	Display name of the view.
`visibility`	string	Yes	Visibility level of the view.
`filters`	object	No	Filter configuration that defines which resources this view displays.
`metadata`	object	No	Additional metadata associated with the view.
`userId`	string (uuid)	Yes	ID of the user who created the view.
`createdAt`	string (date-time)	Yes	Timestamp when the view was created.
`updatedAt`	string (date-time)	Yes	Timestamp when the view was last updated.
`deletedAt`	string \| null (date-time)	No	Timestamp when the view was soft deleted. Null while the view remains active.

Example response

{
  "createdAt": "0001-01-01T00:00:00Z",
  "deletedAt": null,
  "filters": {},
  "id": "00000000-0000-0000-0000-000000000000",
  "metadata": {},
  "name": "My Kubernetes View",
  "updatedAt": "0001-01-01T00:00:00Z",
  "userId": "00000000-0000-0000-0000-000000000000",
  "visibility": "private"
}

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/content/views/{viewId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/content/views/{viewId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/content/views/{viewId}

Parameters

Path parameters

Name	Type	Required	Description
`viewId`	string (uuid)	Yes	View ID

Returned data

Responses

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

Diagnostics POST

/api/diagnostics/failures

Submit a failure diagnostic

Accepts a small, anonymous, redacted diagnostic of a client-side failure, so maintainers learn about it before anyone writes in. Authentication is a per-client-kind, per-release-channel pre-shared key in the X-Client-Key header (a speed bump plus a revocation handle, not a strong secret: the key ships in the app and can be extracted). A signed-in caller may use its bearer token instead; then the organization is attached, and only then. The server enforces a body cap, strict decoding (unknown fields are rejected), rate limits, server-side re-redaction, and a 90-day retention on stored rows. Served by Layer5 Cloud (meshery-cloud #6330); see Blowhorn issue #771.

Authentication

Diagnostics ClientKey or Bearer JWT

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/diagnostics/failures

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/diagnostics/failures

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/diagnostics/failures

Request body

application/json Required

A single anonymous, redacted report of a client-side failure. The same failure is deduplicated per install per day: one report carries the first time it was seen and how many times it has occurred since. Nothing in this report identifies a person: no config files, logs, account names, post text, or tokens, and the failure message keeps only the redacted cause sentence. Every object in this schema is closed (additionalProperties: false), so a client sending an unknown field gets a 400 rather than a silently widened report.

Field	Type	Required	Description
`client`	object	Yes	No description provided.
`compat`	object	Yes	No description provided.
`count`	integer	Yes	How many times the same failure has occurred on this install within the deduplication window (per install per day).
`diagnosticId`	string (uuid)	Yes	Id generated by the client for this report. A human support request links back to it through AnonymousSupportRequest.diagnosticId.
`failure`	object	Yes	No description provided.
`firstSeenAt`	string (date-time)	Yes	When this failure was first seen on this install, for the deduplication window the count covers.
`installId`	string (uuid)	No	Optional per-install id, present only when the person has not opted out of failure reports. A random uuid4 minted once per install (Blowhorn’s installationId, written beside cloud.yaml and reused), never a hardware id. Omitted entirely when opted out.
`occurredAt`	string (date-time)	Yes	When this occurrence of the failure happened.
`os`	object	Yes	No description provided.

Returned data

Responses

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

Field	Type	Required	Description
`diagnosticId`	string (uuid)	Yes	The stored diagnostic’s id: the client’s own when it sent one, otherwise generated by the server. Send it as AnonymousSupportRequest.diagnosticId to link a human report to this diagnostic.

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.

Field	Type	Required	Description
`message`	string	Yes	The refusal, for example “Client key required for operation is invalid or missing”.

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.

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.

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.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/entitlement/features

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/entitlement/features

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/entitlement/features

Parameters

Query parameters

Name	Type	Required	Description
`page`	string	No	Get responses by page
`pagesize`	string	No	Get responses by pagesize

Returned data

Responses

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

List of features.

Field	Type	Required	Description
`id`	string (uuid)	Yes	Unique identifier for the feature.
`plan_id`	string (uuid)	Yes	Identifier of the plan granting this feature.
`plan`	object	No	The plan granting this feature. Populated only when the association is explicitly loaded.
`name`	string	Yes	Name of the entitled feature.
`quantity`	number (double)	Yes	Quantity of the feature granted by the plan. For a cap-style feature this is the maximum, and the sentinel value 999999999999 denotes unlimited. For a capability-style feature any value greater than 0 grants the capability.
`created_at`	string (date-time)	Yes	Timestamp when the resource was created.
`updated_at`	string (date-time)	Yes	Timestamp when the resource was updated.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/entitlement/plans

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/entitlement/plans

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/entitlement/plans

Parameters

Query parameters

Name	Type	Required	Description
`page`	integer	No	Get responses by page
`pagesize`	integer	No	Get responses by pagesize

Returned data

Responses

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

Field	Type	Required	Description
`cadence`	string	Yes	Billing cadence for the plan (monthly, annually, or none).
`currency`	string	Yes	Currency in which the plan is priced.
`id`	string (uuid)	Yes	Unique identifier for the plan.
`minimumUnits`	integer	Yes	Minimum number of units required for the plan.
`name`	string	Yes	Display name of the plan.
`pricePerUnit`	number	Yes	Price per unit of the plan.
`unit`	string	Yes	Unit of consumption this plan charges against (e.g. user).

Authentication

Bearer JWT

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/entitlement/subscriptions

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/entitlement/subscriptions

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/entitlement/subscriptions

Parameters

Query parameters

Name	Type	Required	Description
`page`	integer	No	Get responses by page
`pagesize`	integer	No	Get responses by pagesize
`order`	string	No	Get ordered responses
`status`	array of string	No	Filter subscriptions by status
`planId`	array of string (uuid)	No	Filter subscriptions by plan UUID. Repeat for multiple values.

Returned data

Responses

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

Paginated list of subscriptions.

Field	Type	Required	Description
`page`	integer	Yes	Current page number of the result set.
`pageSize`	integer	Yes	Number of items per page.
`subscriptions`	array of object	Yes	Subscriptions returned on the current page.
`totalCount`	integer	Yes	Total number of items available.

Subscription Subscriptions POST

/api/entitlement/subscriptions

Update an existing subscription

Updates the subscription named by id in the request body. Despite the historical “upsert” name, this route does not create: a body carrying no id is refused with 400. Subscriptions are minted from the payment processor’s own response, either by the checkout flow (POST /api/entitlement/subscriptions/create) or by the payment-processor webhook, and neither of those reaches this route.

Two independent authorization gates guard this route and they answer differently. The route’s own middleware runs first. It authorizes against the organization named by the route’s orgId path parameter when the route has one, and otherwise against whichever organization the caller currently has selected - and this route has no orgId parameter, so here it is the selected one. A caller who is not a provider admin, an Organization Admin or an Organization Owner of that organization is refused with 403 before the body is read at all. The handler then re-checks against the stored subscription’s own organization, which need not be the selected one: the caller must be a provider admin, or an Organization Admin or Organization Owner of that organization, and a caller who is not receives 404 - the same answer an absent subscription gives, and deliberately indistinguishable from it, so that the route cannot be used to discover which subscription IDs exist.

The fields the payment processor and the webhook own are pinned to the stored row before the write, and any client-supplied value for them is ignored rather than honoured: orgId, billingId, status, startDate and endDate. The writable surface is planId and quantity, and the write replaces both - a body that omits one stores that field’s zero value rather than preserving the stored one, so send both on every call.

The 200 body is a SubscriptionPage carrying the single updated subscription (page 0, pageSize 1, totalCount 1), not a bare subscription object.

Authentication

Bearer JWT

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/entitlement/subscriptions

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/entitlement/subscriptions

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/entitlement/subscriptions

Request body

application/json Required

Body of an update to an existing subscription (POST /api/entitlement/subscriptions).

This is an update payload, never a create payload: id names the subscription to update and the server refuses a body without one. It is also a full replacement of the writable surface rather than a partial merge, which is why planId and quantity are both required - omitting either stores its zero value.

The fields the payment processor and the webhook own - orgId, billingId, status, startDate and endDate - are deliberately absent: the server pins each of them to the stored row and ignores any value supplied for them.

Field	Type	Required	Description
`id`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`planId`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`quantity`	integer	Yes	Number of units subscribed (eg number of users).

Returned data

Responses

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

Paginated list of subscriptions.

Field	Type	Required	Description
`page`	integer	Yes	Current page number of the result set.
`pageSize`	integer	Yes	Number of items per page.
`subscriptions`	array of object	Yes	Subscriptions returned on the current page.
`totalCount`	integer	Yes	Total number of items available.

Authentication

Bearer JWT

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/entitlement/subscriptions/create

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/entitlement/subscriptions/create

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/entitlement/subscriptions/create

Request body

application/json Required

Payload for creating a new subscription through a payment processor.

Field	Type	Required	Description
`couponId`	string	No	Coupon ID to apply.
`email`	string (email)	No	Email of the customer.
`orgId`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`paymentProcessor`	string	No	Payment processor used to complete the subscription checkout.
`planId`	string	No	Price ID from the payment processor.
`userCount`	integer	No	Number of users in the organization.

Returned data

Responses

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

Response body returned after a subscription is created.

Field	Type	Required	Description
`clientSecret`	string	No	Client secret returned by the payment processor for the subscription checkout flow.
`subscriptionId`	string	No	ID of the associated subscription in the payment processor.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/entitlement/subscriptions/organizations/{orgId}/features

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/entitlement/subscriptions/organizations/{orgId}/features

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/entitlement/subscriptions/organizations/{orgId}/features

Parameters

Path parameters

Name	Type	Required	Description
`orgId`	string (uuid)	Yes	The ID of the organization

Returned data

Responses

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

List of features.

Field	Type	Required	Description
`id`	string (uuid)	Yes	Unique identifier for the feature.
`plan_id`	string (uuid)	Yes	Identifier of the plan granting this feature.
`plan`	object	No	The plan granting this feature. Populated only when the association is explicitly loaded.
`name`	string	Yes	Name of the entitled feature.
`quantity`	number (double)	Yes	Quantity of the feature granted by the plan. For a cap-style feature this is the maximum, and the sentinel value 999999999999 denotes unlimited. For a capability-style feature any value greater than 0 grants the capability.
`created_at`	string (date-time)	Yes	Timestamp when the resource was created.
`updated_at`	string (date-time)	Yes	Timestamp when the resource was updated.

Authentication

No authentication required

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/entitlement/subscriptions/webhooks

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/entitlement/subscriptions/webhooks

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/entitlement/subscriptions/webhooks

Request body

application/json Required

Payload for webhook events from payment processors.

Schema: object

Returned data

Responses

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

Subscription Subscriptions GET

/api/entitlement/subscriptions/{subscriptionId}

Read a single subscription

Returns the subscription named by subscriptionId.

Authorization is evaluated against the subscription’s own organization, the same bar the org-scoped list route (GET /api/entitlement/subscriptions) enforces over the same data: the caller must be a provider admin, or an Organization Admin or Organization Owner of that organization. A caller who is not receives 404, deliberately indistinguishable from an absent subscription, so that the route cannot be used to enumerate subscription IDs.

Unlike the update route, this one is registered without any organization-scoped middleware, so it never answers 403: every authorization denial, whether “not yours” or “not there”, is that same 404. A malformed request still answers 400 and an unauthenticated one 401, as below.

A subscriptionId that is not a UUID is refused with 400, and an unauthenticated caller with 401.

The 200 body is a SubscriptionPage carrying the single subscription (page 0, pageSize 1, totalCount 1), not a bare subscription object.

Authentication

Bearer JWT

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/entitlement/subscriptions/{subscriptionId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/entitlement/subscriptions/{subscriptionId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/entitlement/subscriptions/{subscriptionId}

Parameters

Path parameters

Name	Type	Required	Description
`subscriptionId`	string (uuid)	Yes	Subscription ID

Returned data

Responses

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

Paginated list of subscriptions.

Field	Type	Required	Description
`page`	integer	Yes	Current page number of the result set.
`pageSize`	integer	Yes	Number of items per page.
`subscriptions`	array of object	Yes	Subscriptions returned on the current page.
`totalCount`	integer	Yes	Total number of items available.

Authentication

Bearer JWT

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/entitlement/subscriptions/{subscriptionId}/cancel

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/entitlement/subscriptions/{subscriptionId}/cancel

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/entitlement/subscriptions/{subscriptionId}/cancel

Parameters

Path parameters

Name	Type	Required	Description
`subscriptionId`	string (uuid)	Yes	Subscription ID

Returned data

Responses

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

Paginated list of subscriptions.

Field	Type	Required	Description
`page`	integer	Yes	Current page number of the result set.
`pageSize`	integer	Yes	Number of items per page.
`subscriptions`	array of object	Yes	Subscriptions returned on the current page.
`totalCount`	integer	Yes	Total number of items available.

Authentication

Bearer JWT

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/entitlement/subscriptions/{subscriptionId}/upgrade

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/entitlement/subscriptions/{subscriptionId}/upgrade

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/entitlement/subscriptions/{subscriptionId}/upgrade

Parameters

Path parameters

Name	Type	Required	Description
`subscriptionId`	string (uuid)	Yes	Subscription ID

Request body

application/json Required

Payload for upgrading or downgrading a subscription by changing one of its plans.

Field	Type	Required	Description
`newPlanId`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`oldPlanId`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.

Returned data

Responses

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

Subscription entity schema.

Field	Type	Required	Description
`billingId`	string	Yes	Billing ID of the subscription. The ID of the subscription in the external billing system (for example, Stripe).
`createdAt`	string (date-time)	No	Timestamp when the subscription was created.
`deletedAt`	string (date-time)	No	Timestamp when the subscription was soft-deleted, if applicable.
`endDate`	string (date-time)	No	Timestamp when the current subscription period ends.
`id`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`orgId`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`plan`	object	No	Eager-loaded plan associated with this subscription.
`planId`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`quantity`	integer	Yes	Number of units subscribed (eg number of users).
`startDate`	string (date-time)	No	Timestamp when the subscription period started.
`status`	string	Yes	Current status of the subscription (e.g. active, past_due, canceled).
`updatedAt`	string (date-time)	No	Timestamp when the subscription was last updated.

Authentication

Bearer JWT

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/entitlement/subscriptions/{subscriptionId}/upgrade-preview

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/entitlement/subscriptions/{subscriptionId}/upgrade-preview

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/entitlement/subscriptions/{subscriptionId}/upgrade-preview

Parameters

Path parameters

Name	Type	Required	Description
`subscriptionId`	string (uuid)	Yes	Subscription ID

Request body

application/json Required

Payload for upgrading or downgrading a subscription by changing one of its plans.

Field	Type	Required	Description
`newPlanId`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`oldPlanId`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.

Returned data

Responses

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

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/environments

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/environments

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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"
}

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/environments/{environmentId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/environments/{environmentId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/environments/{environmentId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/environments/{environmentId}/connections

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/environments/{environmentId}/connections/{connectionId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/environments/{environmentId}/connections/{connectionId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/events

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/events

Parameters

Query parameters

Name	Type	Required	Description
`cumulative`	boolean	No	When true, return cumulative aggregate counts across all time.

Returned data

Responses

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

Aggregated event counts across categories.

Field	Type	Required	Description
`audit`	integer	No	Count of audit-category events.

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.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/events

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/events

Request body

application/json Required

Payload for creating a new event.

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.

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.
`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.

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.
`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.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/events/delete

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/events/list

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/events/list

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/events/list

Parameters

Query parameters

Name	Type	Required	Description
`page`	integer	No	Get responses by page
`pagesize`	integer	No	Get responses by pagesize
`search`	string	No	Get responses that match search param value
`order`	string	No	Get ordered responses
`filter`	string	No	Get filtered reponses
`scope`	string	No	Which events are returned. `user` (default): only the caller’s own events (unchanged behavior). `organization`: every member’s events in the caller’s session organization. Requires organization administration permission in the session organization; callers without it get 403.

Returned data

Responses

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

Paginated list of events.

Field	Type	Required	Description
`data`	array of object	No	The events returned on the current 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.

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.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/events/status

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/events/summary

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/events/summary

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/events/summary

Parameters

Query parameters

Name	Type	Required	Description
`page`	integer	No	Get responses by page
`pagesize`	integer	No	Get responses by 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 per-user event summaries.

Field	Type	Required	Description
`data`	array of object	No	The event summaries returned on the current page.
`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.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/events/types

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/events/types

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/events/types

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.

Returned data

Responses

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

Field	Type	Required	Description
`action`	string	No	The action of the event type.
`category`	string	No	The category of the event type.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/events/{eventId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/events/{eventId}/status

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/identity/badges

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/badges

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/identity/badges

Parameters

Query parameters

Name	Type	Required	Description
`orgId`	string (uuid)	No	Organization ID to scope the badge listing to.

Returned data

Responses

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

Map of badges available in an organization, keyed by badge label.

Field	Type	Required	Description
`badges`	object	No	Available badges, keyed by badge label.

Token GET

/api/identity/native/authorize

Authorize native client sign-in

Browser-facing step of the native client sign-in flow (RFC 8252 loopback redirect with RFC 7636 PKCE). Requires the session cookie of a signed-in user and the Create Token permission. Validates the request. When the request names the client application (client) and its version (clientVersion) and that version is below the provider minimum, it renders the update page with status 426 and issues nothing. Otherwise it stores a single-use authorization code that expires after 60 seconds, bound to the user, the client name and the PKCE code challenge, and redirects the browser to http://127.0.0.1:{port}/callback with code and state query parameters. Only the 127.0.0.1 loopback IP literal is ever used; no token or cookie is placed in the redirect; no consent page is shown.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/identity/native/authorize

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/native/authorize

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/identity/native/authorize

Parameters

Query parameters

Name	Type	Required	Description
`clientName`	string	Yes	Display name of the native client asking to sign in. Used as the name and purpose of the minted token.
`client`	string	No	Identifier of the client application, as in the capabilities `client` parameter. Selects the minimum version checked against `clientVersion`.
`clientVersion`	string	No	Version of the client application, for example `v1.25.0`.
`port`	integer	Yes	Port on 127.0.0.1 where the native client listens for the callback.
`codeChallenge`	string	Yes	PKCE code challenge, BASE64URL(SHA256(codeVerifier)) without padding.
`codeChallengeMethod`	string	Yes	PKCE challenge method. Only S256 is accepted.
`state`	string	Yes	Opaque value from the native client, returned unchanged on the callback.

Returned data

Responses

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

Token POST

/api/identity/native/token

Exchange native client authorization code

Redeems a single-use authorization code from the native client sign-in flow. The caller proves possession of the PKCE code verifier (BASE64URL(SHA256(codeVerifier)) must equal the stored S256 challenge). The code is consumed on the first redemption attempt, whether or not the verifier matches. On success an API token is minted for the user with name and purpose set to the client name. This call is authenticated by the code and verifier, not by a session.

Authentication

No authentication required

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/identity/native/token

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/native/token

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/identity/native/token

Request body

application/json Required

Redeems a native client authorization code with its PKCE verifier.

Field	Type	Required	Description
`code`	string	Yes	Single-use authorization code from the loopback callback.
`codeVerifier`	string	Yes	PKCE code verifier (RFC 7636, 43 to 128 unreserved characters).

Returned data

Responses

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

Represents a user-owned API token or OAuth session.

Field	Type	Required	Description
`id`	string (uuid)	Yes	Unique identifier for the token.
`owner`	string (uuid)	Yes	UUID of the user who owns the token.
`provider`	string	Yes	Authentication provider associated with the token.
`accessToken`	string	Yes	Access token value.
`refreshToken`	string	No	Refresh token value when applicable.
`name`	string	Yes	Human-readable token name.
`purpose`	string	Yes	Purpose for which the token was created.
`isOauth`	boolean	Yes	Whether this entry represents an OAuth session.
`createdAt`	string (date-time)	Yes	Timestamp when the token was created.
`updatedAt`	string (date-time)	Yes	Timestamp when the token was last updated.

Authentication

Bearer JWT

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/orgs

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Authentication

Bearer JWT

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/orgs

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

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

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Authentication

Bearer JWT

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/orgs/{orgId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Authentication

Bearer JWT

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/orgs/{orgId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Authentication

Bearer JWT

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/orgs/{orgId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Organization Organizations 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

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/orgs/{orgId}/children

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Organization Organizations 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

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/orgs/{orgId}/children

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Authentication

Bearer JWT

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/orgs/{orgId}/preferences

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Organization Organizations 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

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/orgs/{orgId}/preferences

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/orgs/{orgId}/roles

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/identity/orgs/{orgId}/roles

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
`all`	boolean	No	Get all possible entries
`selector`	string	No	Role grouping selector such as provider, organization, or team.
`teamId`	string (uuid)	No	Team ID used when selector is team.

Returned data

Responses

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

A paginated list of roles.

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

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/orgs/{orgId}/roles

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/identity/orgs/{orgId}/roles

Parameters

Path parameters

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

Request body

application/json Required

Payload for upserting a role. Includes only client-settable fields.

Field	Type	Required	Description
`description`	string	Yes	Human-readable description of the role.
`id`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`roleName`	string	Yes	Unique name of the role.

Returned data

Responses

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

Role definition

Field	Type	Required	Description
`id`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`roleName`	string	Yes	Unique name of the role.
`description`	string	Yes	Human-readable description of the role.
`createdAt`	string (date-time)	No	Timestamp when the role was created.
`updatedAt`	string (date-time)	No	Timestamp when the role was last updated.
`deletedAt`	string (date-time)	No	Timestamp when the role was soft-deleted, if applicable.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/orgs/{orgId}/roles

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/identity/orgs/{orgId}/roles

Parameters

Path parameters

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

Request body

application/json Required

Field	Type	Required	Description
`id`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`userId`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`username`	string	No	The username of the user.
`email`	string (email)	No	Email address of the user.
`firstName`	string	No	First name of the user.
`lastName`	string	No	Last name of the user.
`status`	string	No	Current status of the user.
`roleNames`	array of string	No	Role names currently or newly assigned to the user.
`createdAt`	string (date-time)	No	Timestamp when the user was created.
`updatedAt`	string (date-time)	No	Timestamp when the user was last updated.
`deletedAt`	string (date-time)	No	Timestamp when the user was soft-deleted, if applicable.

Returned data

Responses

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

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/identity/orgs/{orgId}/roles/{roleId}/keychains

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/orgs/{orgId}/roles/{roleId}/keychains

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/identity/orgs/{orgId}/roles/{roleId}/keychains

Parameters

Path parameters

Name	Type	Required	Description
`orgId`	string (uuid)	Yes	Organization ID
`roleId`	string (uuid)	Yes	Role 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

Returned data

Responses

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

Field	Type	Required	Description
`page`	integer	Yes	No description provided.
`page_size`	integer	Yes	No description provided.
`total_count`	integer	Yes	No description provided.
`keychains`	array of object	Yes	The keychains of the keychainpage.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/identity/orgs/{orgId}/roles/{roleId}/keychains/{keychainId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/orgs/{orgId}/roles/{roleId}/keychains/{keychainId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/identity/orgs/{orgId}/roles/{roleId}/keychains/{keychainId}

Parameters

Path parameters

Name	Type	Required	Description
`orgId`	string (uuid)	Yes	Organization ID
`roleId`	string (uuid)	Yes	Role ID
`keychainId`	string (uuid)	Yes	Keychain ID

Returned data

Responses

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

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/identity/orgs/{orgId}/roles/{roleId}/keychains/{keychainId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/orgs/{orgId}/roles/{roleId}/keychains/{keychainId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/identity/orgs/{orgId}/roles/{roleId}/keychains/{keychainId}

Parameters

Path parameters

Name	Type	Required	Description
`orgId`	string (uuid)	Yes	Organization ID
`roleId`	string (uuid)	Yes	Role ID
`keychainId`	string (uuid)	Yes	Keychain ID

Returned data

Responses

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

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/orgs/{orgId}/teams

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/identity/orgs/{orgId}/teams

Parameters

Path parameters

Name	Type	Required	Description
`orgId`	string (uuid)	Yes	Organization 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.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/orgs/{orgId}/teams

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/identity/orgs/{orgId}/teams

Parameters

Path parameters

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

Request body

application/json Required

Body for creating a team

Payload for creating a new team

Field	Type	Required	Description
`description`	string	No	A detailed description of the team’s purpose and responsibilities.
`metadata`	object	No	Additional client-supplied metadata for the team.
`name`	string	Yes	Team name. Provide a meaningful name that represents this team.
`notifyTeamUpdate`	boolean	No	Whether to notify team members when the team is created or updated.

Returned data

Responses

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

A Team is a group of one or more users. Teams are often used as a grouping mechanism for assigning permissions, whether in the context of an organization, a workspace, or some other domain within Meshery. Learn more at https://docs.meshery.io/concepts/logical/teams

Field	Type	Required	Description
`id`	string (uuid)	Yes	Team ID
`name`	string	Yes	Team name
`description`	string	No	Team description
`owner`	string (uuid)	No	User ID of the owner of the team
`metadata`	object	No	Additional metadata for the team
`createdAt`	string (date-time)	Yes	Timestamp when the team was created.
`updatedAt`	string (date-time)	Yes	Timestamp when the team was last updated.
`deletedAt`	string (date-time)	No	Timestamp when the team was soft-deleted, if applicable.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/orgs/{orgId}/teams/{teamId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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

Returned data

Responses

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

A Team is a group of one or more users. Teams are often used as a grouping mechanism for assigning permissions, whether in the context of an organization, a workspace, or some other domain within Meshery. Learn more at https://docs.meshery.io/concepts/logical/teams

Field	Type	Required	Description
`id`	string (uuid)	Yes	Team ID
`name`	string	Yes	Team name
`description`	string	No	Team description
`owner`	string (uuid)	No	User ID of the owner of the team
`metadata`	object	No	Additional metadata for the team
`createdAt`	string (date-time)	Yes	Timestamp when the team was created.
`updatedAt`	string (date-time)	Yes	Timestamp when the team was last updated.
`deletedAt`	string (date-time)	No	Timestamp when the team was soft-deleted, if applicable.

Authentication

Bearer JWT

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/orgs/{orgId}/teams/{teamId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/orgs/{orgId}/teams/{teamId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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 Required

Body for updating a team

Payload for updating an existing team

Field	Type	Required	Description
`description`	string	No	Updated team description
`name`	string	No	Updated team name

Returned data

Responses

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

A Team is a group of one or more users. Teams are often used as a grouping mechanism for assigning permissions, whether in the context of an organization, a workspace, or some other domain within Meshery. Learn more at https://docs.meshery.io/concepts/logical/teams

Field	Type	Required	Description
`id`	string (uuid)	Yes	Team ID
`name`	string	Yes	Team name
`description`	string	No	Team description
`owner`	string (uuid)	No	User ID of the owner of the team
`metadata`	object	No	Additional metadata for the team
`createdAt`	string (date-time)	Yes	Timestamp when the team was created.
`updatedAt`	string (date-time)	Yes	Timestamp when the team was last updated.
`deletedAt`	string (date-time)	No	Timestamp when the team was soft-deleted, if applicable.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/orgs/{orgId}/teams/{teamId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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

Returned data

Responses

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

Authentication

Bearer JWT

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/orgs/{orgId}/teams/{teamId}/remove

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/orgs/{orgId}/teams/{teamId}/users

Meshery Cloud development server URL (controlled via PORT environment variable)

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

Parameters

Path parameters

Name	Type	Required	Description
`orgId`	string (uuid)	Yes	Organization ID
`teamId`	string (uuid)	Yes	Team 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.

Returned data

Responses

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

Paginated list of team members.

Field	Type	Required	Description
`data`	array of object	No	The data of the teammemberspage.
`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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/identity/orgs/{orgId}/teams/{teamId}/users/{userId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/orgs/{orgId}/teams/{teamId}/users/{userId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/identity/orgs/{orgId}/teams/{teamId}/users/{userId}

Parameters

Path parameters

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

Returned data

Responses

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

Join row between users and teams. The schema name is UsersTeamsMapping (rather than TeamsUsersMapping) so that pop’s tableize default produces the live DB table name users_teams_mappings, eliminating the need for an explicit TableName() helper on the generated Go struct.

Field	Type	Required	Description
`createdAt`	string (date-time)	No	Timestamp when the mapping was created.
`deletedAt`	string (date-time)	No	Timestamp when the mapping was soft-deleted, if applicable.
`id`	string (uuid)	No	No description provided.
`roleId`	string (uuid)	No	Optional role assigned to this team membership. Nullable because a membership may exist without an explicit role (e.g., team-admin assignments are stamped on insert; non-owner adds may leave `role_id` null until a role is assigned). References `roles.id`.
`teamId`	string (uuid)	No	Team ID
`updatedAt`	string (date-time)	No	Timestamp when the mapping was last updated.
`userId`	string (uuid)	No	User ID

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/identity/orgs/{orgId}/teams/{teamId}/users/{userId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/orgs/{orgId}/teams/{teamId}/users/{userId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/identity/orgs/{orgId}/teams/{teamId}/users/{userId}

Parameters

Path parameters

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

Returned data

Responses

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

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/orgs/{orgId}/users

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/orgs/{orgId}/users/invite

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/identity/orgs/{orgId}/users/invite

Parameters

Path parameters

Name	Type	Required	Description
`orgId`	string (uuid)	Yes	The ID of the organization.

Request body

application/json Required

Schema: object

Returned data

Responses

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

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/orgs/{orgId}/users/keys

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/orgs/{orgId}/users/search

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/identity/orgs/{orgId}/users/search

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`.
`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.

Authentication

Bearer JWT

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/orgs/{orgId}/users/{userId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Authentication

Bearer JWT

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/orgs/{orgId}/users/{userId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/identity/roles

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/roles

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/identity/roles

Request body

application/json Required

Request body for assigning a role to a user.

Field	Type	Required	Description
`email`	string (email)	Yes	Email of the user to assign roles to.
`roleNames`	array of string	Yes	List of role names to assign.

Returned data

Responses

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

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/identity/roles/{roleId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/roles/{roleId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/identity/roles/{roleId}

Parameters

Path parameters

Name	Type	Required	Description
`roleId`	string (uuid)	Yes	Role ID

Returned data

Responses

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

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/identity/teams/{teamId}/users

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/teams/{teamId}/users

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/identity/teams/{teamId}/users

Parameters

Path parameters

Name	Type	Required	Description
`teamId`	string (uuid)	Yes	Team 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.

Returned data

Responses

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

Paginated list of team members.

Field	Type	Required	Description
`data`	array of object	No	The data of the teammemberspage.
`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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/identity/tokens

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/tokens

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/identity/tokens

Parameters

Query parameters

Name	Type	Required	Description
`isOauth`	boolean	No	Whether to retrieve OAuth-backed sessions instead of API tokens.
`purpose`	string	No	Token purpose. Tokens are minted with this purpose on generate. On list, only tokens whose purpose is exactly this value (case-sensitive, not a substring match) are returned; omit it to list every purpose.
`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 tokens.

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

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/identity/tokens

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/tokens

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/identity/tokens

Parameters

Query parameters

Name	Type	Required	Description
`name`	string	Yes	Name of the token.
`purpose`	string	No	Token purpose. Tokens are minted with this purpose on generate. On list, only tokens whose purpose is exactly this value (case-sensitive, not a substring match) are returned; omit it to list every purpose.

Returned data

Responses

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

A paginated list of tokens.

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

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/identity/tokens

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/tokens

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/identity/tokens

Parameters

Query parameters

Name	Type	Required	Description
`tokenId`	string (uuid)	Yes	ID of the token to delete.

Returned data

Responses

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

A paginated list of tokens.

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

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/identity/tokens/infinite

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/tokens/infinite

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/identity/tokens/infinite

Parameters

Query parameters

Name	Type	Required	Description
`userId`	string (uuid)	Yes	UUID of the user to issue the indefinite token for.
`provider`	string	Yes	Authentication provider to associate with the indefinite token.

Returned data

Responses

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

A paginated list of tokens.

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

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/identity/tokens/{tokenId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/tokens/{tokenId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/identity/tokens/{tokenId}

Parameters

Path parameters

Name	Type	Required	Description
`tokenId`	string (uuid)	Yes	Token ID

Returned data

Responses

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

Represents a user-owned API token or OAuth session.

Field	Type	Required	Description
`id`	string (uuid)	Yes	Unique identifier for the token.
`owner`	string (uuid)	Yes	UUID of the user who owns the token.
`provider`	string	Yes	Authentication provider associated with the token.
`accessToken`	string	Yes	Access token value.
`refreshToken`	string	No	Refresh token value when applicable.
`name`	string	Yes	Human-readable token name.
`purpose`	string	Yes	Purpose for which the token was created.
`isOauth`	boolean	Yes	Whether this entry represents an OAuth session.
`createdAt`	string (date-time)	Yes	Timestamp when the token was created.
`updatedAt`	string (date-time)	Yes	Timestamp when the token was last updated.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/identity/users/anonymous

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/users/anonymous

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/identity/users/anonymous

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.

Response returned after minting an anonymous user session: the session access token, the ID of the synthetic anonymous user, and the capability document for the session.

Field	Type	Required	Description
`accessToken`	string	Yes	JWT access token for the anonymous session.
`capability`	object	No	Capability document for the anonymous session. Untyped pending the provider-capabilities schema tracked separately in the identifier-uniformity program.
`userId`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/identity/users/badges

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/users/badges

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/identity/users/badges

Request body

application/json Required

Payload for assigning a set of badges to a user.

Field	Type	Required	Description
`badges`	array of string	Yes	Labels of the badges being assigned to the user.
`notify`	boolean	No	When true, send a notification to the user about the new badge assignment.
`userId`	string (uuid)	Yes	ID of the user to receive the badges.

Returned data

Responses

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

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/identity/users/notify/comment

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/users/notify/comment

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/identity/users/notify/comment

Request body

application/json Required

Request body for notifying users about a design comment: the users mentioned in the comment, the thread participants, and the comment messages to include in the notification email.

Field	Type	Required	Description
`designId`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`mentionUsers`	array of string (uuid)	No	IDs of the users explicitly mentioned in the comment.
`messages`	array of object	No	The comment messages to include in the notification email.
`participants`	array of string (uuid)	No	IDs of the users participating in the comment thread.
`usersOptedOutOfNotifications`	array of string (uuid)	No	IDs of the users who opted out of mention notifications.

Returned data

Responses

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

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/identity/users/preferences

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/users/preferences

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/identity/users/preferences

Request body

application/json Required

The client-settable fields of Preference for updateUserPreferences. Every field is optional: the server merges the ones present onto the stored preferences and keeps the rest. updatedAt is server-recorded and is not settable.

Field	Type	Required	Description
`anonymousPerfResults`	boolean	No	The anonymous perf results of the preference.
`anonymousUsageStats`	boolean	No	The anonymous usage stats of the preference.
`dashboardPreferences`	object	No	The dashboard preferences of the preference.
`grafana`	object	No	No description provided.
`loadTestPrefs`	object	No	No description provided.
`meshAdapters`	array of object	No	The mesh adapters of the preference.
`prometheus`	object	No	No description provided.
`remoteProviderPreferences`	object	No	The remote provider preferences of the preference.
`selectedOrganizationId`	string (uuid)	No	ID of the organization to make the session’s selected organization.
`selectedWorkspaceForOrganizations`	object	No	The selected workspace for organizations of the preference.
`usersExtensionPreferences`	object	No	The users extension preferences of the preference.

Returned data

Responses

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

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/users/profile

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/identity/users/profile/details

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/users/profile/details

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/identity/users/profile/details

Returned data

Responses

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

Aggregate counts shown on the current user’s profile overview.

Field	Type	Required	Description
`k8sCount`	integer	Yes	Number of Kubernetes contexts owned by the user.
`patternCount`	integer	Yes	Number of designs owned by the user.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/users/profile/{id}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/identity/users/request

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/users/request

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/identity/users/request

Parameters

Query parameters

Name	Type	Required	Description
`page`	integer	No	Get responses by page
`pagesize`	integer	No	Get responses by 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 signup requests.

Field	Type	Required	Description
`data`	array of object	No	Signup requests returned on the current page.
`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.

Authentication

No authentication required

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/identity/users/request

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/users/request

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/identity/users/request

Request body

application/json Required

Schema: object

Returned data

Responses

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

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/identity/users/request/approve

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/users/request/approve

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/identity/users/request/approve

Parameters

Query parameters

Name	Type	Required	Description
`id`	string (uuid)	Yes	The ID of the signup request being approved or denied.
`firstName`	string	No	First name of the requester.
`lastName`	string	No	Last name of the requester.
`email`	string (email)	No	Email address of the requester.
`occupation`	string	No	Occupation of the requester.
`organization`	string	No	Organization of the requester.
`role`	string	No	Requested role.
`formType`	string	No	The signup form variant the request originated from.
`status`	string	No	Status to record on the signup request.
`taskId`	string	No	Tracking task identifier associated with the request.
`taskLink`	string	No	Tracking task link associated with the request.

Returned data

Responses

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

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/identity/users/request/deny

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/users/request/deny

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/identity/users/request/deny

Parameters

Query parameters

Name	Type	Required	Description
`id`	string (uuid)	Yes	The ID of the signup request being approved or denied.
`firstName`	string	No	First name of the requester.
`lastName`	string	No	Last name of the requester.
`email`	string (email)	No	Email address of the requester.
`occupation`	string	No	Occupation of the requester.
`organization`	string	No	Organization of the requester.
`role`	string	No	Requested role.
`formType`	string	No	The signup form variant the request originated from.
`status`	string	No	Status to record on the signup request.
`taskId`	string	No	Tracking task identifier associated with the request.
`taskLink`	string	No	Tracking task link associated with the request.

Returned data

Responses

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

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/identity/users/request/notification

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/users/request/notification

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/identity/users/request/notification

Returned data

Responses

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

Notification about the most recent signup request awaiting moderator action, served by getSignupRequestNotification.

Field	Type	Required	Description
`preProcessed`	boolean	Yes	Whether the signup request was automatically processed before moderator review.
`signupData`	object	Yes	The signup request the notification refers to.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/users/search

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

User DELETE

/api/identity/users/self

Delete the caller's own account

Soft-deletes the caller’s Layer5 Cloud user record and hard-deletes the backing identity. When deleteOrganization is true, the caller’s organization is hard-deleted in the same operation, subject to server-side re-validation: the organization must not be the shared Layer5 provider organization, must not have an active paid subscription, and organizationNameConfirmation must match the stored organization name. When the organization shares resources into other surviving organizations, confirmSharedResourceDestruction must also be true. Inputs are passed as query parameters because DELETE request bodies are unreliable across the extension proxy and intermediate HTTP clients.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/identity/users/self

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/users/self

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/identity/users/self

Parameters

Query parameters

Name	Type	Required	Description
`deleteOrganization`	boolean	No	When true, hard-delete the caller’s organization along with the account. Defaults to false (delete only the account).
`organizationId`	string (uuid)	No	Identifier of the organization to hard-delete. Required by the server when deleteOrganization is true.
`organizationNameConfirmation`	string	No	User-typed organization name. The server re-validates this against the stored organization name when deleteOrganization is true and rejects the request on mismatch.
`confirmSharedResourceDestruction`	boolean	No	Explicit acknowledgement that resources shared into other surviving organizations will be destroyed. Required by the server when the organization’s crossTenantSharedResourceCount is greater than zero.

Returned data

Responses

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

User GET

/api/identity/users/self/account-deletion-eligibility

Get account deletion eligibility

Pre-check evaluated before an account self-deletion is confirmed. Reports whether deleting the caller’s account would also require or permit hard-deleting their organization, whether that organization is the shared Layer5 provider organization or carries an active paid subscription, how many of its resources are also shared into other surviving organizations, and the per-resource blast radius of the deletion.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/identity/users/self/account-deletion-eligibility

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/users/self/account-deletion-eligibility

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/identity/users/self/account-deletion-eligibility

Parameters

Query parameters

Name	Type	Required	Description
`organizationId`	string (uuid)	No	Organization to evaluate for deletion alongside the account. When omitted, the caller’s currently selected organization is evaluated.

Returned data

Responses

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

Pre-check result returned before an account self-deletion is confirmed. Describes whether deleting the caller’s account would also require or permit hard-deleting their organization and quantifies the blast radius. All fields are always present so the client can render the confirmation state deterministically.

Field	Type	Required	Description
`crossTenantSharedResourceCount`	integer	Yes	Count of resources reachable from this organization that are also shared into a different, surviving organization; destroying them affects other tenants. When greater than zero the client must set confirmSharedResourceDestruction to proceed.
`hasActivePaidSubscription`	boolean	Yes	True when the organization has an active paid (non-“Personal”/free) plan subscription that must be cancelled before the organization can be hard-deleted.
`impact`	object	Yes	Per-resource counts of the objects that would be destroyed when an organization is hard-deleted alongside the account.
`isProviderOrg`	boolean	Yes	True when this is the shared Layer5 provider organization, which is never deletable regardless of membership.
`isSoleActiveMember`	boolean	Yes	True when the caller is the only active member of the organization, so deleting their account would leave the organization without any active members.
`organizationId`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`organizationName`	string	Yes	Human-readable name of the organization evaluated for deletion. The client echoes this value back as organizationNameConfirmation when requesting deletion.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/users/{userId}/emails

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

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

Authentication

No authentication required

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/identity/users/{userId}/profile/activity

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/identity/users/{userId}/profile/activity

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/identity/users/{userId}/profile/activity

Parameters

Path parameters

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

Query parameters

Name	Type	Required	Description
`page`	integer	No	Zero-based page index of the activity feed.
`pageSize`	integer	No	Number of activity entries per page.
`pagesize`	integer	No	Deprecated lowercase alias of pageSize, kept while existing clients migrate to the canonical camelCase parameter.
`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 recent-activity feed for a user’s public profile.

Field	Type	Required	Description
`activities`	array of object	No	The activity entries on the current page.
`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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/integrations/connections

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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

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

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/integrations/connections

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

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.

Connection API Connections GET

/api/integrations/connections/desktop

List the organization's desktop connections

Returns every live desktop connection in the session organization, whoever registered it, as a summary: id, name, kind, owner, status, organizationId and lastSeenAt only. Any live member of the organization may read it, so members can see which computers share its work; a guest session cannot. Servers must never include the connection’s credential, metadata (beyond lastSeenAt), URL or description here: the full connection stays readable only by its owner through getConnections. status follows the heartbeat rule of recordConnectionHeartbeat (a desktop connection silent for 3 minutes reads disconnected). A caller who is not a live member of the session organization receives 404.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/integrations/connections/desktop

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/integrations/connections/desktop

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/integrations/connections/desktop

Parameters

Query parameters

Name	Type	Required	Description
`page`	integer	No	Page number
`pageSize`	integer	No	Number of items per page
`owner`	string (uuid)	No	Only connections registered by this user.

Returned data

Responses

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

Page of connection summaries.

Field	Type	Required	Description
`connections`	array of object	Yes	Connection summaries 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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/integrations/connections/desktop/{installationId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/integrations/connections/desktop/{installationId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/integrations/connections/desktop/{installationId}

Parameters

Path parameters

Name	Type	Required	Description
`installationId`	string	Yes	Installation identifier from `metadata.installationId`.

Returned data

Responses

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

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/integrations/connections/kubernetes/{connectionId}/context

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/integrations/connections/meshery/{mesheryServerId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/integrations/connections/{connectionId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

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

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/integrations/connections/{connectionId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/integrations/connections/{connectionId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Connection API Connections POST

/api/integrations/connections/{connectionId}/heartbeat

Record a connection heartbeat

Mark the caller’s connection as alive. Servers implementing this contract must set metadata.lastSeenAt to the current time and, when the connection is disconnected, set its status back to connected. Servers must report a connection whose metadata.lastSeenAt is older than 3 minutes as disconnected until its next heartbeat. The request has no body, so a heartbeat cannot change anything else about the connection. When the connection’s metadata.clientName and metadata.appVersion, as stored by the latest registration (which every connect makes before its first heartbeat), fall below the server’s minimum version for that client, servers must answer 426 with a ClientUpgradeRequiredError body and set the connection to maintenance instead of recording the heartbeat.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/integrations/connections/{connectionId}/heartbeat

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/integrations/connections/{connectionId}/heartbeat

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.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/integrations/credentials

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/integrations/credentials

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/integrations/credentials

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/integrations/credentials

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/integrations/credentials/{credentialId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/integrations/github

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/integrations/github

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/integrations/github

Parameters

Query parameters

Name	Type	Required	Description
`id`	string	Yes	GitHub App installation id; must be one of the caller’s verified installations.
`page`	integer	No	Get responses by page

Returned data

Responses

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

One page of GitHub’s GET /installation/repositories answer, passed through as GitHub returns it (total_count, repositories).

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.

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.

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.

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.

GitHub GET

/api/integrations/github/authorize

Start a trip to GitHub (browser navigation)

Browser navigation, not a data call. Issues a single-use state bound to the signed-in user (consumed once, five-minute lifetime) and redirects to GitHub carrying it: flow=install to the GitHub App’s installation page (derived from the App’s own html_url), flow=authorize to GitHub’s user-authorization page for the App. The UI never links to GitHub directly. Failures redirect to /connect/github/new/<userId>?githubError=<reason>, as the callback does.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/integrations/github/authorize

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/integrations/github/authorize

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/integrations/github/authorize

Parameters

Query parameters

Name	Type	Required	Description
`flow`	string	Yes	`install` sends the browser to the GitHub App’s installation page; `authorize` sends it to GitHub’s user-authorization page for the App.

Returned data

Responses

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

Design Github GET

/api/integrations/github/branches/{connectionId}

List a repository's branches

Lists the branches of one repository reachable through the caller’s GitHub App connection, with the repository’s default branch, so a client can offer the refs a design’s source can track. Branch order is GitHub’s. connectionId must name the caller’s own live GitHub connection (404 otherwise, with the same body as “no such connection”). 403 means the repository is not reachable through one of the caller’s verified GitHub App installations - the installations GitHub lists for the caller’s own GitHub account when they authorize the App. The refusal is deliberately uniform: the App not being installed on the repository’s account and its being installed there for someone else answer the same body, so the route does not reveal where the App is installed. A distinct 403 whose MeshKit error asks for re-authorization means the caller’s GitHub connection predates verification; re-authorize it (see startGithubAuthorization) before use; 502 means GitHub could not be reached or rejected the request.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/integrations/github/branches/{connectionId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/integrations/github/branches/{connectionId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/integrations/github/branches/{connectionId}

Parameters

Path parameters

Name	Type	Required	Description
`connectionId`	string (uuid)	Yes	ID of a GitHub App connection.

Query parameters

Name	Type	Required	Description
`repository`	string	Yes	Repository as `<owner>/<repo>` (case-insensitive).
`page`	integer	No	Get responses by page
`pageSize`	integer	No	Number of items per page (canonical camelCase form).

Returned data

Responses

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

A page of a repository’s branches. GitHub does not report a total, so the page says whether another follows instead of carrying a count.

Field	Type	Required	Description
`branches`	array of object	Yes	No description provided.
`defaultBranch`	string	Yes	The repository’s default branch.
`hasMore`	boolean	Yes	True when another page of branches follows.
`page`	integer	Yes	Zero-based page index served.
`pageSize`	integer	Yes	Page size served.

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.

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.

GitHub GET

/api/integrations/github/callback

The GitHub App's callback (browser navigation)

Browser navigation, not a data call. GitHub returns the browser here with the state issued by startGithubAuthorization and a one-time code. A missing, expired, reused or foreign state is refused before the code is exchanged or any connection is touched (githubError=authorization-stale). The server then exchanges the code for a user-to-server token, lists the installations of the App the authorizing GitHub account can access (GitHub’s GET /user/installations) and stores exactly that set on the caller’s GitHub connection - creating it, or updating it in place. An installation_id not in that set is never stored, and a result of zero installations never deletes or replaces an existing connection. Always answers a 302: to /connect/github/verify?githubLogin=true&id=<installation>[&setup_action=update] on success, else to /connect/github/new/<userId>?githubError=<reason>, reason one of authorization-failed, authorization-stale, authorization-unavailable, connection-failed, installation-not-verified, no-installations. The installation_id and setup_action query parameter names are GitHub’s and are kept as GitHub sends them.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/integrations/github/callback

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/integrations/github/callback

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/integrations/github/callback

Parameters

Query parameters

Name	Type	Required	Description
`state`	string	Yes	The single-use state `startGithubAuthorization` issued.
`code`	string	No	GitHub’s one-time authorization code.
`installation_id`	string	No	The installation GitHub names on return (GitHub’s parameter name). It is stored only when it is one of the installations GitHub lists for the authorizing account.
`setup_action`	string	No	GitHub’s setup action (GitHub’s parameter name).

Returned data

Responses

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

Design Designs GET

/api/integrations/github/designs/{connectionId}

List designs imported from GitHub

Returns the designs owned by the GitHub connection’s owner whose location.type is github - every design imported (or refreshed) from GitHub - newest first. The inventory is owner-wide, not scoped to the connection: Meshery Cloud keeps one GitHub App connection per user, and the connection only authorizes the read. Use repository to narrow it. location carries host (github.com//), path and branch (empty = the repository’s default branch). patternFile and sourceContent are not projected. Only the connection’s owner may list it, as only a design’s owner may refresh it: a caller who does not own the connection gets 404 regardless of any all-organizations scope, with the same body as “no such connection”, so private designs are never listed to another user.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/integrations/github/designs/{connectionId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/integrations/github/designs/{connectionId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/integrations/github/designs/{connectionId}

Parameters

Path parameters

Name	Type	Required	Description
`connectionId`	string (uuid)	Yes	ID of a GitHub App connection.

Query parameters

Name	Type	Required	Description
`repository`	string	No	Restrict to one repository, as `<owner>/<repo>` (case-insensitive).
`page`	integer	No	Get responses by page
`pageSize`	integer	No	Number of items per page (canonical camelCase form).

Returned data

Responses

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

Paginated collection of designs.

Field	Type	Required	Description
`page`	integer	No	Current page number of the result set.
`pageSize`	integer	No	Number of items per page.
`patterns`	array of object	No	Designs included on this page of results.
`resultType`	string	No	Optional discriminator describing which collection the page represents.
`totalCount`	integer	No	Total number of items available.

Design Designs POST

/api/integrations/github/import/{connectionId}

Import files from a GitHub repository as designs

Imports the selected files (a selected directory is walked recursively) from one repository reachable through the caller’s GitHub App connection. Matching is idempotent: a file whose (owner, location.type, location.host, location.path, location.branch) already identifies one of the caller’s designs is handled per onExisting. connectionId must name the caller’s own live GitHub connection (404 otherwise). 403 means the repository is not reachable through one of the caller’s verified GitHub App installations - the installations GitHub lists for the caller’s own GitHub account when they authorize the App. The refusal is deliberately uniform: the App not being installed on the repository’s account and its being installed there for someone else answer the same body, so the route does not reveal where the App is installed. A distinct 403 whose MeshKit error asks for re-authorization means the caller’s GitHub connection predates verification; re-authorize it (see startGithubAuthorization) before use; 502 means GitHub could not be reached or rejected the request. Each imported or updated design records the commit its file was read at in location.commitSha.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/integrations/github/import/{connectionId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/integrations/github/import/{connectionId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/integrations/github/import/{connectionId}

Parameters

Path parameters

Name	Type	Required	Description
`connectionId`	string (uuid)	Yes	ID of a GitHub App connection.

Request body

application/json Required

Files to import from one repository and how to treat files that were imported before.

Field	Type	Required	Description
`name`	string	Yes	Repository as `<owner>/<repo>`.
`onExisting`	string	No	What to do with a selected file that already identifies one of the caller’s designs. `skip` (the default, “import new only”) leaves it untouched and reports it in `skippedPaths`, so a request that omits `onExisting` never overwrites an existing design; `update` refreshes that design in place under the same ID (idempotent import); `new` imports it again as an additional design.
`paths`	array of object	Yes	Selected tree items, as served by `GET /api/integrations/github/scan`. The server reads only `type` and `entry.path`; the remaining scan fields are accepted and ignored.

Returned data

Responses

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

Outcome of a GitHub repository import.

Field	Type	Required	Description
`errors`	array of object	No	One Error-severity import event per selected path that failed.
`patterns`	array of object	No	Designs created or updated by this import, with `sourceContent`, `patternFile` and `catalogData` omitted.
`skippedPaths`	array of string	No	Repository-relative paths left untouched because `onExisting` was `skip` and a design already imports them.
`updatedIds`	array of string (uuid)	No	IDs (all also present in `patterns`) of designs updated in place rather than created.

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.

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.

GitHub POST

/api/integrations/github/install

Commit the Kanvas workflow into repositories

Commits the Kanvas workflow into each requested repository. Every well-formed repository is authorized before anything is written: one repository the caller cannot reach through their verified GitHub App installations refuses the whole request with the uniform 403, and nothing is committed anywhere. A malformed repository identifier is reported per repository (code: 400) and never reaches GitHub. The id query parameter is accepted for compatibility and is not consulted.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/integrations/github/install

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/integrations/github/install

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/integrations/github/install

Parameters

Query parameters

Name	Type	Required	Description
`id`	string	No	Ignored. Accepted for compatibility; the server resolves the installation itself.

Request body

application/json Required

The repositories to commit the Kanvas workflow into.

Field	Type	Required	Description
`repositories`	array of string	Yes	Repositories as `<owner>/<repo>`.

Returned data

Responses

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

One single-key entry per requested repository, keyed by <owner>/<repo>.

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.

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.

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.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/integrations/github/scan

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/integrations/github/scan

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/integrations/github/scan

Parameters

Query parameters

Name	Type	Required	Description
`name`	string	Yes	Repository as `<owner>/<repo>`.
`ref`	string	No	Branch or tag to scan. Empty or omitted scans the repository’s default branch. A ref that names no commit answers 409.
`page`	integer	No	Get responses by page
`pageSize`	integer	No	Number of items per page.

Returned data

Responses

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

One page of a repository’s file tree.

Field	Type	Required	Description
`children`	array of object	No	The items under a directory, each shaped as a `GithubRepositoryTreeItem`.
`entry`	object	No	GitHub’s tree entry for the item, passed through as GitHub returns it.
`id`	string (uuid)	No	Identifier of the tree item, for the UI’s tree view.
`label`	string	No	Display name of the file or directory.
`type`	string	No	Kind of the tree item, such as a file or a directory.

One page of a repository’s file tree.

Field	Type	Required	Description
`children`	array of object	No	The items under a directory, each shaped as a `GithubRepositoryTreeItem`.
`entry`	object	No	GitHub’s tree entry for the item, passed through as GitHub returns it.
`id`	string (uuid)	No	Identifier of the tree item, for the UI’s tree view.
`label`	string	No	Display name of the file or directory.
`type`	string	No	Kind of the tree item, such as a file or a directory.

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.

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.

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.

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.

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.

GitHub GET

/api/integrations/github/status

Whether the caller's GitHub connection is usable

Checks the caller’s GitHub App connection. A connection is usable only when its installations were verified against the caller’s own GitHub account and GitHub confirms the installation it opens on still exists. 403 with a MeshKit error saying the connection must be re-authorized means it predates verification; re-authorize it with startGithubAuthorization (flow=authorize). When GitHub reports the installation the connection opens on removed, that installation is dropped and the connection re-points at its next verified installation, which is checked in turn: 200 when one remains. 404 means the caller has no GitHub connection, or no verified installation remains - in which case the connection is deleted. 502 means GitHub could not confirm either way; the connection is kept.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/integrations/github/status

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/integrations/github/status

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/integrations/github/status

Returned data

Responses

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

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.

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.

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.

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.

GitHub POST

/api/integrations/github/verify/{owner}/{repo}

Whether the Kanvas workflow is already present in a repository

Reports whether the Kanvas workflow is already committed to a repository. The repository’s installation is resolved and authorized by the server; the id query parameter is accepted for compatibility and is not consulted. A repository the caller cannot reach through one of their verified GitHub App installations is refused with the same uniform 403 as importGithubRepository. No request body.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/integrations/github/verify/{owner}/{repo}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/integrations/github/verify/{owner}/{repo}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/integrations/github/verify/{owner}/{repo}

Parameters

Path parameters

Name	Type	Required	Description
`owner`	string	Yes	Login of the account that owns the repository.
`repo`	string	Yes	Repository name, without its owner.

Query parameters

Name	Type	Required	Description
`id`	string	No	Ignored. Accepted for compatibility; the server resolves the installation itself.

Returned data

Responses

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

Whether the Kanvas workflow is already present in a repository.

Field	Type	Required	Description
`error`	string	No	Why the repository cannot take the workflow.
`fileUrl`	string (uri)	No	URL of the workflow file already present.
`status`	string	Yes	`ok` when no workflow is present; `error` when one is (`fileUrl` names it) or the check failed (`error` says why).

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.

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.

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.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/integrations/meshmodels/models

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/integrations/meshmodels/models

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/integrations/meshmodels/models

Parameters

Query parameters

Name	Type	Required	Description
`page`	integer	No	Current page number of the result set.
`pageSize`	integer	No	Number of items per page.
`search`	string	No	Free-text search query applied to model names.
`order`	string	No	Sort order for the result set (e.g. “name asc”).

Returned data

Responses

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

Page of mesh models matching the list-endpoint query.

Field	Type	Required	Description
`models`	array of object	No	The models matching the list-endpoint query.
`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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/integrations/support

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/integrations/support

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/integrations/support

Request body

application/json Required

Payload for submitting a help-and-support request.

Field	Type	Required	Description
`message`	string	Yes	Detailed description of the issue or question.
`scope`	string	No	Category that best represents the nature of the inquiry.
`subject`	string	Yes	Concise and descriptive title for the support request.

Returned data

Responses

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

Field	Type	Required	Description
`message`	string	No	No description provided.

Ledger POST

/api/ledgers/{ledger}/claims

Claim a ledger key if absent

Atomically gives entryKey to the connection connectionId, which must be the caller’s own live connection in the session organization; any other connection is 404. When the key is not in the ledger, the entry is created already claimed and returned with 201. When it is recorded but unclaimed, it is claimed and returned with 200. When connectionId already holds it, the call is a replay and returns the entry with 200. When another live connection holds it, the call is refused with 409 and nothing changes. A claim ends when the entry is deleted or when the holding connection is deleted; a key whose holder was deleted can be claimed again.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/ledgers/{ledger}/claims

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/ledgers/{ledger}/claims

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/ledgers/{ledger}/claims

Parameters

Path parameters

Name	Type	Required	Description
`ledger`	string	Yes	Name of the ledger, for example `processed-profiles`.

Request body

application/json Required

Claim-if-absent payload giving a key to one connection.

Field	Type	Required	Description
`connectionId`	string (uuid)	Yes	ID of the connection taking the key: the caller’s own live connection in the session organization (for example the connection a desktop client registered for its machine).
`entryKey`	string	Yes	Key to claim.
`value`	object	No	Value stored when the claim creates the entry; ignored when the entry already exists.

Returned data

Responses

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

Server-returned ledger entry. An organization keeps any number of named ledgers, each an idempotent set keyed by entryKey: recording an existing key never creates a second entry and never changes that entry, and claim-if-absent gives a key to exactly one claiming connection, so two workers never both act on it. Change a stored value with updateLedgerEntry, which replaces the value wholesale and advances updatedAt. Any organization member may read, update and delete entries; a claim names the connection that holds it, which must be the caller’s own live connection in the organization. An update does not check who holds a claim.

Field	Type	Required	Description
`id`	string (uuid)	Yes	Server-generated ledger entry ID.
`organizationId`	string (uuid)	Yes	Owning organization ID. Derived from the authenticated session, never client-settable.
`ledger`	string	Yes	Name of the ledger (the idempotent set) the entry belongs to.
`entryKey`	string	Yes	Key within the ledger. Unique per (organization, ledger).
`value`	object	No	Entry value, stored as a JSON blob.
`claimedByConnectionId`	string (uuid)	No	ID of the connection that holds the entry, if any. Set only by claim-if-absent and never changed afterwards. References a connection (`connections.id`); a claim held by a connection that is later deleted is released, so the key may be claimed again. Omitted when the entry is unclaimed.
`claimedAt`	string \| null (date-time)	No	Time the current or most recent claim was taken. Set only by claim-if-absent; null when the entry was never claimed. An entry whose claimedByConnectionId is omitted is unclaimed whatever this holds.
`createdAt`	string (date-time)	Yes	Timestamp of ledger entry creation.
`updatedAt`	string (date-time)	Yes	Timestamp of last ledger entry modification; advances on every update.

Server-returned ledger entry. An organization keeps any number of named ledgers, each an idempotent set keyed by entryKey: recording an existing key never creates a second entry and never changes that entry, and claim-if-absent gives a key to exactly one claiming connection, so two workers never both act on it. Change a stored value with updateLedgerEntry, which replaces the value wholesale and advances updatedAt. Any organization member may read, update and delete entries; a claim names the connection that holds it, which must be the caller’s own live connection in the organization. An update does not check who holds a claim.

Field	Type	Required	Description
`id`	string (uuid)	Yes	Server-generated ledger entry ID.
`organizationId`	string (uuid)	Yes	Owning organization ID. Derived from the authenticated session, never client-settable.
`ledger`	string	Yes	Name of the ledger (the idempotent set) the entry belongs to.
`entryKey`	string	Yes	Key within the ledger. Unique per (organization, ledger).
`value`	object	No	Entry value, stored as a JSON blob.
`claimedByConnectionId`	string (uuid)	No	ID of the connection that holds the entry, if any. Set only by claim-if-absent and never changed afterwards. References a connection (`connections.id`); a claim held by a connection that is later deleted is released, so the key may be claimed again. Omitted when the entry is unclaimed.
`claimedAt`	string \| null (date-time)	No	Time the current or most recent claim was taken. Set only by claim-if-absent; null when the entry was never claimed. An entry whose claimedByConnectionId is omitted is unclaimed whatever this holds.
`createdAt`	string (date-time)	Yes	Timestamp of ledger entry creation.
`updatedAt`	string (date-time)	Yes	Timestamp of last ledger entry modification; advances on every update.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/ledgers/{ledger}/entries

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/ledgers/{ledger}/entries

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/ledgers/{ledger}/entries

Parameters

Path parameters

Name	Type	Required	Description
`ledger`	string	Yes	Name of the ledger, for example `processed-profiles`.

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

Returned data

Responses

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

Paginated collection of ledger entries.

Field	Type	Required	Description
`ledgerEntries`	array of object	Yes	Ledger entries included on this page of results.
`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.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/ledgers/{ledger}/entries

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/ledgers/{ledger}/entries

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/ledgers/{ledger}/entries

Parameters

Path parameters

Name	Type	Required	Description
`ledger`	string	Yes	Name of the ledger, for example `processed-profiles`.

Request body

application/json Required

Payload for recording a ledger entry. The ledger comes from the path and the organization from the session; claim fields and timestamps are server-owned.

Field	Type	Required	Description
`entryKey`	string	Yes	Key within the ledger.
`value`	object	No	Entry value, stored as a JSON object.

Returned data

Responses

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

Server-returned ledger entry. An organization keeps any number of named ledgers, each an idempotent set keyed by entryKey: recording an existing key never creates a second entry and never changes that entry, and claim-if-absent gives a key to exactly one claiming connection, so two workers never both act on it. Change a stored value with updateLedgerEntry, which replaces the value wholesale and advances updatedAt. Any organization member may read, update and delete entries; a claim names the connection that holds it, which must be the caller’s own live connection in the organization. An update does not check who holds a claim.

Field	Type	Required	Description
`id`	string (uuid)	Yes	Server-generated ledger entry ID.
`organizationId`	string (uuid)	Yes	Owning organization ID. Derived from the authenticated session, never client-settable.
`ledger`	string	Yes	Name of the ledger (the idempotent set) the entry belongs to.
`entryKey`	string	Yes	Key within the ledger. Unique per (organization, ledger).
`value`	object	No	Entry value, stored as a JSON blob.
`claimedByConnectionId`	string (uuid)	No	ID of the connection that holds the entry, if any. Set only by claim-if-absent and never changed afterwards. References a connection (`connections.id`); a claim held by a connection that is later deleted is released, so the key may be claimed again. Omitted when the entry is unclaimed.
`claimedAt`	string \| null (date-time)	No	Time the current or most recent claim was taken. Set only by claim-if-absent; null when the entry was never claimed. An entry whose claimedByConnectionId is omitted is unclaimed whatever this holds.
`createdAt`	string (date-time)	Yes	Timestamp of ledger entry creation.
`updatedAt`	string (date-time)	Yes	Timestamp of last ledger entry modification; advances on every update.

Server-returned ledger entry. An organization keeps any number of named ledgers, each an idempotent set keyed by entryKey: recording an existing key never creates a second entry and never changes that entry, and claim-if-absent gives a key to exactly one claiming connection, so two workers never both act on it. Change a stored value with updateLedgerEntry, which replaces the value wholesale and advances updatedAt. Any organization member may read, update and delete entries; a claim names the connection that holds it, which must be the caller’s own live connection in the organization. An update does not check who holds a claim.

Field	Type	Required	Description
`id`	string (uuid)	Yes	Server-generated ledger entry ID.
`organizationId`	string (uuid)	Yes	Owning organization ID. Derived from the authenticated session, never client-settable.
`ledger`	string	Yes	Name of the ledger (the idempotent set) the entry belongs to.
`entryKey`	string	Yes	Key within the ledger. Unique per (organization, ledger).
`value`	object	No	Entry value, stored as a JSON blob.
`claimedByConnectionId`	string (uuid)	No	ID of the connection that holds the entry, if any. Set only by claim-if-absent and never changed afterwards. References a connection (`connections.id`); a claim held by a connection that is later deleted is released, so the key may be claimed again. Omitted when the entry is unclaimed.
`claimedAt`	string \| null (date-time)	No	Time the current or most recent claim was taken. Set only by claim-if-absent; null when the entry was never claimed. An entry whose claimedByConnectionId is omitted is unclaimed whatever this holds.
`createdAt`	string (date-time)	Yes	Timestamp of ledger entry creation.
`updatedAt`	string (date-time)	Yes	Timestamp of last ledger entry modification; advances on every update.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/ledgers/{ledger}/entries/{entryKey}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/ledgers/{ledger}/entries/{entryKey}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/ledgers/{ledger}/entries/{entryKey}

Parameters

Path parameters

Name	Type	Required	Description
`ledger`	string	Yes	Name of the ledger, for example `processed-profiles`.
`entryKey`	string	Yes	Key within the ledger. URL-encode keys that contain reserved characters such as `/`.

Returned data

Responses

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

Server-returned ledger entry. An organization keeps any number of named ledgers, each an idempotent set keyed by entryKey: recording an existing key never creates a second entry and never changes that entry, and claim-if-absent gives a key to exactly one claiming connection, so two workers never both act on it. Change a stored value with updateLedgerEntry, which replaces the value wholesale and advances updatedAt. Any organization member may read, update and delete entries; a claim names the connection that holds it, which must be the caller’s own live connection in the organization. An update does not check who holds a claim.

Field	Type	Required	Description
`id`	string (uuid)	Yes	Server-generated ledger entry ID.
`organizationId`	string (uuid)	Yes	Owning organization ID. Derived from the authenticated session, never client-settable.
`ledger`	string	Yes	Name of the ledger (the idempotent set) the entry belongs to.
`entryKey`	string	Yes	Key within the ledger. Unique per (organization, ledger).
`value`	object	No	Entry value, stored as a JSON blob.
`claimedByConnectionId`	string (uuid)	No	ID of the connection that holds the entry, if any. Set only by claim-if-absent and never changed afterwards. References a connection (`connections.id`); a claim held by a connection that is later deleted is released, so the key may be claimed again. Omitted when the entry is unclaimed.
`claimedAt`	string \| null (date-time)	No	Time the current or most recent claim was taken. Set only by claim-if-absent; null when the entry was never claimed. An entry whose claimedByConnectionId is omitted is unclaimed whatever this holds.
`createdAt`	string (date-time)	Yes	Timestamp of ledger entry creation.
`updatedAt`	string (date-time)	Yes	Timestamp of last ledger entry modification; advances on every update.

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.

Ledger PUT

/api/ledgers/{ledger}/entries/{entryKey}

Update a ledger entry

Replaces the stored value wholesale (not a merge) and advances updatedAt (strictly increasing, so it works as a version token). Never changes entryKey, claimedByConnectionId, claimedAt, createdAt or id. Does not create entries: a key that is not in the ledger is 404 (use POST entries or claims to create). Does not check who holds a claim (same as delete). Any member of the session organization may update. expectedValue, when present, applies the update only if the stored value equals it (JSON equality; key order and whitespace do not matter). expectedUpdatedAt, when present, applies the update only if the stored entry’s updatedAt equals it exactly; clients echo the updatedAt they last read. Both preconditions may be sent; then both must hold. With neither, the update is unconditional. A precondition that does not match returns 412 and changes nothing. A bad ledger name, key, or body (for example a missing value or a non-object value) is 400.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/ledgers/{ledger}/entries/{entryKey}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/ledgers/{ledger}/entries/{entryKey}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/ledgers/{ledger}/entries/{entryKey}

Parameters

Path parameters

Name	Type	Required	Description
`ledger`	string	Yes	Name of the ledger, for example `processed-profiles`.
`entryKey`	string	Yes	Key within the ledger. URL-encode keys that contain reserved characters such as `/`.

Request body

application/json Required

Payload for replacing a ledger entry’s value. The ledger and entryKey come from the path. Claim fields, id and timestamps are server-owned and are not accepted here.

Field	Type	Required	Description
`expectedUpdatedAt`	string (date-time)	No	Optional precondition. When present, the update applies only if the stored entry’s updatedAt equals this instant exactly. Clients echo the updatedAt they last read. Omit the property to skip this check.
`expectedValue`	object	No	Optional precondition. When present, including as an empty object, the update applies only if the stored value equals this object (JSON equality; key order and whitespace do not matter). Omit the property to skip this check. Absence is distinct from an empty object.
`value`	object	Yes	The new entry value, stored as a JSON object. Replaces the stored value wholesale.

Returned data

Responses

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

Server-returned ledger entry. An organization keeps any number of named ledgers, each an idempotent set keyed by entryKey: recording an existing key never creates a second entry and never changes that entry, and claim-if-absent gives a key to exactly one claiming connection, so two workers never both act on it. Change a stored value with updateLedgerEntry, which replaces the value wholesale and advances updatedAt. Any organization member may read, update and delete entries; a claim names the connection that holds it, which must be the caller’s own live connection in the organization. An update does not check who holds a claim.

Field	Type	Required	Description
`id`	string (uuid)	Yes	Server-generated ledger entry ID.
`organizationId`	string (uuid)	Yes	Owning organization ID. Derived from the authenticated session, never client-settable.
`ledger`	string	Yes	Name of the ledger (the idempotent set) the entry belongs to.
`entryKey`	string	Yes	Key within the ledger. Unique per (organization, ledger).
`value`	object	No	Entry value, stored as a JSON blob.
`claimedByConnectionId`	string (uuid)	No	ID of the connection that holds the entry, if any. Set only by claim-if-absent and never changed afterwards. References a connection (`connections.id`); a claim held by a connection that is later deleted is released, so the key may be claimed again. Omitted when the entry is unclaimed.
`claimedAt`	string \| null (date-time)	No	Time the current or most recent claim was taken. Set only by claim-if-absent; null when the entry was never claimed. An entry whose claimedByConnectionId is omitted is unclaimed whatever this holds.
`createdAt`	string (date-time)	Yes	Timestamp of ledger entry creation.
`updatedAt`	string (date-time)	Yes	Timestamp of last ledger entry modification; advances on every update.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/ledgers/{ledger}/entries/{entryKey}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/ledgers/{ledger}/entries/{entryKey}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/ledgers/{ledger}/entries/{entryKey}

Parameters

Path parameters

Name	Type	Required	Description
`ledger`	string	Yes	Name of the ledger, for example `processed-profiles`.
`entryKey`	string	Yes	Key within the ledger. URL-encode keys that contain reserved characters such as `/`.

Returned data

Responses

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

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/media-assets

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/media-assets

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/media-assets

Parameters

Query parameters

Name	Type	Required	Description
`page`	integer	No	Get responses by page
`pageSize`	integer	No	Number of items per page.
`search`	string	No	Get responses that match search param value
`order`	string	No	Get ordered responses
`status`	string	No	Filter by status, evaluated at read time (a `ready` asset past `expiresAt` matches `expired`).

Returned data

Responses

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

Paginated collection of media assets.

Field	Type	Required	Description
`mediaAssets`	array of object	No	Media assets included on this page of results.
`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.

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.

MediaAsset POST

/api/media-assets

Create a media asset and its upload URL

Records a new pending asset from the declared contentType, bytes and sha256, and answers it with a short-lived upload URL. The client sends the file’s bytes to upload.url with one request using upload.method and exactly the upload.headers, before upload.expiresAt, then calls completeMediaAsset. The server derives kind from contentType and sets expiresAt to the end of the upload window. Refused with 400 when contentType is not one the provider accepts (MediaAssetQuota.contentTypes), when bytes exceeds the per-kind limit (maxImageBytes, maxVideoBytes), when backend is one the provider does not serve, when gdrive is named without a connectionId or r2 with one, and when retainUntil is not in the future or lies beyond maxRetentionDays from now. Refused with 409 when the asset would take the organization past bytesLimit. A connectionId that is not the caller’s own live Google Drive connection in the session organization receives 404. Every create is a new asset; nothing is deduplicated by sha256. A create that is never completed is reaped when its upload window ends.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/media-assets

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/media-assets

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/media-assets

Request body

application/json Required

Payload for creating a media asset. Contains only client-settable fields; the owning organizationId and createdBy (from the session), kind (derived from contentType), status, rejectionReason, externalId, completedAt, expiresAt and the timestamps are server-owned and not accepted.

Field	Type	Required	Description
`backend`	string	No	Where to store the file. Omitted, the server stores it in `r2`.
`bytes`	integer (int64)	Yes	Size of the file in bytes. Must not exceed the quota’s limit for its kind.
`connectionId`	string (uuid)	No	The caller’s own live Google Drive connection in the session organization. Required when `backend` is `gdrive`, refused otherwise.
`contentType`	string	Yes	Media type of the file, from a closed allowlist. The server sniffs the stored bytes on completion and rejects an upload whose real type differs. A provider may accept fewer types than this list (`MediaAssetQuota.contentTypes`).
`locationStripped`	boolean	Yes	Whether the client removed location metadata (EXIF and XMP GPS, maker notes, device serial numbers) from the file before hashing and uploading it. Recorded as sent.
`name`	string	No	Display name of the file, typically its original file name.
`retainUntil`	string (date-time)	No	Time the asset must stay downloadable until, for example a little after the post that uses it is scheduled. Omitted, the organization’s default retention applies from completion.
`sha256`	string	Yes	Lowercase hex SHA-256 of the exact bytes that will be uploaded.

Returned data

Responses

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

Answer to createMediaAsset: the new pending asset and the grant to upload its bytes.

Field	Type	Required	Description
`mediaAsset`	object	Yes	Server-returned media asset: one image or video file an organization uploaded so that a content item can post it without a link. A content item refers to an asset by its `id`, never by a URL; a short-lived download URL is minted only when the file is about to be used (`getMediaAssetDownload`) and is never stored. An asset is created `pending` with a short-lived upload URL, becomes `ready` once `completeMediaAsset` has checked the stored bytes against the declared size, type and SHA-256, or `rejected` when they do not match. A `pending` asset that is never completed, and a `ready` asset whose retention ended, read as `expired` from `expiresAt` on: expiry is evaluated when the asset is read, so an asset never reads `pending` or `ready` past its `expiresAt`. No field carries a storage credential, a bucket name, an object key or a signed URL. The bytes live in the backend `backend` names, under a location only the server knows.
`upload`	object	Yes	A short-lived grant to move one file’s bytes: send one request with `method` to `url` carrying exactly `headers`, before `expiresAt`. The URL is the only credential, it covers this one file, and it must be treated as a secret: never store it, log it or put it in a content item.

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.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/media-assets/quota

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/media-assets/quota

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/media-assets/quota

Returned data

Responses

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

The media asset limits of the session organization and its current storage use.

Field	Type	Required	Description
`backends`	array of string	Yes	Backends this provider serves for the organization. A create naming another is refused with 400.
`bytesLimit`	integer \| null (int64)	Yes	Total bytes the organization’s live `pending` and `ready` assets may hold. Null when the organization has no storage limit.
`bytesUsed`	integer \| null (int64)	Yes	Total bytes of the organization’s live `pending` and `ready` assets. Null when it could not be measured, which must be presented as unknown; a number, including 0, is a measurement.
`contentTypes`	array of string	Yes	Content types this provider accepts.
`defaultRetentionDays`	integer	Yes	Days a `ready` asset is kept after completion when no `retainUntil` was set.
`maxImageBytes`	integer (int64)	Yes	Largest image a create accepts, in bytes.
`maxRetentionDays`	integer	Yes	Furthest `retainUntil` may lie from now, in days.
`maxVideoBytes`	integer (int64)	Yes	Largest video a create accepts, in bytes.
`uploadWindowSeconds`	integer	Yes	How long a `pending` asset waits for its upload and completion before it expires, in seconds.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/media-assets/{mediaAssetId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/media-assets/{mediaAssetId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/media-assets/{mediaAssetId}

Parameters

Path parameters

Name	Type	Required	Description
`mediaAssetId`	string (uuid)	Yes	Media asset ID

Returned data

Responses

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

Server-returned media asset: one image or video file an organization uploaded so that a content item can post it without a link. A content item refers to an asset by its id, never by a URL; a short-lived download URL is minted only when the file is about to be used (getMediaAssetDownload) and is never stored. An asset is created pending with a short-lived upload URL, becomes ready once completeMediaAsset has checked the stored bytes against the declared size, type and SHA-256, or rejected when they do not match. A pending asset that is never completed, and a ready asset whose retention ended, read as expired from expiresAt on: expiry is evaluated when the asset is read, so an asset never reads pending or ready past its expiresAt. No field carries a storage credential, a bucket name, an object key or a signed URL. The bytes live in the backend backend names, under a location only the server knows.

Field	Type	Required	Description
`id`	string (uuid)	Yes	Server-generated media asset ID. Reveals nothing about the file or where it is stored.
`organizationId`	string (uuid)	Yes	Owning organization ID. Derived from the authenticated session, never client-settable.
`createdBy`	string (uuid)	No	ID of the user whose session created the asset. Derived from the authenticated session, never client-settable. Omitted when that user was later purged.
`backend`	string	Yes	Where the bytes are stored (`r2` or `gdrive`).
`connectionId`	string (uuid)	No	ID of the Google Drive connection (`connections.id`) the file was uploaded through. Set only when `backend` is `gdrive`; omitted for `r2`, and when that connection was later deleted.
`externalId`	string	No	Identifier of the file in the person’s own storage: the Google Drive file ID when `backend` is `gdrive`. Server-written once the upload is completed; omitted for `r2`, whose storage location is never on the wire, and while a `gdrive` asset is `pending`.
`kind`	string	Yes	Image or video, derived by the server from `contentType`.
`contentType`	string	Yes	Media type of the file, from the closed allowlist; checked against the sniffed bytes on completion.
`bytes`	integer (int64)	Yes	Size of the file in bytes, as declared at create. `completeMediaAsset` refuses an upload whose stored size differs.
`sha256`	string	Yes	Lowercase hex SHA-256 of the file’s bytes as uploaded (after any metadata stripping), as declared at create. `completeMediaAsset` refuses an upload whose stored bytes hash differently, and a reader compares the bytes it downloads against it before posting them.
`name`	string	No	Display name of the file, typically its original file name. Shown to people only; the type is never inferred from it.
`locationStripped`	boolean	Yes	Whether the uploading client removed location metadata (EXIF and XMP GPS, plus maker notes and device serial numbers) from the file before uploading it. Declared by the client and recorded as sent; the server does not inspect the bytes for metadata. `false` records that the bytes may still carry where they were captured, for example a video whose location the client could not remove.
`status`	string	Yes	Lifecycle of the asset. `pending` from create until it is completed; `ready` once the stored bytes matched the declaration; `rejected` when they did not (see `rejectionReason`); `expired` once `expiresAt` passed, whether the upload was never completed or the retention of a `ready` asset ended. Evaluated when the asset is read.
`rejectionReason`	string	No	Why the upload was rejected. Set only on a `rejected` asset.
`retainUntil`	string \| null (date-time)	No	Time the client asked the asset to stay downloadable until, from the create payload or the last `updateMediaAsset`. Null when the client never asked, in which case the organization’s default retention applies once the asset is completed.
`completedAt`	string \| null (date-time)	No	Time `completeMediaAsset` accepted the upload. Null until the asset is `ready`, and on a `rejected` asset.
`expiresAt`	string (date-time)	Yes	Time the asset stops being usable. Always set by the server. While `pending` it is the end of the upload window (`uploadWindowSeconds` of the quota after creation). Once `ready` it is `retainUntil` when the client set one, otherwise `completedAt` plus the organization’s `defaultRetentionDays`. Past it the asset reads `expired`, no download is minted, and the stored bytes of an `r2` asset are removed.
`createdAt`	string (date-time)	Yes	Timestamp of media asset creation.
`updatedAt`	string (date-time)	Yes	Timestamp of last media asset modification.
`deletedAt`	string \| null (date-time)	No	Timestamp when the media asset was deleted. A deleted asset is never returned by the API.

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.

MediaAsset PUT

/api/media-assets/{mediaAssetId}

Change how long a media asset is kept

Sets retainUntil, the only field of an asset that changes after create, for example when the post that uses it is rescheduled. On a ready asset expiresAt becomes retainUntil, so retention can be shortened as well as extended; on a pending asset it is recorded and applied when the asset is completed. Refused with 400 when retainUntil is not in the future or lies beyond maxRetentionDays from now, and with 409 when the asset is rejected or expired.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/media-assets/{mediaAssetId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/media-assets/{mediaAssetId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/media-assets/{mediaAssetId}

Parameters

Path parameters

Name	Type	Required	Description
`mediaAssetId`	string (uuid)	Yes	Media asset ID

Request body

application/json Required

Payload for changing how long a media asset is kept. Retention is the only field that changes after create.

Field	Type	Required	Description
`retainUntil`	string (date-time)	Yes	New time the asset must stay downloadable until. Must be in the future and within `maxRetentionDays` from now.

Returned data

Responses

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

Server-returned media asset: one image or video file an organization uploaded so that a content item can post it without a link. A content item refers to an asset by its id, never by a URL; a short-lived download URL is minted only when the file is about to be used (getMediaAssetDownload) and is never stored. An asset is created pending with a short-lived upload URL, becomes ready once completeMediaAsset has checked the stored bytes against the declared size, type and SHA-256, or rejected when they do not match. A pending asset that is never completed, and a ready asset whose retention ended, read as expired from expiresAt on: expiry is evaluated when the asset is read, so an asset never reads pending or ready past its expiresAt. No field carries a storage credential, a bucket name, an object key or a signed URL. The bytes live in the backend backend names, under a location only the server knows.

Field	Type	Required	Description
`id`	string (uuid)	Yes	Server-generated media asset ID. Reveals nothing about the file or where it is stored.
`organizationId`	string (uuid)	Yes	Owning organization ID. Derived from the authenticated session, never client-settable.
`createdBy`	string (uuid)	No	ID of the user whose session created the asset. Derived from the authenticated session, never client-settable. Omitted when that user was later purged.
`backend`	string	Yes	Where the bytes are stored (`r2` or `gdrive`).
`connectionId`	string (uuid)	No	ID of the Google Drive connection (`connections.id`) the file was uploaded through. Set only when `backend` is `gdrive`; omitted for `r2`, and when that connection was later deleted.
`externalId`	string	No	Identifier of the file in the person’s own storage: the Google Drive file ID when `backend` is `gdrive`. Server-written once the upload is completed; omitted for `r2`, whose storage location is never on the wire, and while a `gdrive` asset is `pending`.
`kind`	string	Yes	Image or video, derived by the server from `contentType`.
`contentType`	string	Yes	Media type of the file, from the closed allowlist; checked against the sniffed bytes on completion.
`bytes`	integer (int64)	Yes	Size of the file in bytes, as declared at create. `completeMediaAsset` refuses an upload whose stored size differs.
`sha256`	string	Yes	Lowercase hex SHA-256 of the file’s bytes as uploaded (after any metadata stripping), as declared at create. `completeMediaAsset` refuses an upload whose stored bytes hash differently, and a reader compares the bytes it downloads against it before posting them.
`name`	string	No	Display name of the file, typically its original file name. Shown to people only; the type is never inferred from it.
`locationStripped`	boolean	Yes	Whether the uploading client removed location metadata (EXIF and XMP GPS, plus maker notes and device serial numbers) from the file before uploading it. Declared by the client and recorded as sent; the server does not inspect the bytes for metadata. `false` records that the bytes may still carry where they were captured, for example a video whose location the client could not remove.
`status`	string	Yes	Lifecycle of the asset. `pending` from create until it is completed; `ready` once the stored bytes matched the declaration; `rejected` when they did not (see `rejectionReason`); `expired` once `expiresAt` passed, whether the upload was never completed or the retention of a `ready` asset ended. Evaluated when the asset is read.
`rejectionReason`	string	No	Why the upload was rejected. Set only on a `rejected` asset.
`retainUntil`	string \| null (date-time)	No	Time the client asked the asset to stay downloadable until, from the create payload or the last `updateMediaAsset`. Null when the client never asked, in which case the organization’s default retention applies once the asset is completed.
`completedAt`	string \| null (date-time)	No	Time `completeMediaAsset` accepted the upload. Null until the asset is `ready`, and on a `rejected` asset.
`expiresAt`	string (date-time)	Yes	Time the asset stops being usable. Always set by the server. While `pending` it is the end of the upload window (`uploadWindowSeconds` of the quota after creation). Once `ready` it is `retainUntil` when the client set one, otherwise `completedAt` plus the organization’s `defaultRetentionDays`. Past it the asset reads `expired`, no download is minted, and the stored bytes of an `r2` asset are removed.
`createdAt`	string (date-time)	Yes	Timestamp of media asset creation.
`updatedAt`	string (date-time)	Yes	Timestamp of last media asset modification.
`deletedAt`	string \| null (date-time)	No	Timestamp when the media asset was deleted. A deleted asset is never returned by the API.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/media-assets/{mediaAssetId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/media-assets/{mediaAssetId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/media-assets/{mediaAssetId}

Parameters

Path parameters

Name	Type	Required	Description
`mediaAssetId`	string (uuid)	Yes	Media asset ID

Returned data

Responses

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

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.

MediaAsset POST

/api/media-assets/{mediaAssetId}/complete

Complete a media asset upload

Checks the stored bytes of a pending asset against its declaration: the size must equal bytes, the type sniffed from the bytes must be contentType (the extension and any declared header are never trusted), and the SHA-256 must equal sha256. On a match the asset becomes ready, completedAt is set and expiresAt moves to the end of its retention. On a mismatch, or when nothing was uploaded, the asset becomes rejected with a rejectionReason, its stored bytes are removed, and the call is refused with 409; the client creates a new asset to try again. Completing a ready asset answers it unchanged, so a retried completion is safe. Completing a rejected or expired asset is refused with 409.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/media-assets/{mediaAssetId}/complete

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/media-assets/{mediaAssetId}/complete

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/media-assets/{mediaAssetId}/complete

Parameters

Path parameters

Name	Type	Required	Description
`mediaAssetId`	string (uuid)	Yes	Media asset ID

Returned data

Responses

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

Server-returned media asset: one image or video file an organization uploaded so that a content item can post it without a link. A content item refers to an asset by its id, never by a URL; a short-lived download URL is minted only when the file is about to be used (getMediaAssetDownload) and is never stored. An asset is created pending with a short-lived upload URL, becomes ready once completeMediaAsset has checked the stored bytes against the declared size, type and SHA-256, or rejected when they do not match. A pending asset that is never completed, and a ready asset whose retention ended, read as expired from expiresAt on: expiry is evaluated when the asset is read, so an asset never reads pending or ready past its expiresAt. No field carries a storage credential, a bucket name, an object key or a signed URL. The bytes live in the backend backend names, under a location only the server knows.

Field	Type	Required	Description
`id`	string (uuid)	Yes	Server-generated media asset ID. Reveals nothing about the file or where it is stored.
`organizationId`	string (uuid)	Yes	Owning organization ID. Derived from the authenticated session, never client-settable.
`createdBy`	string (uuid)	No	ID of the user whose session created the asset. Derived from the authenticated session, never client-settable. Omitted when that user was later purged.
`backend`	string	Yes	Where the bytes are stored (`r2` or `gdrive`).
`connectionId`	string (uuid)	No	ID of the Google Drive connection (`connections.id`) the file was uploaded through. Set only when `backend` is `gdrive`; omitted for `r2`, and when that connection was later deleted.
`externalId`	string	No	Identifier of the file in the person’s own storage: the Google Drive file ID when `backend` is `gdrive`. Server-written once the upload is completed; omitted for `r2`, whose storage location is never on the wire, and while a `gdrive` asset is `pending`.
`kind`	string	Yes	Image or video, derived by the server from `contentType`.
`contentType`	string	Yes	Media type of the file, from the closed allowlist; checked against the sniffed bytes on completion.
`bytes`	integer (int64)	Yes	Size of the file in bytes, as declared at create. `completeMediaAsset` refuses an upload whose stored size differs.
`sha256`	string	Yes	Lowercase hex SHA-256 of the file’s bytes as uploaded (after any metadata stripping), as declared at create. `completeMediaAsset` refuses an upload whose stored bytes hash differently, and a reader compares the bytes it downloads against it before posting them.
`name`	string	No	Display name of the file, typically its original file name. Shown to people only; the type is never inferred from it.
`locationStripped`	boolean	Yes	Whether the uploading client removed location metadata (EXIF and XMP GPS, plus maker notes and device serial numbers) from the file before uploading it. Declared by the client and recorded as sent; the server does not inspect the bytes for metadata. `false` records that the bytes may still carry where they were captured, for example a video whose location the client could not remove.
`status`	string	Yes	Lifecycle of the asset. `pending` from create until it is completed; `ready` once the stored bytes matched the declaration; `rejected` when they did not (see `rejectionReason`); `expired` once `expiresAt` passed, whether the upload was never completed or the retention of a `ready` asset ended. Evaluated when the asset is read.
`rejectionReason`	string	No	Why the upload was rejected. Set only on a `rejected` asset.
`retainUntil`	string \| null (date-time)	No	Time the client asked the asset to stay downloadable until, from the create payload or the last `updateMediaAsset`. Null when the client never asked, in which case the organization’s default retention applies once the asset is completed.
`completedAt`	string \| null (date-time)	No	Time `completeMediaAsset` accepted the upload. Null until the asset is `ready`, and on a `rejected` asset.
`expiresAt`	string (date-time)	Yes	Time the asset stops being usable. Always set by the server. While `pending` it is the end of the upload window (`uploadWindowSeconds` of the quota after creation). Once `ready` it is `retainUntil` when the client set one, otherwise `completedAt` plus the organization’s `defaultRetentionDays`. Past it the asset reads `expired`, no download is minted, and the stored bytes of an `r2` asset are removed.
`createdAt`	string (date-time)	Yes	Timestamp of media asset creation.
`updatedAt`	string (date-time)	Yes	Timestamp of last media asset modification.
`deletedAt`	string \| null (date-time)	No	Timestamp when the media asset was deleted. A deleted asset is never returned by the API.

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.

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.

MediaAsset GET

/api/media-assets/{mediaAssetId}/content

Download the bytes of a Drive-backed media asset

Streams the bytes of a ready gdrive asset from the person’s Google Drive. This route is only ever reached through a URL that getMediaAssetDownload minted: it takes no session, and the expires and signature it carries are the whole grant, valid for that one asset until expires. The response Content-Type is the asset’s contentType. A missing, altered or lapsed signature is refused with 403; an asset that was deleted, expired or is not gdrive since the URL was minted receives 404; a Drive file that was removed, moved out of reach or whose grant was revoked is refused with 502.

Authentication

No authentication required

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/media-assets/{mediaAssetId}/content

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/media-assets/{mediaAssetId}/content

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/media-assets/{mediaAssetId}/content

Parameters

Path parameters

Name	Type	Required	Description
`mediaAssetId`	string (uuid)	Yes	Media asset ID

Query parameters

Name	Type	Required	Description
`expires`	integer (int64)	Yes	Time the grant lapses, in seconds since the Unix epoch.
`signature`	string	Yes	Server-computed signature over the asset ID and `expires`. Opaque to clients.

Returned data

Responses

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

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.

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.

MediaAsset GET

/api/media-assets/{mediaAssetId}/download

Get a short-lived download URL for a media asset

Mints a fresh download URL for a ready asset, valid for minutes. Call it just before the file is used and never store the answer: a scheduled post asks for a new URL when it runs. For r2 the URL is a signed URL on the provider’s object storage; for gdrive it is a signed getMediaAssetContent URL on the provider, which relays the bytes from the person’s Drive so that no Google token leaves the provider. A pending, rejected or expired asset is refused with 409. The reader checks the downloaded bytes against bytes and sha256 before using them.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/media-assets/{mediaAssetId}/download

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/media-assets/{mediaAssetId}/download

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/media-assets/{mediaAssetId}/download

Parameters

Path parameters

Name	Type	Required	Description
`mediaAssetId`	string (uuid)	Yes	Media asset ID

Returned data

Responses

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

A short-lived grant to move one file’s bytes: send one request with method to url carrying exactly headers, before expiresAt. The URL is the only credential, it covers this one file, and it must be treated as a secret: never store it, log it or put it in a content item.

Field	Type	Required	Description
`expiresAt`	string (date-time)	Yes	Time the URL stops working.
`headers`	object	Yes	Headers the request must carry, verbatim (for an upload, at least `Content-Type`, and any integrity header the signature binds). Empty when none are needed. Never contains an authorization header.
`method`	string	Yes	HTTP method to use. `PUT` for an upload, `GET` for a download.
`url`	string (uri)	Yes	Absolute HTTPS URL to send the request to.

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.

MentionAlias GET

/api/mention-aliases

List mention aliases

Returns a paginated list of the mention aliases of the organization of the authenticated session. entity (repeatable) returns only the aliases of those entities, each compared ignoring case, so the aliases for every tag in one message come back in one read; an entity with no alias contributes nothing. platform (repeatable) returns only the aliases on those platforms. search matches entity or handle containing the term, ignoring case. order sorts by entity, platform, createdAt or updatedAt (asc or desc); the default is entity asc, then platform asc. An organization with no matching alias returns an empty page.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/mention-aliases

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/mention-aliases

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/mention-aliases

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
`entity`	array of string	No	Return only the aliases of these entities (repeatable), each compared ignoring case.
`platform`	array of string	No	Return only the aliases on these platforms (repeatable).

Returned data

Responses

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

Paginated collection of mention aliases.

Field	Type	Required	Description
`mentionAliases`	array of object	Yes	Mention aliases included on this page of results.
`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.

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.

MentionAlias POST

/api/mention-aliases

Write mention aliases

Writes the confirmed aliases in mentionAliases, keyed by (entity, platform) with entity compared ignoring case. A new key creates the alias; an existing key replaces its handle and entity casing, sets confirmedBy to the caller and advances updatedAt, even when the handle is unchanged. id, organizationId and createdAt of an existing alias never change. The write is all or nothing in one transaction: a body that fails validation, or that names the same key twice, is refused with a 400 and stores nothing. Answers 200 with the stored aliases, one per entry and in the order of the request.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/mention-aliases

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/mention-aliases

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/mention-aliases

Request body

application/json Required

The confirmed aliases to write in one all-or-nothing request.

Field	Type	Required	Description
`mentionAliases`	array of object	Yes	Aliases to write, at most one per (`entity`, `platform`) key with `entity` compared ignoring case. A key named twice refuses the whole request with 400.

Returned data

Responses

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

Field	Type	Required	Description
`id`	string (uuid)	Yes	Server-generated mention alias ID.
`organizationId`	string (uuid)	Yes	Owning organization ID. Derived from the authenticated session, never client-settable.
`entity`	string	Yes	The tag as written after `@`, without the `@` (`kate`). Compared ignoring case: `Kate` and `kate` are the same entity, and the alias keeps the casing of the write that last stored it. The pattern is the tag grammar a message is read with: letters, digits, `_`, `.` and `-`, starting and ending with a letter, digit or `_`.
`platform`	string	Yes	A platform whose messages can tag an entity: `linkedin`, `x`, `bluesky`, `reddit` or `slack`. A server refuses any other value with 400. A platform joins by adding a value here.
`handle`	string	Yes	The entity’s form on `platform`, stored as confirmed: `@kate_ops` on X, `@kate.example.org` on Bluesky, `u/kate` or `r/kate` on Reddit, a member ID such as `U012AB3CD` on Slack, or a plain-text name on LinkedIn. An empty string is a confirmed answer, not a missing one: it means the entity is sent as its name in plain text on that platform. The server checks length and surrounding whitespace only; whether a value is a valid handle on its platform is the client’s check.
`confirmedBy`	string (uuid)	No	ID of the user whose session last wrote the alias. Derived from the authenticated session on every write, never client-settable. Omitted when that user was later purged.
`createdAt`	string (date-time)	Yes	Timestamp the alias was first confirmed.
`updatedAt`	string (date-time)	Yes	Timestamp the alias was last confirmed. Every write of the alias’s key advances it, including one that stores the same handle again.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/mention-aliases/{mentionAliasId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/mention-aliases/{mentionAliasId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/mention-aliases/{mentionAliasId}

Parameters

Path parameters

Name	Type	Required	Description
`mentionAliasId`	string (uuid)	Yes	Mention alias ID

Returned data

Responses

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

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/organizations/badges

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/organizations/badges

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/organizations/badges

Request body

application/json Required

Payload for creating or updating a badge.

Field	Type	Required	Description
`description`	string	Yes	A description of the milestone achieved, often including criteria for receiving this recognition.
`id`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`imageUrl`	string (uri)	Yes	URL to the badge image.
`label`	string	Yes	Unique identifier for the badge, typically slug-style (auto generated).
`name`	string	Yes	Concise descriptor for the badge or certificate.
`orgId`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.

Returned data

Responses

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

Badge entity — a named recognition issued within an organization.

Field	Type	Required	Description
`createdAt`	string (date-time)	Yes	Timestamp when the badge was created.
`deletedAt`	string (date-time)	Yes	Timestamp when the badge was soft-deleted, if applicable.
`description`	string	Yes	A description of the milestone achieved, often including criteria for receiving this recognition.
`id`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`imageUrl`	string (uri)	Yes	URL to the badge image.
`label`	string	Yes	Unique identifier for the badge, typically slug-style (auto generated).
`name`	string	Yes	Concise descriptor for the badge or certificate.
`orgId`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`updatedAt`	string (date-time)	Yes	Timestamp when the badge was last updated.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/organizations/badges/{badgeId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/organizations/badges/{badgeId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/organizations/badges/{badgeId}

Parameters

Path parameters

Name	Type	Required	Description
`badgeId`	string (uuid)	Yes	Badge ID

Returned data

Responses

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

Badge entity — a named recognition issued within an organization.

Field	Type	Required	Description
`createdAt`	string (date-time)	Yes	Timestamp when the badge was created.
`deletedAt`	string (date-time)	Yes	Timestamp when the badge was soft-deleted, if applicable.
`description`	string	Yes	A description of the milestone achieved, often including criteria for receiving this recognition.
`id`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`imageUrl`	string (uri)	Yes	URL to the badge image.
`label`	string	Yes	Unique identifier for the badge, typically slug-style (auto generated).
`name`	string	Yes	Concise descriptor for the badge or certificate.
`orgId`	string (uuid)	Yes	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`updatedAt`	string (date-time)	Yes	Timestamp when the badge was last updated.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/organizations/badges/{badgeId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/organizations/badges/{badgeId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/organizations/badges/{badgeId}

Parameters

Path parameters

Name	Type	Required	Description
`badgeId`	string (uuid)	Yes	Badge ID

Returned data

Responses

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

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/organizations/invitations

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/organizations/invitations

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/organizations/invitations

Parameters

Query parameters

Name	Type	Required	Description
`page`	integer	No	Get responses by page
`pagesize`	integer	No	Get responses by 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 invitations for an organization.

Field	Type	Required	Description
`data`	array of object	No	Invitations returned on the current page.
`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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/organizations/invitations

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/organizations/invitations

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/organizations/invitations

Request body

application/json Required

Payload for creating or updating an invitation.

Field	Type	Required	Description
`acceptanceOutcome`	string	No	Determines what accepting this invitation does for the accepting user, for new and existing accounts alike. direct_membership (the default, and the behavior of every invitation that omits this property) adds the user to the inviting organization. child_organization creates a new child organization for the user whose parent is always the inviting organization; the child follows the standard organization-creation procedure (a My Team team, a My Workspace workspace, and the accepting user as its owner with organization administrator privileges). The child’s display name is set by childOrganizationName when present and non-empty; otherwise it defaults to “My Organization”. With child_organization the invitation’s roles and teams apply in the child organization, not in the inviting organization.
`childOrganizationBranding`	string	No	Determines what branding a child organization created by accepting this invitation starts with. Applies only when acceptanceOutcome is child_organization; ignored otherwise. parent (the default, including every invitation that omits this property) copies the inviting organization’s branding into the child at creation: theme (logos and colors), authentication-page branding, email branding (sender name, templates, and footer), links (including social profiles), and the authentication-page carousel setting. provider copies the provider organization’s branding instead. none gives the child no branding of its own. Every copy is a snapshot: later changes to the source do not propagate, and the child’s administrators can change its branding afterwards without affecting the source.
`childOrganizationName`	string	No	Display name for the child organization created when acceptanceOutcome is child_organization. Applies only when acceptanceOutcome is child_organization; ignored otherwise. When this property is omitted or empty, the child is named “My Organization”. When present and non-empty, that string is the child organization’s name at creation. Administrators can rename the child afterward.
`description`	string	No	Description of the invitation. Optional; omitting it stores an empty description.
`emails`	array of string	No	Email addresses or patterns this invitation is valid for. Optional; omitting it or sending an empty list means any email address may accept the invitation.
`expiresAt`	string (date-time)	No	Timestamp when the invitation expires, if applicable.
`id`	string (uuid)	No	Existing invitation ID for updates; omit on create.
`isDefault`	boolean	No	Indicates whether the invitation is a default invitation (open invite).
`name`	string	Yes	Name of the invitation.
`orgId`	string (uuid)	Yes	ID of the organization to which the user is invited.
`owner`	string (uuid)	No	ID of the user who created the invitation.
`quota`	integer	No	Quota for the invitation; limits the number of users that can accept it.
`roles`	array of string	No	Roles that the user will have when accepting the invitation. Optional; omitting it or sending an empty list grants no roles.
`status`	string	Yes	Activation status of the invitation.
`teams`	array of string	No	Teams that the user will be added to when accepting the invitation. Optional; omitting it or sending an empty list adds the user to no teams.

Returned data

Responses

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

Invitation entity schema.

Field	Type	Required	Description
`acceptanceOutcome`	string	No	Determines what accepting this invitation does for the accepting user, for new and existing accounts alike. direct_membership (the default, and the behavior of every invitation that omits this property) adds the user to the inviting organization. child_organization creates a new child organization for the user whose parent is always the inviting organization; the child follows the standard organization-creation procedure (a My Team team, a My Workspace workspace, and the accepting user as its owner with organization administrator privileges). The child’s display name is set by childOrganizationName when present and non-empty; otherwise it defaults to “My Organization”. With child_organization the invitation’s roles and teams apply in the child organization, not in the inviting organization.
`acceptedBy`	array of string	Yes	List of user ids that have already accepted the invitation. Empty means the invitation has not been used yet.
`childOrganizationBranding`	string	No	Determines what branding a child organization created by accepting this invitation starts with. Applies only when acceptanceOutcome is child_organization; ignored otherwise. parent (the default, including every invitation that omits this property) copies the inviting organization’s branding into the child at creation: theme (logos and colors), authentication-page branding, email branding (sender name, templates, and footer), links (including social profiles), and the authentication-page carousel setting. provider copies the provider organization’s branding instead. none gives the child no branding of its own. Every copy is a snapshot: later changes to the source do not propagate, and the child’s administrators can change its branding afterwards without affecting the source.
`childOrganizationName`	string	No	Display name for the child organization created when acceptanceOutcome is child_organization. Applies only when acceptanceOutcome is child_organization; ignored otherwise. When this property is omitted or empty, the child is named “My Organization”. When present and non-empty, that string is the child organization’s name at creation. Administrators can rename the child afterward.
`createdAt`	string (date-time)	Yes	Timestamp when the invitation was created.
`deletedAt`	string \| null (date-time)	Yes	Timestamp when the invitation was deleted, if applicable.
`description`	string	Yes	Description of the invitation, which can be used to provide additional context. Null or empty string means the invitation does not have a description.
`emails`	array of string \| null	Yes	Email addresses or patterns for which the invitation is valid. Null means the invitation is valid for any email address.
`expiresAt`	string \| null (date-time)	No	Timestamp when the invitation expires, if applicable. Null or empty means the invitation does not expire.
`id`	string (uuid)	Yes	Unique identifier for the invitation, also used as the invitation code.
`isDefault`	boolean	No	Indicates whether the invitation is a default invitation (open invite), which can be used to assign users when signing up from fqdn or custom domain. An organization can only have one default invitation.
`name`	string	Yes	Name of the invitation, which can be used to identify it. Required; cannot be an empty string.
`orgId`	string (uuid)	Yes	ID of the organization to which the user is invited.
`owner`	string (uuid)	Yes	ID of the user who created the invitation. Tracks who created the invitation for auditing purposes.
`quota`	integer	No	Quota for the invitation; limits the number of users that can accept it. Null or empty means the invitation is unlimited.
`roles`	array of string	Yes	Roles that the user will have when accepting the invitation. Empty means the invitation does not specify any roles.
`status`	string	Yes	Activation status of the invitation.
`teams`	array of string	Yes	Teams that the user will be added to when accepting the invitation. Empty means the invitation does not specify any teams.
`updatedAt`	string (date-time)	Yes	Timestamp when the invitation was last updated.

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.

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.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/organizations/invitations/{invitationId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/organizations/invitations/{invitationId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/organizations/invitations/{invitationId}

Parameters

Path parameters

Name	Type	Required	Description
`invitationId`	string (uuid)	Yes	The ID of the invitation.

Returned data

Responses

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

Invitation entity schema.

Field	Type	Required	Description
`acceptanceOutcome`	string	No	Determines what accepting this invitation does for the accepting user, for new and existing accounts alike. direct_membership (the default, and the behavior of every invitation that omits this property) adds the user to the inviting organization. child_organization creates a new child organization for the user whose parent is always the inviting organization; the child follows the standard organization-creation procedure (a My Team team, a My Workspace workspace, and the accepting user as its owner with organization administrator privileges). The child’s display name is set by childOrganizationName when present and non-empty; otherwise it defaults to “My Organization”. With child_organization the invitation’s roles and teams apply in the child organization, not in the inviting organization.
`acceptedBy`	array of string	Yes	List of user ids that have already accepted the invitation. Empty means the invitation has not been used yet.
`childOrganizationBranding`	string	No	Determines what branding a child organization created by accepting this invitation starts with. Applies only when acceptanceOutcome is child_organization; ignored otherwise. parent (the default, including every invitation that omits this property) copies the inviting organization’s branding into the child at creation: theme (logos and colors), authentication-page branding, email branding (sender name, templates, and footer), links (including social profiles), and the authentication-page carousel setting. provider copies the provider organization’s branding instead. none gives the child no branding of its own. Every copy is a snapshot: later changes to the source do not propagate, and the child’s administrators can change its branding afterwards without affecting the source.
`childOrganizationName`	string	No	Display name for the child organization created when acceptanceOutcome is child_organization. Applies only when acceptanceOutcome is child_organization; ignored otherwise. When this property is omitted or empty, the child is named “My Organization”. When present and non-empty, that string is the child organization’s name at creation. Administrators can rename the child afterward.
`createdAt`	string (date-time)	Yes	Timestamp when the invitation was created.
`deletedAt`	string \| null (date-time)	Yes	Timestamp when the invitation was deleted, if applicable.
`description`	string	Yes	Description of the invitation, which can be used to provide additional context. Null or empty string means the invitation does not have a description.
`emails`	array of string \| null	Yes	Email addresses or patterns for which the invitation is valid. Null means the invitation is valid for any email address.
`expiresAt`	string \| null (date-time)	No	Timestamp when the invitation expires, if applicable. Null or empty means the invitation does not expire.
`id`	string (uuid)	Yes	Unique identifier for the invitation, also used as the invitation code.
`isDefault`	boolean	No	Indicates whether the invitation is a default invitation (open invite), which can be used to assign users when signing up from fqdn or custom domain. An organization can only have one default invitation.
`name`	string	Yes	Name of the invitation, which can be used to identify it. Required; cannot be an empty string.
`orgId`	string (uuid)	Yes	ID of the organization to which the user is invited.
`owner`	string (uuid)	Yes	ID of the user who created the invitation. Tracks who created the invitation for auditing purposes.
`quota`	integer	No	Quota for the invitation; limits the number of users that can accept it. Null or empty means the invitation is unlimited.
`roles`	array of string	Yes	Roles that the user will have when accepting the invitation. Empty means the invitation does not specify any roles.
`status`	string	Yes	Activation status of the invitation.
`teams`	array of string	Yes	Teams that the user will be added to when accepting the invitation. Empty means the invitation does not specify any teams.
`updatedAt`	string (date-time)	Yes	Timestamp when the invitation was last updated.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/organizations/invitations/{invitationId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/organizations/invitations/{invitationId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/organizations/invitations/{invitationId}

Parameters

Path parameters

Name	Type	Required	Description
`invitationId`	string (uuid)	Yes	The ID of the invitation.

Request body

application/json Required

Payload for creating or updating an invitation.

Field	Type	Required	Description
`acceptanceOutcome`	string	No	Determines what accepting this invitation does for the accepting user, for new and existing accounts alike. direct_membership (the default, and the behavior of every invitation that omits this property) adds the user to the inviting organization. child_organization creates a new child organization for the user whose parent is always the inviting organization; the child follows the standard organization-creation procedure (a My Team team, a My Workspace workspace, and the accepting user as its owner with organization administrator privileges). The child’s display name is set by childOrganizationName when present and non-empty; otherwise it defaults to “My Organization”. With child_organization the invitation’s roles and teams apply in the child organization, not in the inviting organization.
`childOrganizationBranding`	string	No	Determines what branding a child organization created by accepting this invitation starts with. Applies only when acceptanceOutcome is child_organization; ignored otherwise. parent (the default, including every invitation that omits this property) copies the inviting organization’s branding into the child at creation: theme (logos and colors), authentication-page branding, email branding (sender name, templates, and footer), links (including social profiles), and the authentication-page carousel setting. provider copies the provider organization’s branding instead. none gives the child no branding of its own. Every copy is a snapshot: later changes to the source do not propagate, and the child’s administrators can change its branding afterwards without affecting the source.
`childOrganizationName`	string	No	Display name for the child organization created when acceptanceOutcome is child_organization. Applies only when acceptanceOutcome is child_organization; ignored otherwise. When this property is omitted or empty, the child is named “My Organization”. When present and non-empty, that string is the child organization’s name at creation. Administrators can rename the child afterward.
`description`	string	No	Description of the invitation. Optional; omitting it stores an empty description.
`emails`	array of string	No	Email addresses or patterns this invitation is valid for. Optional; omitting it or sending an empty list means any email address may accept the invitation.
`expiresAt`	string (date-time)	No	Timestamp when the invitation expires, if applicable.
`id`	string (uuid)	No	Existing invitation ID for updates; omit on create.
`isDefault`	boolean	No	Indicates whether the invitation is a default invitation (open invite).
`name`	string	Yes	Name of the invitation.
`orgId`	string (uuid)	Yes	ID of the organization to which the user is invited.
`owner`	string (uuid)	No	ID of the user who created the invitation.
`quota`	integer	No	Quota for the invitation; limits the number of users that can accept it.
`roles`	array of string	No	Roles that the user will have when accepting the invitation. Optional; omitting it or sending an empty list grants no roles.
`status`	string	Yes	Activation status of the invitation.
`teams`	array of string	No	Teams that the user will be added to when accepting the invitation. Optional; omitting it or sending an empty list adds the user to no teams.

Returned data

Responses

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

Invitation entity schema.

Field	Type	Required	Description
`acceptanceOutcome`	string	No	Determines what accepting this invitation does for the accepting user, for new and existing accounts alike. direct_membership (the default, and the behavior of every invitation that omits this property) adds the user to the inviting organization. child_organization creates a new child organization for the user whose parent is always the inviting organization; the child follows the standard organization-creation procedure (a My Team team, a My Workspace workspace, and the accepting user as its owner with organization administrator privileges). The child’s display name is set by childOrganizationName when present and non-empty; otherwise it defaults to “My Organization”. With child_organization the invitation’s roles and teams apply in the child organization, not in the inviting organization.
`acceptedBy`	array of string	Yes	List of user ids that have already accepted the invitation. Empty means the invitation has not been used yet.
`childOrganizationBranding`	string	No	Determines what branding a child organization created by accepting this invitation starts with. Applies only when acceptanceOutcome is child_organization; ignored otherwise. parent (the default, including every invitation that omits this property) copies the inviting organization’s branding into the child at creation: theme (logos and colors), authentication-page branding, email branding (sender name, templates, and footer), links (including social profiles), and the authentication-page carousel setting. provider copies the provider organization’s branding instead. none gives the child no branding of its own. Every copy is a snapshot: later changes to the source do not propagate, and the child’s administrators can change its branding afterwards without affecting the source.
`childOrganizationName`	string	No	Display name for the child organization created when acceptanceOutcome is child_organization. Applies only when acceptanceOutcome is child_organization; ignored otherwise. When this property is omitted or empty, the child is named “My Organization”. When present and non-empty, that string is the child organization’s name at creation. Administrators can rename the child afterward.
`createdAt`	string (date-time)	Yes	Timestamp when the invitation was created.
`deletedAt`	string \| null (date-time)	Yes	Timestamp when the invitation was deleted, if applicable.
`description`	string	Yes	Description of the invitation, which can be used to provide additional context. Null or empty string means the invitation does not have a description.
`emails`	array of string \| null	Yes	Email addresses or patterns for which the invitation is valid. Null means the invitation is valid for any email address.
`expiresAt`	string \| null (date-time)	No	Timestamp when the invitation expires, if applicable. Null or empty means the invitation does not expire.
`id`	string (uuid)	Yes	Unique identifier for the invitation, also used as the invitation code.
`isDefault`	boolean	No	Indicates whether the invitation is a default invitation (open invite), which can be used to assign users when signing up from fqdn or custom domain. An organization can only have one default invitation.
`name`	string	Yes	Name of the invitation, which can be used to identify it. Required; cannot be an empty string.
`orgId`	string (uuid)	Yes	ID of the organization to which the user is invited.
`owner`	string (uuid)	Yes	ID of the user who created the invitation. Tracks who created the invitation for auditing purposes.
`quota`	integer	No	Quota for the invitation; limits the number of users that can accept it. Null or empty means the invitation is unlimited.
`roles`	array of string	Yes	Roles that the user will have when accepting the invitation. Empty means the invitation does not specify any roles.
`status`	string	Yes	Activation status of the invitation.
`teams`	array of string	Yes	Teams that the user will be added to when accepting the invitation. Empty means the invitation does not specify any teams.
`updatedAt`	string (date-time)	Yes	Timestamp when the invitation was last updated.

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.

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.

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.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/organizations/invitations/{invitationId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/organizations/invitations/{invitationId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/organizations/invitations/{invitationId}

Parameters

Path parameters

Name	Type	Required	Description
`invitationId`	string (uuid)	Yes	The ID of the invitation.

Returned data

Responses

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

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/organizations/invitations/{invitationId}/accept

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/organizations/invitations/{invitationId}/accept

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/organizations/invitations/{invitationId}/accept

Parameters

Path parameters

Name	Type	Required	Description
`invitationId`	string (uuid)	Yes	The ID of the invitation.

Returned data

Responses

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

Invitation entity schema.

Field	Type	Required	Description
`acceptanceOutcome`	string	No	Determines what accepting this invitation does for the accepting user, for new and existing accounts alike. direct_membership (the default, and the behavior of every invitation that omits this property) adds the user to the inviting organization. child_organization creates a new child organization for the user whose parent is always the inviting organization; the child follows the standard organization-creation procedure (a My Team team, a My Workspace workspace, and the accepting user as its owner with organization administrator privileges). The child’s display name is set by childOrganizationName when present and non-empty; otherwise it defaults to “My Organization”. With child_organization the invitation’s roles and teams apply in the child organization, not in the inviting organization.
`acceptedBy`	array of string	Yes	List of user ids that have already accepted the invitation. Empty means the invitation has not been used yet.
`childOrganizationBranding`	string	No	Determines what branding a child organization created by accepting this invitation starts with. Applies only when acceptanceOutcome is child_organization; ignored otherwise. parent (the default, including every invitation that omits this property) copies the inviting organization’s branding into the child at creation: theme (logos and colors), authentication-page branding, email branding (sender name, templates, and footer), links (including social profiles), and the authentication-page carousel setting. provider copies the provider organization’s branding instead. none gives the child no branding of its own. Every copy is a snapshot: later changes to the source do not propagate, and the child’s administrators can change its branding afterwards without affecting the source.
`childOrganizationName`	string	No	Display name for the child organization created when acceptanceOutcome is child_organization. Applies only when acceptanceOutcome is child_organization; ignored otherwise. When this property is omitted or empty, the child is named “My Organization”. When present and non-empty, that string is the child organization’s name at creation. Administrators can rename the child afterward.
`createdAt`	string (date-time)	Yes	Timestamp when the invitation was created.
`deletedAt`	string \| null (date-time)	Yes	Timestamp when the invitation was deleted, if applicable.
`description`	string	Yes	Description of the invitation, which can be used to provide additional context. Null or empty string means the invitation does not have a description.
`emails`	array of string \| null	Yes	Email addresses or patterns for which the invitation is valid. Null means the invitation is valid for any email address.
`expiresAt`	string \| null (date-time)	No	Timestamp when the invitation expires, if applicable. Null or empty means the invitation does not expire.
`id`	string (uuid)	Yes	Unique identifier for the invitation, also used as the invitation code.
`isDefault`	boolean	No	Indicates whether the invitation is a default invitation (open invite), which can be used to assign users when signing up from fqdn or custom domain. An organization can only have one default invitation.
`name`	string	Yes	Name of the invitation, which can be used to identify it. Required; cannot be an empty string.
`orgId`	string (uuid)	Yes	ID of the organization to which the user is invited.
`owner`	string (uuid)	Yes	ID of the user who created the invitation. Tracks who created the invitation for auditing purposes.
`quota`	integer	No	Quota for the invitation; limits the number of users that can accept it. Null or empty means the invitation is unlimited.
`roles`	array of string	Yes	Roles that the user will have when accepting the invitation. Empty means the invitation does not specify any roles.
`status`	string	Yes	Activation status of the invitation.
`teams`	array of string	Yes	Teams that the user will be added to when accepting the invitation. Empty means the invitation does not specify any teams.
`updatedAt`	string (date-time)	Yes	Timestamp when the invitation was last updated.

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.

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.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/orgs/{orgId}/environments/mail-relay

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/orgs/{orgId}/environments/mail-relay

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/orgs/{orgId}/environments/mail-relay

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.

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"
}

Organization SMTP Configuration OrganizationSmtp DELETE

/api/orgs/{orgId}/environments/mail-relay

Remove an organization's mail server entirely

Removes the configuration, its stored credential and the environment that held them, together. The organization’s mail reverts to the provider’s shared relay. Idempotent, and deliberately declares no 404: removing an absent configuration succeeds with the same 204 as removing a present one, so “not found” is not an outcome this operation has. An unknown or unauthorized organization is answered by the permission middleware before the handler runs.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/orgs/{orgId}/environments/mail-relay

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/orgs/{orgId}/environments/mail-relay

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/orgs/{orgId}/environments/mail-relay

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/orgs/{orgId}/environments/mail-relay/connection

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/orgs/{orgId}/environments/mail-relay/connection

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/orgs/{orgId}/environments/mail-relay/connection

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.

An organization’s own outbound mail server. When present and healthy, every transactional email whose reader belongs to this organization - application notifications and identity-flow mail (account verification, password recovery) alike - is delivered through this server rather than through the provider’s shared relay, so the message leaves from the organization’s own domain. At most one live configuration exists per organization. The SMTP password is encrypted at rest and is never returned; reads always carry the redaction sentinel instead.

This is a WIRE contract only. It is not backed by a table of its own: the configuration is stored on the same environment/connection/credential chain that bring-your-own identity providers already uses - a well-known per-organization Environment, joined through environments_connections_mappings to a Connection whose credential_id points at a Credential. The organization relationship lives on environments.organization_id, the dial target on connections.url and connections.metadata, the transport verdict on connections.status, and the password alone in credentials.secret.

No property here carries a construct-specific db tag, because no property here names a column of its own. The exception is deliberate and inherited: createdAt and updatedAt $ref the shared core definitions, which declare db: created_at / db: updated_at for every construct that uses them, and those two tags are accurate for the underlying connection row.

Field	Type	Required	Description
`id`	string (uuid)	Yes	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.
`host`	string	Yes	Hostname of the organization’s SMTP server.
`port`	integer	Yes	TCP port the organization’s SMTP server listens on. The server additionally restricts this to a submission-port allowlist; a syntactically valid port outside it is refused.
`encryption`	string	Yes	Transport encryption to negotiate. `starttls` upgrades a cleartext connection (typically port 587), `tls` opens an implicit TLS connection (typically port 465), and `none` sends in cleartext and is intended only for an internal relay on a trusted network.
`authMechanism`	string	Yes	SMTP authentication mechanism. `none` is permitted only for a relay that authorizes by source address; a configuration using any other mechanism must carry both a username and a password.
`username`	string	No	Username presented to the organization’s SMTP server. Held beside the host rather than with the password because it is an identifier rather than a secret, and the health surface must show it without a decryption round trip. It is usually an email address, so it is returned only on an authorized read.
`password`	string	No	Present only when a password is stored, and then always the redaction sentinel `***` - never the stored value, which is encrypted at rest and is never projected into a response. Its presence is therefore the only thing it reports: a configuration whose `authMechanism` is `none` stores no password and omits this property entirely. It is optional rather than required for exactly that reason. Read-only, and read-only here means read-only: no request body references this schema. The write semantics belong to the payload schemas - `OrganizationSmtpConfigurationPayload` on create and `OrganizationSmtpCredentialPayload` on rotation - and are documented there.
`fromAddress`	string (email)	Yes	Address the organization’s mail is sent from. Its domain must be verified before mail is routed through this server.
`fromDisplayName`	string	No	Display name shown alongside the from address in the message header.
`replyToAddress`	string (email)	No	Address replies are directed to. It is also the address carried when a message falls back to the provider relay, which rewrites the from address to the provider’s own so the message stays aligned for SPF and DMARC.
`status`	string	Yes	Lifecycle and transport verdict, carrying the connection status vocabulary because the configuration IS a connection. `registered` means configured but never proven - the from domain is unverified, or no message has yet been delivered - and mail takes the provider relay. `connected` means the last delivery attempt succeeded and mail is routed through this server. `disconnected` means the most recent delivery attempt did not succeed, and `fallbackToProvider` governs what becomes of that message. It is a verdict on the last attempt alone: a SINGLE failure records it, there is no failure threshold, and the status does not by itself stop the server being dialled for the next message. Read it as “the last attempt failed”, not as “this server has been taken out of rotation” - the circuit breaker that would do the latter is planned, not built, and is tracked in meshery-cloud#6057. `ignored` means an administrator turned it off. The writers are disjoint on purpose: only an administrator writes `ignored`, and only a delivery outcome writes `connected` or `disconnected`. That is what keeps a deliberate opt-out distinguishable from a failing relay. It also makes “enabled while the from domain is unverified” unrepresentable rather than merely forbidden, which is why this property replaces the separate `enabled` and `verificationState` pair it supersedes.
`fallbackToProvider`	boolean	Yes	Whether a message that this server fails to accept is re-sent through the provider’s shared relay. Disabling it means the organization owns delivery entirely and a failure is a dropped message, including account verification and password recovery.
`fromDomain`	string	No	Registrable domain of the from address, held separately as the unit that ownership is proven for.
`fromDomainVerificationToken`	string	No	Token the organization publishes in DNS to prove control of the from domain. Not a credential - it authorizes nothing and grants no access.
`fromDomainVerifiedAt`	string \| null (date-time)	No	Timestamp at which control of the from domain was last proven. Null while unproven.
`lastSuccessAt`	string \| null (date-time)	No	Timestamp of the last message this server accepted.
`lastFailureAt`	string \| null (date-time)	No	Timestamp of the last delivery attempt this server rejected or failed to accept.
`lastFailureReason`	string	No	Classification of the last failure. Always a classification, never the remote server’s own message: the set is closed on purpose, because reporting a remote server’s text back to a caller would turn a refusal into an oracle for what the network can reach.
`consecutiveFailures`	integer	Yes	Count of delivery attempts that have failed since the last success, reset to zero by a success. It is a RECORD and nothing more: no threshold reads it, and reaching any particular value does not itself stop a persistently unreachable server being dialled. A consumer must not treat a non-zero count as protection already in place. The circuit breaker that would consume this count - and which needs a threshold, a reset policy, and a decision about its interaction with `fallbackToProvider`, where an open circuit with fallback off drops account-verification and password-recovery mail - is planned under meshery-cloud#6057.
`createdBy`	string \| null (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`createdAt`	string (date-time)	Yes	Timestamp when the configuration was created.
`updatedAt`	string (date-time)	Yes	Timestamp when the configuration was last changed.
`deletedAt`	string \| null (date-time)	No	Timestamp when the configuration was soft deleted. Null while it remains active.

Example response

{
  "authMechanism": "plain",
  "consecutiveFailures": 0,
  "createdAt": "0001-01-01T00:00:00Z",
  "createdBy": "00000000-0000-0000-0000-000000000000",
  "deletedAt": null,
  "encryption": "starttls",
  "fallbackToProvider": true,
  "fromAddress": "[email protected]",
  "fromDisplayName": "Example Corp",
  "fromDomain": "example.com",
  "fromDomainVerificationToken": "0f6a5d2c9b1e4a7f8c3d6b0e2a4f7c19",
  "fromDomainVerifiedAt": null,
  "host": "smtp.example.com",
  "id": "00000000-0000-0000-0000-000000000000",
  "lastFailureAt": null,
  "lastSuccessAt": null,
  "organizationId": "00000000-0000-0000-0000-000000000000",
  "password": "***",
  "port": 587,
  "replyToAddress": "[email protected]",
  "status": "registered",
  "updatedAt": "0001-01-01T00:00:00Z",
  "username": "[email protected]"
}

Organization SMTP Configuration OrganizationSmtp POST

/api/orgs/{orgId}/environments/mail-relay/connection

Register an organization's SMTP server

Creates the configuration, provisioning the mail-relay environment on the organization’s behalf when it does not yet exist. This is the only operation that accepts the password alongside the settings; afterwards the two are written separately. The new configuration starts unproven, so mail continues to take the provider relay until the from domain is verified and a test delivery succeeds. Declares no 404 for the same reason the delete does not: this operation brings the configuration into existence, so its absence beforehand is the normal case rather than an error.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/orgs/{orgId}/environments/mail-relay/connection

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/orgs/{orgId}/environments/mail-relay/connection

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/orgs/{orgId}/environments/mail-relay/connection

Parameters

Path parameters

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

Request body

application/json Required

Everything needed to register an organization’s mail server, settings and password together, so that registration is one operation. Accepted only on create; afterwards the settings and the credential are written by separate operations. status, the delivery counters behind it, the from-domain proof and the timestamps are all server-owned and are not accepted here. A new configuration therefore always starts at registered, whatever the caller sends.

Field	Type	Required	Description
`host`	string	Yes	Hostname of the organization’s SMTP server.
`port`	integer	Yes	TCP port the organization’s SMTP server listens on. Restricted further by a submission-port allowlist.
`encryption`	string	No	Transport encryption to negotiate. `starttls` upgrades a cleartext connection (typically port 587), `tls` opens an implicit TLS connection (typically port 465), and `none` sends in cleartext.
`authMechanism`	string	No	SMTP authentication mechanism. Any mechanism other than `none` requires both a username and a password.
`username`	string	No	Username presented to the organization’s SMTP server. Required by the server, together with `password`, for every `authMechanism` other than `none`; see that property for why the pairing is a server-enforced contract rather than a schema constraint.
`password`	string	No	Password presented to the organization’s SMTP server. The server requires it, together with `username`, for every `authMechanism` other than `none`, and answers 400 when either is missing. That rule is deliberately NOT encoded in `required` or as a `oneOf`/`if`-`then`. Both encodings were measured against the generator: `if`/`then` collapses this payload to `interface{}`, and `oneOf` injects a `union json.RawMessage` field with a custom marshaller, either of which costs every consumer its generated type or its wire behaviour to express a constraint the server enforces anyway. Treat this property as conditionally required by contract, not by schema. This is the ONLY operation that accepts the password alongside the settings, so that registering a mail server is one call and no configuration exists in a state where it is expected to send but holds no credential. Afterwards the password is written only by the rotation operation, never by the settings update, whose payload declares no `password` property at all. The redaction sentinel `***` is refused, and so is the empty string - omit the property instead of sending it empty, which the `minLength` below enforces so this payload and the rotation payload agree.
`fromAddress`	string (email)	Yes	Address the organization’s mail is sent from.
`fromDisplayName`	string	No	Display name shown alongside the from address.
`replyToAddress`	string (email)	No	Address replies are directed to.
`fallbackToProvider`	boolean	No	Whether a message this server fails to accept is re-sent through the provider’s shared relay. Disabling it means a failure is a dropped message, account verification and password recovery included.

Returned data

Responses

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

An organization’s own outbound mail server. When present and healthy, every transactional email whose reader belongs to this organization - application notifications and identity-flow mail (account verification, password recovery) alike - is delivered through this server rather than through the provider’s shared relay, so the message leaves from the organization’s own domain. At most one live configuration exists per organization. The SMTP password is encrypted at rest and is never returned; reads always carry the redaction sentinel instead.

This is a WIRE contract only. It is not backed by a table of its own: the configuration is stored on the same environment/connection/credential chain that bring-your-own identity providers already uses - a well-known per-organization Environment, joined through environments_connections_mappings to a Connection whose credential_id points at a Credential. The organization relationship lives on environments.organization_id, the dial target on connections.url and connections.metadata, the transport verdict on connections.status, and the password alone in credentials.secret.

No property here carries a construct-specific db tag, because no property here names a column of its own. The exception is deliberate and inherited: createdAt and updatedAt $ref the shared core definitions, which declare db: created_at / db: updated_at for every construct that uses them, and those two tags are accurate for the underlying connection row.

Field	Type	Required	Description
`id`	string (uuid)	Yes	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.
`host`	string	Yes	Hostname of the organization’s SMTP server.
`port`	integer	Yes	TCP port the organization’s SMTP server listens on. The server additionally restricts this to a submission-port allowlist; a syntactically valid port outside it is refused.
`encryption`	string	Yes	Transport encryption to negotiate. `starttls` upgrades a cleartext connection (typically port 587), `tls` opens an implicit TLS connection (typically port 465), and `none` sends in cleartext and is intended only for an internal relay on a trusted network.
`authMechanism`	string	Yes	SMTP authentication mechanism. `none` is permitted only for a relay that authorizes by source address; a configuration using any other mechanism must carry both a username and a password.
`username`	string	No	Username presented to the organization’s SMTP server. Held beside the host rather than with the password because it is an identifier rather than a secret, and the health surface must show it without a decryption round trip. It is usually an email address, so it is returned only on an authorized read.
`password`	string	No	Present only when a password is stored, and then always the redaction sentinel `***` - never the stored value, which is encrypted at rest and is never projected into a response. Its presence is therefore the only thing it reports: a configuration whose `authMechanism` is `none` stores no password and omits this property entirely. It is optional rather than required for exactly that reason. Read-only, and read-only here means read-only: no request body references this schema. The write semantics belong to the payload schemas - `OrganizationSmtpConfigurationPayload` on create and `OrganizationSmtpCredentialPayload` on rotation - and are documented there.
`fromAddress`	string (email)	Yes	Address the organization’s mail is sent from. Its domain must be verified before mail is routed through this server.
`fromDisplayName`	string	No	Display name shown alongside the from address in the message header.
`replyToAddress`	string (email)	No	Address replies are directed to. It is also the address carried when a message falls back to the provider relay, which rewrites the from address to the provider’s own so the message stays aligned for SPF and DMARC.
`status`	string	Yes	Lifecycle and transport verdict, carrying the connection status vocabulary because the configuration IS a connection. `registered` means configured but never proven - the from domain is unverified, or no message has yet been delivered - and mail takes the provider relay. `connected` means the last delivery attempt succeeded and mail is routed through this server. `disconnected` means the most recent delivery attempt did not succeed, and `fallbackToProvider` governs what becomes of that message. It is a verdict on the last attempt alone: a SINGLE failure records it, there is no failure threshold, and the status does not by itself stop the server being dialled for the next message. Read it as “the last attempt failed”, not as “this server has been taken out of rotation” - the circuit breaker that would do the latter is planned, not built, and is tracked in meshery-cloud#6057. `ignored` means an administrator turned it off. The writers are disjoint on purpose: only an administrator writes `ignored`, and only a delivery outcome writes `connected` or `disconnected`. That is what keeps a deliberate opt-out distinguishable from a failing relay. It also makes “enabled while the from domain is unverified” unrepresentable rather than merely forbidden, which is why this property replaces the separate `enabled` and `verificationState` pair it supersedes.
`fallbackToProvider`	boolean	Yes	Whether a message that this server fails to accept is re-sent through the provider’s shared relay. Disabling it means the organization owns delivery entirely and a failure is a dropped message, including account verification and password recovery.
`fromDomain`	string	No	Registrable domain of the from address, held separately as the unit that ownership is proven for.
`fromDomainVerificationToken`	string	No	Token the organization publishes in DNS to prove control of the from domain. Not a credential - it authorizes nothing and grants no access.
`fromDomainVerifiedAt`	string \| null (date-time)	No	Timestamp at which control of the from domain was last proven. Null while unproven.
`lastSuccessAt`	string \| null (date-time)	No	Timestamp of the last message this server accepted.
`lastFailureAt`	string \| null (date-time)	No	Timestamp of the last delivery attempt this server rejected or failed to accept.
`lastFailureReason`	string	No	Classification of the last failure. Always a classification, never the remote server’s own message: the set is closed on purpose, because reporting a remote server’s text back to a caller would turn a refusal into an oracle for what the network can reach.
`consecutiveFailures`	integer	Yes	Count of delivery attempts that have failed since the last success, reset to zero by a success. It is a RECORD and nothing more: no threshold reads it, and reaching any particular value does not itself stop a persistently unreachable server being dialled. A consumer must not treat a non-zero count as protection already in place. The circuit breaker that would consume this count - and which needs a threshold, a reset policy, and a decision about its interaction with `fallbackToProvider`, where an open circuit with fallback off drops account-verification and password-recovery mail - is planned under meshery-cloud#6057.
`createdBy`	string \| null (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`createdAt`	string (date-time)	Yes	Timestamp when the configuration was created.
`updatedAt`	string (date-time)	Yes	Timestamp when the configuration was last changed.
`deletedAt`	string \| null (date-time)	No	Timestamp when the configuration was soft deleted. Null while it remains active.

Example response

{
  "authMechanism": "plain",
  "consecutiveFailures": 0,
  "createdAt": "0001-01-01T00:00:00Z",
  "createdBy": "00000000-0000-0000-0000-000000000000",
  "deletedAt": null,
  "encryption": "starttls",
  "fallbackToProvider": true,
  "fromAddress": "[email protected]",
  "fromDisplayName": "Example Corp",
  "fromDomain": "example.com",
  "fromDomainVerificationToken": "0f6a5d2c9b1e4a7f8c3d6b0e2a4f7c19",
  "fromDomainVerifiedAt": null,
  "host": "smtp.example.com",
  "id": "00000000-0000-0000-0000-000000000000",
  "lastFailureAt": null,
  "lastSuccessAt": null,
  "organizationId": "00000000-0000-0000-0000-000000000000",
  "password": "***",
  "port": 587,
  "replyToAddress": "[email protected]",
  "status": "registered",
  "updatedAt": "0001-01-01T00:00:00Z",
  "username": "[email protected]"
}

Organization SMTP Configuration OrganizationSmtp PUT

/api/orgs/{orgId}/environments/mail-relay/connection

Update an organization's SMTP settings

Replaces the settings. The payload has no password property at all and rejects unknown properties, so this operation cannot carry a credential even by accident - rotating the password is a separate operation. That is what lets an administrator rename a display name without retyping a secret, while the redaction sentinel stays refused everywhere it can be written. Changing the from address to a different registrable domain resets from-domain verification and returns the configuration to registered.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/orgs/{orgId}/environments/mail-relay/connection

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/orgs/{orgId}/environments/mail-relay/connection

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/orgs/{orgId}/environments/mail-relay/connection

Parameters

Path parameters

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

Request body

application/json Required

Client-settable settings of an organization’s mail server, WITHOUT the password. The omission is deliberate and structural: because this schema forbids unknown properties, a client cannot send a credential through this operation at all, so the read-then-write round trip that would otherwise overwrite a stored password with the redaction sentinel is not expressible. Rotate the password through its own operation.

Field	Type	Required	Description
`host`	string	Yes	Hostname of the organization’s SMTP server.
`port`	integer	Yes	TCP port the organization’s SMTP server listens on. Restricted further by a submission-port allowlist.
`encryption`	string	No	Transport encryption to negotiate.
`authMechanism`	string	No	SMTP authentication mechanism. Changing this to a mechanism other than `none` while no password is stored is refused; rotate the credential first.
`username`	string	No	Username presented to the organization’s SMTP server.
`fromAddress`	string (email)	Yes	Address the organization’s mail is sent from. Changing it to a different registrable domain resets from-domain verification.
`fromDisplayName`	string	No	Display name shown alongside the from address.
`replyToAddress`	string (email)	No	Address replies are directed to.
`fallbackToProvider`	boolean	No	Whether a message this server fails to accept is re-sent through the provider’s shared relay.

Returned data

Responses

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

An organization’s own outbound mail server. When present and healthy, every transactional email whose reader belongs to this organization - application notifications and identity-flow mail (account verification, password recovery) alike - is delivered through this server rather than through the provider’s shared relay, so the message leaves from the organization’s own domain. At most one live configuration exists per organization. The SMTP password is encrypted at rest and is never returned; reads always carry the redaction sentinel instead.

This is a WIRE contract only. It is not backed by a table of its own: the configuration is stored on the same environment/connection/credential chain that bring-your-own identity providers already uses - a well-known per-organization Environment, joined through environments_connections_mappings to a Connection whose credential_id points at a Credential. The organization relationship lives on environments.organization_id, the dial target on connections.url and connections.metadata, the transport verdict on connections.status, and the password alone in credentials.secret.

No property here carries a construct-specific db tag, because no property here names a column of its own. The exception is deliberate and inherited: createdAt and updatedAt $ref the shared core definitions, which declare db: created_at / db: updated_at for every construct that uses them, and those two tags are accurate for the underlying connection row.

Field	Type	Required	Description
`id`	string (uuid)	Yes	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.
`host`	string	Yes	Hostname of the organization’s SMTP server.
`port`	integer	Yes	TCP port the organization’s SMTP server listens on. The server additionally restricts this to a submission-port allowlist; a syntactically valid port outside it is refused.
`encryption`	string	Yes	Transport encryption to negotiate. `starttls` upgrades a cleartext connection (typically port 587), `tls` opens an implicit TLS connection (typically port 465), and `none` sends in cleartext and is intended only for an internal relay on a trusted network.
`authMechanism`	string	Yes	SMTP authentication mechanism. `none` is permitted only for a relay that authorizes by source address; a configuration using any other mechanism must carry both a username and a password.
`username`	string	No	Username presented to the organization’s SMTP server. Held beside the host rather than with the password because it is an identifier rather than a secret, and the health surface must show it without a decryption round trip. It is usually an email address, so it is returned only on an authorized read.
`password`	string	No	Present only when a password is stored, and then always the redaction sentinel `***` - never the stored value, which is encrypted at rest and is never projected into a response. Its presence is therefore the only thing it reports: a configuration whose `authMechanism` is `none` stores no password and omits this property entirely. It is optional rather than required for exactly that reason. Read-only, and read-only here means read-only: no request body references this schema. The write semantics belong to the payload schemas - `OrganizationSmtpConfigurationPayload` on create and `OrganizationSmtpCredentialPayload` on rotation - and are documented there.
`fromAddress`	string (email)	Yes	Address the organization’s mail is sent from. Its domain must be verified before mail is routed through this server.
`fromDisplayName`	string	No	Display name shown alongside the from address in the message header.
`replyToAddress`	string (email)	No	Address replies are directed to. It is also the address carried when a message falls back to the provider relay, which rewrites the from address to the provider’s own so the message stays aligned for SPF and DMARC.
`status`	string	Yes	Lifecycle and transport verdict, carrying the connection status vocabulary because the configuration IS a connection. `registered` means configured but never proven - the from domain is unverified, or no message has yet been delivered - and mail takes the provider relay. `connected` means the last delivery attempt succeeded and mail is routed through this server. `disconnected` means the most recent delivery attempt did not succeed, and `fallbackToProvider` governs what becomes of that message. It is a verdict on the last attempt alone: a SINGLE failure records it, there is no failure threshold, and the status does not by itself stop the server being dialled for the next message. Read it as “the last attempt failed”, not as “this server has been taken out of rotation” - the circuit breaker that would do the latter is planned, not built, and is tracked in meshery-cloud#6057. `ignored` means an administrator turned it off. The writers are disjoint on purpose: only an administrator writes `ignored`, and only a delivery outcome writes `connected` or `disconnected`. That is what keeps a deliberate opt-out distinguishable from a failing relay. It also makes “enabled while the from domain is unverified” unrepresentable rather than merely forbidden, which is why this property replaces the separate `enabled` and `verificationState` pair it supersedes.
`fallbackToProvider`	boolean	Yes	Whether a message that this server fails to accept is re-sent through the provider’s shared relay. Disabling it means the organization owns delivery entirely and a failure is a dropped message, including account verification and password recovery.
`fromDomain`	string	No	Registrable domain of the from address, held separately as the unit that ownership is proven for.
`fromDomainVerificationToken`	string	No	Token the organization publishes in DNS to prove control of the from domain. Not a credential - it authorizes nothing and grants no access.
`fromDomainVerifiedAt`	string \| null (date-time)	No	Timestamp at which control of the from domain was last proven. Null while unproven.
`lastSuccessAt`	string \| null (date-time)	No	Timestamp of the last message this server accepted.
`lastFailureAt`	string \| null (date-time)	No	Timestamp of the last delivery attempt this server rejected or failed to accept.
`lastFailureReason`	string	No	Classification of the last failure. Always a classification, never the remote server’s own message: the set is closed on purpose, because reporting a remote server’s text back to a caller would turn a refusal into an oracle for what the network can reach.
`consecutiveFailures`	integer	Yes	Count of delivery attempts that have failed since the last success, reset to zero by a success. It is a RECORD and nothing more: no threshold reads it, and reaching any particular value does not itself stop a persistently unreachable server being dialled. A consumer must not treat a non-zero count as protection already in place. The circuit breaker that would consume this count - and which needs a threshold, a reset policy, and a decision about its interaction with `fallbackToProvider`, where an open circuit with fallback off drops account-verification and password-recovery mail - is planned under meshery-cloud#6057.
`createdBy`	string \| null (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`createdAt`	string (date-time)	Yes	Timestamp when the configuration was created.
`updatedAt`	string (date-time)	Yes	Timestamp when the configuration was last changed.
`deletedAt`	string \| null (date-time)	No	Timestamp when the configuration was soft deleted. Null while it remains active.

Example response

{
  "authMechanism": "plain",
  "consecutiveFailures": 0,
  "createdAt": "0001-01-01T00:00:00Z",
  "createdBy": "00000000-0000-0000-0000-000000000000",
  "deletedAt": null,
  "encryption": "starttls",
  "fallbackToProvider": true,
  "fromAddress": "[email protected]",
  "fromDisplayName": "Example Corp",
  "fromDomain": "example.com",
  "fromDomainVerificationToken": "0f6a5d2c9b1e4a7f8c3d6b0e2a4f7c19",
  "fromDomainVerifiedAt": null,
  "host": "smtp.example.com",
  "id": "00000000-0000-0000-0000-000000000000",
  "lastFailureAt": null,
  "lastSuccessAt": null,
  "organizationId": "00000000-0000-0000-0000-000000000000",
  "password": "***",
  "port": 587,
  "replyToAddress": "[email protected]",
  "status": "registered",
  "updatedAt": "0001-01-01T00:00:00Z",
  "username": "[email protected]"
}

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/orgs/{orgId}/environments/mail-relay/connection/credential

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/orgs/{orgId}/environments/mail-relay/connection/credential

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/orgs/{orgId}/environments/mail-relay/connection/credential

Parameters

Path parameters

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

Request body

application/json Required

The password presented to an organization’s SMTP server. The only payload that carries it after creation.

Field	Type	Required	Description
`password`	string	Yes	New password. The redaction sentinel `***` and the empty string are refused with a 400 rather than treated as “leave the stored value alone”, so echoing a read back cannot erase the credential.

Returned data

Responses

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

An organization’s own outbound mail server. When present and healthy, every transactional email whose reader belongs to this organization - application notifications and identity-flow mail (account verification, password recovery) alike - is delivered through this server rather than through the provider’s shared relay, so the message leaves from the organization’s own domain. At most one live configuration exists per organization. The SMTP password is encrypted at rest and is never returned; reads always carry the redaction sentinel instead.

This is a WIRE contract only. It is not backed by a table of its own: the configuration is stored on the same environment/connection/credential chain that bring-your-own identity providers already uses - a well-known per-organization Environment, joined through environments_connections_mappings to a Connection whose credential_id points at a Credential. The organization relationship lives on environments.organization_id, the dial target on connections.url and connections.metadata, the transport verdict on connections.status, and the password alone in credentials.secret.

No property here carries a construct-specific db tag, because no property here names a column of its own. The exception is deliberate and inherited: createdAt and updatedAt $ref the shared core definitions, which declare db: created_at / db: updated_at for every construct that uses them, and those two tags are accurate for the underlying connection row.

Field	Type	Required	Description
`id`	string (uuid)	Yes	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.
`host`	string	Yes	Hostname of the organization’s SMTP server.
`port`	integer	Yes	TCP port the organization’s SMTP server listens on. The server additionally restricts this to a submission-port allowlist; a syntactically valid port outside it is refused.
`encryption`	string	Yes	Transport encryption to negotiate. `starttls` upgrades a cleartext connection (typically port 587), `tls` opens an implicit TLS connection (typically port 465), and `none` sends in cleartext and is intended only for an internal relay on a trusted network.
`authMechanism`	string	Yes	SMTP authentication mechanism. `none` is permitted only for a relay that authorizes by source address; a configuration using any other mechanism must carry both a username and a password.
`username`	string	No	Username presented to the organization’s SMTP server. Held beside the host rather than with the password because it is an identifier rather than a secret, and the health surface must show it without a decryption round trip. It is usually an email address, so it is returned only on an authorized read.
`password`	string	No	Present only when a password is stored, and then always the redaction sentinel `***` - never the stored value, which is encrypted at rest and is never projected into a response. Its presence is therefore the only thing it reports: a configuration whose `authMechanism` is `none` stores no password and omits this property entirely. It is optional rather than required for exactly that reason. Read-only, and read-only here means read-only: no request body references this schema. The write semantics belong to the payload schemas - `OrganizationSmtpConfigurationPayload` on create and `OrganizationSmtpCredentialPayload` on rotation - and are documented there.
`fromAddress`	string (email)	Yes	Address the organization’s mail is sent from. Its domain must be verified before mail is routed through this server.
`fromDisplayName`	string	No	Display name shown alongside the from address in the message header.
`replyToAddress`	string (email)	No	Address replies are directed to. It is also the address carried when a message falls back to the provider relay, which rewrites the from address to the provider’s own so the message stays aligned for SPF and DMARC.
`status`	string	Yes	Lifecycle and transport verdict, carrying the connection status vocabulary because the configuration IS a connection. `registered` means configured but never proven - the from domain is unverified, or no message has yet been delivered - and mail takes the provider relay. `connected` means the last delivery attempt succeeded and mail is routed through this server. `disconnected` means the most recent delivery attempt did not succeed, and `fallbackToProvider` governs what becomes of that message. It is a verdict on the last attempt alone: a SINGLE failure records it, there is no failure threshold, and the status does not by itself stop the server being dialled for the next message. Read it as “the last attempt failed”, not as “this server has been taken out of rotation” - the circuit breaker that would do the latter is planned, not built, and is tracked in meshery-cloud#6057. `ignored` means an administrator turned it off. The writers are disjoint on purpose: only an administrator writes `ignored`, and only a delivery outcome writes `connected` or `disconnected`. That is what keeps a deliberate opt-out distinguishable from a failing relay. It also makes “enabled while the from domain is unverified” unrepresentable rather than merely forbidden, which is why this property replaces the separate `enabled` and `verificationState` pair it supersedes.
`fallbackToProvider`	boolean	Yes	Whether a message that this server fails to accept is re-sent through the provider’s shared relay. Disabling it means the organization owns delivery entirely and a failure is a dropped message, including account verification and password recovery.
`fromDomain`	string	No	Registrable domain of the from address, held separately as the unit that ownership is proven for.
`fromDomainVerificationToken`	string	No	Token the organization publishes in DNS to prove control of the from domain. Not a credential - it authorizes nothing and grants no access.
`fromDomainVerifiedAt`	string \| null (date-time)	No	Timestamp at which control of the from domain was last proven. Null while unproven.
`lastSuccessAt`	string \| null (date-time)	No	Timestamp of the last message this server accepted.
`lastFailureAt`	string \| null (date-time)	No	Timestamp of the last delivery attempt this server rejected or failed to accept.
`lastFailureReason`	string	No	Classification of the last failure. Always a classification, never the remote server’s own message: the set is closed on purpose, because reporting a remote server’s text back to a caller would turn a refusal into an oracle for what the network can reach.
`consecutiveFailures`	integer	Yes	Count of delivery attempts that have failed since the last success, reset to zero by a success. It is a RECORD and nothing more: no threshold reads it, and reaching any particular value does not itself stop a persistently unreachable server being dialled. A consumer must not treat a non-zero count as protection already in place. The circuit breaker that would consume this count - and which needs a threshold, a reset policy, and a decision about its interaction with `fallbackToProvider`, where an open circuit with fallback off drops account-verification and password-recovery mail - is planned under meshery-cloud#6057.
`createdBy`	string \| null (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`createdAt`	string (date-time)	Yes	Timestamp when the configuration was created.
`updatedAt`	string (date-time)	Yes	Timestamp when the configuration was last changed.
`deletedAt`	string \| null (date-time)	No	Timestamp when the configuration was soft deleted. Null while it remains active.

Example response

{
  "authMechanism": "plain",
  "consecutiveFailures": 0,
  "createdAt": "0001-01-01T00:00:00Z",
  "createdBy": "00000000-0000-0000-0000-000000000000",
  "deletedAt": null,
  "encryption": "starttls",
  "fallbackToProvider": true,
  "fromAddress": "[email protected]",
  "fromDisplayName": "Example Corp",
  "fromDomain": "example.com",
  "fromDomainVerificationToken": "0f6a5d2c9b1e4a7f8c3d6b0e2a4f7c19",
  "fromDomainVerifiedAt": null,
  "host": "smtp.example.com",
  "id": "00000000-0000-0000-0000-000000000000",
  "lastFailureAt": null,
  "lastSuccessAt": null,
  "organizationId": "00000000-0000-0000-0000-000000000000",
  "password": "***",
  "port": 587,
  "replyToAddress": "[email protected]",
  "status": "registered",
  "updatedAt": "0001-01-01T00:00:00Z",
  "username": "[email protected]"
}

Organization SMTP Configuration OrganizationSmtp POST

/api/orgs/{orgId}/environments/mail-relay/connection/enablement

Turn an organization's own mail server on or off

The only operation by which an administrator writes the configuration’s status, and it can write only the two administrative states: turning it off moves the configuration to ignored, and turning it on returns it to registered so that it must prove itself again before mail is routed. connected and disconnected are written by delivery outcomes alone and are never settable here, which is what keeps a deliberate opt-out distinguishable from a failing relay. Turning it on is refused with a 409 while the from domain is unverified.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/orgs/{orgId}/environments/mail-relay/connection/enablement

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/orgs/{orgId}/environments/mail-relay/connection/enablement

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/orgs/{orgId}/environments/mail-relay/connection/enablement

Parameters

Path parameters

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

Request body

application/json Required

Administrative on/off for an organization’s own mail server. It cannot express the delivery-driven states, which are written by outcomes alone.

Field	Type	Required	Description
`enabled`	boolean	Yes	True returns the configuration to `registered` so it may prove itself and carry mail; false moves it to `ignored`. Turning it on is refused while the from domain is unverified.

Returned data

Responses

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

An organization’s own outbound mail server. When present and healthy, every transactional email whose reader belongs to this organization - application notifications and identity-flow mail (account verification, password recovery) alike - is delivered through this server rather than through the provider’s shared relay, so the message leaves from the organization’s own domain. At most one live configuration exists per organization. The SMTP password is encrypted at rest and is never returned; reads always carry the redaction sentinel instead.

This is a WIRE contract only. It is not backed by a table of its own: the configuration is stored on the same environment/connection/credential chain that bring-your-own identity providers already uses - a well-known per-organization Environment, joined through environments_connections_mappings to a Connection whose credential_id points at a Credential. The organization relationship lives on environments.organization_id, the dial target on connections.url and connections.metadata, the transport verdict on connections.status, and the password alone in credentials.secret.

No property here carries a construct-specific db tag, because no property here names a column of its own. The exception is deliberate and inherited: createdAt and updatedAt $ref the shared core definitions, which declare db: created_at / db: updated_at for every construct that uses them, and those two tags are accurate for the underlying connection row.

Field	Type	Required	Description
`id`	string (uuid)	Yes	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.
`host`	string	Yes	Hostname of the organization’s SMTP server.
`port`	integer	Yes	TCP port the organization’s SMTP server listens on. The server additionally restricts this to a submission-port allowlist; a syntactically valid port outside it is refused.
`encryption`	string	Yes	Transport encryption to negotiate. `starttls` upgrades a cleartext connection (typically port 587), `tls` opens an implicit TLS connection (typically port 465), and `none` sends in cleartext and is intended only for an internal relay on a trusted network.
`authMechanism`	string	Yes	SMTP authentication mechanism. `none` is permitted only for a relay that authorizes by source address; a configuration using any other mechanism must carry both a username and a password.
`username`	string	No	Username presented to the organization’s SMTP server. Held beside the host rather than with the password because it is an identifier rather than a secret, and the health surface must show it without a decryption round trip. It is usually an email address, so it is returned only on an authorized read.
`password`	string	No	Present only when a password is stored, and then always the redaction sentinel `***` - never the stored value, which is encrypted at rest and is never projected into a response. Its presence is therefore the only thing it reports: a configuration whose `authMechanism` is `none` stores no password and omits this property entirely. It is optional rather than required for exactly that reason. Read-only, and read-only here means read-only: no request body references this schema. The write semantics belong to the payload schemas - `OrganizationSmtpConfigurationPayload` on create and `OrganizationSmtpCredentialPayload` on rotation - and are documented there.
`fromAddress`	string (email)	Yes	Address the organization’s mail is sent from. Its domain must be verified before mail is routed through this server.
`fromDisplayName`	string	No	Display name shown alongside the from address in the message header.
`replyToAddress`	string (email)	No	Address replies are directed to. It is also the address carried when a message falls back to the provider relay, which rewrites the from address to the provider’s own so the message stays aligned for SPF and DMARC.
`status`	string	Yes	Lifecycle and transport verdict, carrying the connection status vocabulary because the configuration IS a connection. `registered` means configured but never proven - the from domain is unverified, or no message has yet been delivered - and mail takes the provider relay. `connected` means the last delivery attempt succeeded and mail is routed through this server. `disconnected` means the most recent delivery attempt did not succeed, and `fallbackToProvider` governs what becomes of that message. It is a verdict on the last attempt alone: a SINGLE failure records it, there is no failure threshold, and the status does not by itself stop the server being dialled for the next message. Read it as “the last attempt failed”, not as “this server has been taken out of rotation” - the circuit breaker that would do the latter is planned, not built, and is tracked in meshery-cloud#6057. `ignored` means an administrator turned it off. The writers are disjoint on purpose: only an administrator writes `ignored`, and only a delivery outcome writes `connected` or `disconnected`. That is what keeps a deliberate opt-out distinguishable from a failing relay. It also makes “enabled while the from domain is unverified” unrepresentable rather than merely forbidden, which is why this property replaces the separate `enabled` and `verificationState` pair it supersedes.
`fallbackToProvider`	boolean	Yes	Whether a message that this server fails to accept is re-sent through the provider’s shared relay. Disabling it means the organization owns delivery entirely and a failure is a dropped message, including account verification and password recovery.
`fromDomain`	string	No	Registrable domain of the from address, held separately as the unit that ownership is proven for.
`fromDomainVerificationToken`	string	No	Token the organization publishes in DNS to prove control of the from domain. Not a credential - it authorizes nothing and grants no access.
`fromDomainVerifiedAt`	string \| null (date-time)	No	Timestamp at which control of the from domain was last proven. Null while unproven.
`lastSuccessAt`	string \| null (date-time)	No	Timestamp of the last message this server accepted.
`lastFailureAt`	string \| null (date-time)	No	Timestamp of the last delivery attempt this server rejected or failed to accept.
`lastFailureReason`	string	No	Classification of the last failure. Always a classification, never the remote server’s own message: the set is closed on purpose, because reporting a remote server’s text back to a caller would turn a refusal into an oracle for what the network can reach.
`consecutiveFailures`	integer	Yes	Count of delivery attempts that have failed since the last success, reset to zero by a success. It is a RECORD and nothing more: no threshold reads it, and reaching any particular value does not itself stop a persistently unreachable server being dialled. A consumer must not treat a non-zero count as protection already in place. The circuit breaker that would consume this count - and which needs a threshold, a reset policy, and a decision about its interaction with `fallbackToProvider`, where an open circuit with fallback off drops account-verification and password-recovery mail - is planned under meshery-cloud#6057.
`createdBy`	string \| null (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`createdAt`	string (date-time)	Yes	Timestamp when the configuration was created.
`updatedAt`	string (date-time)	Yes	Timestamp when the configuration was last changed.
`deletedAt`	string \| null (date-time)	No	Timestamp when the configuration was soft deleted. Null while it remains active.

Example response

{
  "authMechanism": "plain",
  "consecutiveFailures": 0,
  "createdAt": "0001-01-01T00:00:00Z",
  "createdBy": "00000000-0000-0000-0000-000000000000",
  "deletedAt": null,
  "encryption": "starttls",
  "fallbackToProvider": true,
  "fromAddress": "[email protected]",
  "fromDisplayName": "Example Corp",
  "fromDomain": "example.com",
  "fromDomainVerificationToken": "0f6a5d2c9b1e4a7f8c3d6b0e2a4f7c19",
  "fromDomainVerifiedAt": null,
  "host": "smtp.example.com",
  "id": "00000000-0000-0000-0000-000000000000",
  "lastFailureAt": null,
  "lastSuccessAt": null,
  "organizationId": "00000000-0000-0000-0000-000000000000",
  "password": "***",
  "port": 587,
  "replyToAddress": "[email protected]",
  "status": "registered",
  "updatedAt": "0001-01-01T00:00:00Z",
  "username": "[email protected]"
}

Organization SMTP Configuration OrganizationSmtp POST

/api/orgs/{orgId}/environments/mail-relay/connection/test

Send a test message through an organization's SMTP configuration

Delivers a real message through the configured server and reports a classified outcome. A real delivery rather than a connection probe on purpose: a server that connects and authenticates but refuses the sender or the recipient is the most common misconfiguration, and a probe reports it healthy. A successful test is also what promotes a verified configuration from registered to connected, so this operation is part of the lifecycle rather than a convenience. It takes the same permission as a write, because there is no read-only form of dialling an arbitrary host, and it is rate limited per organization. The recipient defaults to the calling administrator’s own address. The outcome is a classification, never the remote server’s own text.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/orgs/{orgId}/environments/mail-relay/connection/test

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/orgs/{orgId}/environments/mail-relay/connection/test

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/orgs/{orgId}/environments/mail-relay/connection/test

Parameters

Path parameters

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

Request body

application/json Optional

Options for a test delivery.

Field	Type	Required	Description
`to`	string (email)	No	Recipient of the test message. Defaults to the calling administrator’s own address.

Returned data

Responses

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

Classified outcome of a test delivery. Carries no text from the remote server, so a refusal reveals nothing about what the network can reach.

Field	Type	Required	Description
`outcome`	string	Yes	What happened. `delivered` means the server accepted the message; every other value names the stage that refused it.
`message`	string	No	Human-readable summary of the outcome, drawn from a fixed set of phrasings.
`sentTo`	string (email)	No	Address the test message was addressed to.
`testedAt`	string (date-time)	Yes	When the delivery was attempted.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/orgs/{orgId}/environments/mail-relay/domain-verification

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/orgs/{orgId}/environments/mail-relay/domain-verification

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/orgs/{orgId}/environments/mail-relay/domain-verification

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.

The DNS record proving control of an organization’s from domain, and the current state of that proof.

Field	Type	Required	Description
`domain`	string	Yes	Registrable domain the proof applies to.
`method`	string	Yes	How the domain is proven. `custom-domain` means it matches the organization’s own registered custom domain and needs no record; `dns-txt` means the record below must be published.
`recordName`	string	No	Fully qualified name of the TXT record to publish.
`recordValue`	string	No	Value the TXT record must carry.
`verified`	boolean	Yes	Whether control of the domain is currently proven.
`verifiedAt`	string \| null (date-time)	No	When control was last proven. Null while unproven.
`failureReason`	string	No	Why the last check did not prove control.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/orgs/{orgId}/environments/mail-relay/domain-verification

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/orgs/{orgId}/environments/mail-relay/domain-verification

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/orgs/{orgId}/environments/mail-relay/domain-verification

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.

The DNS record proving control of an organization’s from domain, and the current state of that proof.

Field	Type	Required	Description
`domain`	string	Yes	Registrable domain the proof applies to.
`method`	string	Yes	How the domain is proven. `custom-domain` means it matches the organization’s own registered custom domain and needs no record; `dns-txt` means the record below must be published.
`recordName`	string	No	Fully qualified name of the TXT record to publish.
`recordValue`	string	No	Value the TXT record must carry.
`verified`	boolean	Yes	Whether control of the domain is currently proven.
`verifiedAt`	string \| null (date-time)	No	When control was last proven. Null while unproven.
`failureReason`	string	No	Why the last check did not prove control.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/pattern/import

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/performance/profiles

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/performance/profiles

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/performance/profiles/{performanceProfileId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/performance/profiles/{performanceProfileId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/performance/profiles/{performanceProfileId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/performance/profiles/{performanceProfileId}/results

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/performance/profiles/{performanceProfileId}/results/{resultId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/performance/profiles/{performanceProfileId}/results/{resultId}

Parameters

Path parameters

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

Returned data

Responses

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

Load-test result captured for a Meshery performance profile.

Field	Type	Required	Description
`createdAt`	string (date-time)	No	Timestamp when the performance result was created.
`mesh`	string	No	Service mesh under test for this result.
`mesheryId`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`name`	string	No	Human-readable name of the performance result.
`owner`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`performanceProfile`	string \| null (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`runnerResults`	object	No	Raw load-generator output for this performance result.
`serverBoardConfig`	object	No	Server board configuration associated with this performance result.
`serverMetrics`	object	No	Server-side metrics collected for this performance result.
`testId`	string	No	Provider-assigned test identifier for this result.
`testStartTime`	string (date-time)	No	Time when the load test started.
`updatedAt`	string (date-time)	No	Timestamp when the performance result was last updated.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/performance/results

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/profiles

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/profiles

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/profiles

Parameters

Query parameters

Name	Type	Required	Description
`search`	string	No	Get responses that match search param value
`name`	string	No	Return only live profiles whose name equals this value, ignoring case.
`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)	No	Organization ID used to scope the listing. Defaults to the organization the session resolved to.
`userId`	string (uuid)	No	Return only the profile that represents this user.

Returned data

Responses

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

Paginated list of 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	Profiles in this page.
`totalCount`	integer	Yes	Total number of items across all pages.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/profiles

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/profiles

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/profiles

Request body

application/json Required

Body for creating or updating a profile

Payload for creating or updating a profile. Carries only the client-settable fields. id, createdAt, updatedAt and deletedAt are server-owned and deliberately absent. owner is optional: omitted on create it defaults to the authenticated user, and omitted on update it is unchanged.

Field	Type	Required	Description
`description`	string	No	Description of the profile.
`metadata`	object	No	Free-form settings of the profile.
`name`	string	Yes	Name of the profile, typically its short handle. Not unique.
`organizationId`	string (uuid)	Yes	Organization in which to create the profile. Cannot change after creation.
`owner`	string (uuid)	No	ID of the user who owns the profile. Only the owner or a holder of Edit Profile in a workspace the profile is assigned to may change it.
`userId`	string (uuid)	No	ID of the user this profile represents, when it represents a user. The user must be a member of the organization.

Returned data

Responses

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

A profile is a publishing or persona profile: a named set of settings, owned by an organization, that a person or brand publishes as, with the platform accounts it acts through linked to it as Connections. It is not the user account profile (/api/identity/users/profile) and not a performance profile (/api/performance/profiles), and it is neither an environment nor a workspace. Like environments, a profile is assigned to any number of workspaces, and workspace assignment is how access to it is shared: a profile is readable by its owner (whether or not it is assigned to any workspace), by organization admins, and by members of the workspaces it is assigned to. Provider admins do not see profiles automatically, and seeing a profile does not grant access to its linked connections.

Field	Type	Required	Description
`id`	string (uuid)	Yes	Server-generated profile ID.
`schemaVersion`	string	Yes	Specifies the version of the schema to which the profile conforms.
`name`	string	Yes	Name of the profile, typically its short handle. Not unique; like environment names, two profiles may share one.
`description`	string	No	Description of the profile.
`organizationId`	string (uuid)	Yes	Owning organization ID. Fixed at creation.
`owner`	string (uuid)	Yes	ID of the user who owns the profile. Defaults to the creating user. The owner, or a holder of the Edit Profile key in a workspace the profile is assigned to, may transfer it. When the owner’s account is deleted, ownership passes on by the same succession rule that applies to designs.
`userId`	string (uuid)	No	ID of the user this profile represents, when it represents a user. Absent for a profile that represents no user account, such as a brand. Not unique: a user may be represented by more than one profile.
`metadata`	object	No	Free-form settings of the profile, stored as a JSON blob.
`createdAt`	string (date-time)	Yes	Timestamp when the profile was created.
`updatedAt`	string (date-time)	Yes	Timestamp when the profile was last updated.
`deletedAt`	string \| null (date-time)	No	Timestamp when the profile was soft-deleted. Null while the profile remains active.

Example response

{
  "createdAt": "0001-01-01T00:00:00Z",
  "deletedAt": null,
  "description": "Profile for Jane's accounts and settings.",
  "id": "00000000-0000-0000-0000-000000000000",
  "metadata": {},
  "name": "jane",
  "organizationId": "00000000-0000-0000-0000-000000000000",
  "owner": "00000000-0000-0000-0000-000000000000",
  "schemaVersion": "profiles.meshery.io/v1beta3",
  "updatedAt": "0001-01-01T00:00:00Z",
  "userId": "00000000-0000-0000-0000-000000000000"
}

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.

Profile GET

/api/profiles/connections

Get the connection links of every visible profile

Gets, in one paged read, the live profile-to-connection links of every live profile of the organization whose connections the caller may list under getProfileConnections’ rules: the profiles the caller can see, with View Profiles; without it, only the profiles the caller owns. A profile that only represents the caller (userId) contributes no links, as its read-only grant does not cover its connections. A client learns which connections each profile acts through without one getProfileConnections call per profile. Items are ProfileConnectionMapping records; they carry ids only, and the connections themselves keep their own access rules. Ordered by profile, then connection.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/profiles/connections

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/profiles/connections

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/profiles/connections

Parameters

Query parameters

Name	Type	Required	Description
`orgId`	string (uuid)	No	Organization ID used to scope the listing. Defaults to the organization the session resolved to.
`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`.

Returned data

Responses

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

Paginated list of profile-to-connection links.

Field	Type	Required	Description
`mappings`	array of object	Yes	Profile-to-connection links 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.

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.

Profile GET

/api/profiles/{profileId}

Get profile by ID

Gets a profile visible to the caller: its owner (whether or not the profile is assigned to any workspace), the user it represents (userId, read only), an organization admin, or a member of a workspace it is assigned to. Provider admins are not granted visibility automatically. A profile the caller cannot see returns 404. Seeing the profile does not grant access to its linked connections. The response carries the profile’s entity tag in the ETag header.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/profiles/{profileId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/profiles/{profileId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/profiles/{profileId}

Parameters

Path parameters

Name	Type	Required	Description
`profileId`	string (uuid)	Yes	Profile ID

Returned data

Responses

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

A profile is a publishing or persona profile: a named set of settings, owned by an organization, that a person or brand publishes as, with the platform accounts it acts through linked to it as Connections. It is not the user account profile (/api/identity/users/profile) and not a performance profile (/api/performance/profiles), and it is neither an environment nor a workspace. Like environments, a profile is assigned to any number of workspaces, and workspace assignment is how access to it is shared: a profile is readable by its owner (whether or not it is assigned to any workspace), by organization admins, and by members of the workspaces it is assigned to. Provider admins do not see profiles automatically, and seeing a profile does not grant access to its linked connections.

Field	Type	Required	Description
`id`	string (uuid)	Yes	Server-generated profile ID.
`schemaVersion`	string	Yes	Specifies the version of the schema to which the profile conforms.
`name`	string	Yes	Name of the profile, typically its short handle. Not unique; like environment names, two profiles may share one.
`description`	string	No	Description of the profile.
`organizationId`	string (uuid)	Yes	Owning organization ID. Fixed at creation.
`owner`	string (uuid)	Yes	ID of the user who owns the profile. Defaults to the creating user. The owner, or a holder of the Edit Profile key in a workspace the profile is assigned to, may transfer it. When the owner’s account is deleted, ownership passes on by the same succession rule that applies to designs.
`userId`	string (uuid)	No	ID of the user this profile represents, when it represents a user. Absent for a profile that represents no user account, such as a brand. Not unique: a user may be represented by more than one profile.
`metadata`	object	No	Free-form settings of the profile, stored as a JSON blob.
`createdAt`	string (date-time)	Yes	Timestamp when the profile was created.
`updatedAt`	string (date-time)	Yes	Timestamp when the profile was last updated.
`deletedAt`	string \| null (date-time)	No	Timestamp when the profile was soft-deleted. Null while the profile remains active.

Example response

{
  "createdAt": "0001-01-01T00:00:00Z",
  "deletedAt": null,
  "description": "Profile for Jane's accounts and settings.",
  "id": "00000000-0000-0000-0000-000000000000",
  "metadata": {},
  "name": "jane",
  "organizationId": "00000000-0000-0000-0000-000000000000",
  "owner": "00000000-0000-0000-0000-000000000000",
  "schemaVersion": "profiles.meshery.io/v1beta3",
  "updatedAt": "0001-01-01T00:00:00Z",
  "userId": "00000000-0000-0000-0000-000000000000"
}

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.

Profile PUT

/api/profiles/{profileId}

Update a profile

Replaces the client-settable fields of the profile. organizationId cannot change after creation; a different value is refused with 400. Changing owner transfers the profile; the new owner must be a member of the organization. The optional If-Match header makes the write conditional on the entity tag the profile carried when it was read: when it no longer matches, the request is refused with 412 and nothing is written. Without If-Match the write is unconditional.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/profiles/{profileId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/profiles/{profileId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/profiles/{profileId}

Parameters

Path parameters

Name	Type	Required	Description
`profileId`	string (uuid)	Yes	Profile ID

Header parameters

Name	Type	Required	Description
`If-Match`	string	No	Entity tag of the profile as last read, from the `ETag` header of getProfileById or updateProfile. When present the write applies only if it still matches; otherwise 412.

Request body

application/json Required

Body for creating or updating a profile

Payload for creating or updating a profile. Carries only the client-settable fields. id, createdAt, updatedAt and deletedAt are server-owned and deliberately absent. owner is optional: omitted on create it defaults to the authenticated user, and omitted on update it is unchanged.

Field	Type	Required	Description
`description`	string	No	Description of the profile.
`metadata`	object	No	Free-form settings of the profile.
`name`	string	Yes	Name of the profile, typically its short handle. Not unique.
`organizationId`	string (uuid)	Yes	Organization in which to create the profile. Cannot change after creation.
`owner`	string (uuid)	No	ID of the user who owns the profile. Only the owner or a holder of Edit Profile in a workspace the profile is assigned to may change it.
`userId`	string (uuid)	No	ID of the user this profile represents, when it represents a user. The user must be a member of the organization.

Returned data

Responses

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

A profile is a publishing or persona profile: a named set of settings, owned by an organization, that a person or brand publishes as, with the platform accounts it acts through linked to it as Connections. It is not the user account profile (/api/identity/users/profile) and not a performance profile (/api/performance/profiles), and it is neither an environment nor a workspace. Like environments, a profile is assigned to any number of workspaces, and workspace assignment is how access to it is shared: a profile is readable by its owner (whether or not it is assigned to any workspace), by organization admins, and by members of the workspaces it is assigned to. Provider admins do not see profiles automatically, and seeing a profile does not grant access to its linked connections.

Field	Type	Required	Description
`id`	string (uuid)	Yes	Server-generated profile ID.
`schemaVersion`	string	Yes	Specifies the version of the schema to which the profile conforms.
`name`	string	Yes	Name of the profile, typically its short handle. Not unique; like environment names, two profiles may share one.
`description`	string	No	Description of the profile.
`organizationId`	string (uuid)	Yes	Owning organization ID. Fixed at creation.
`owner`	string (uuid)	Yes	ID of the user who owns the profile. Defaults to the creating user. The owner, or a holder of the Edit Profile key in a workspace the profile is assigned to, may transfer it. When the owner’s account is deleted, ownership passes on by the same succession rule that applies to designs.
`userId`	string (uuid)	No	ID of the user this profile represents, when it represents a user. Absent for a profile that represents no user account, such as a brand. Not unique: a user may be represented by more than one profile.
`metadata`	object	No	Free-form settings of the profile, stored as a JSON blob.
`createdAt`	string (date-time)	Yes	Timestamp when the profile was created.
`updatedAt`	string (date-time)	Yes	Timestamp when the profile was last updated.
`deletedAt`	string \| null (date-time)	No	Timestamp when the profile was soft-deleted. Null while the profile remains active.

Example response

{
  "createdAt": "0001-01-01T00:00:00Z",
  "deletedAt": null,
  "description": "Profile for Jane's accounts and settings.",
  "id": "00000000-0000-0000-0000-000000000000",
  "metadata": {},
  "name": "jane",
  "organizationId": "00000000-0000-0000-0000-000000000000",
  "owner": "00000000-0000-0000-0000-000000000000",
  "schemaVersion": "profiles.meshery.io/v1beta3",
  "updatedAt": "0001-01-01T00:00:00Z",
  "userId": "00000000-0000-0000-0000-000000000000"
}

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/profiles/{profileId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/profiles/{profileId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/profiles/{profileId}

Parameters

Path parameters

Name	Type	Required	Description
`profileId`	string (uuid)	Yes	Profile ID

Returned data

Responses

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

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.

Profile GET

/api/profiles/{profileId}/connections

Get profile connections

Gets the connections linked to a profile visible to the caller: its owner (whether or not the profile is assigned to any workspace), an organization admin, or a member of a workspace it is assigned to. The owner needs no permission key; organization admins and workspace members also need View Profiles. Provider admins are not granted visibility automatically. A profile the caller cannot see returns 404. Seeing the profile does not grant access to its linked connections, which follow their own access rules. kind narrows the page to connections of the given kinds.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/profiles/{profileId}/connections

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/profiles/{profileId}/connections

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/profiles/{profileId}/connections

Parameters

Path parameters

Name	Type	Required	Description
`profileId`	string (uuid)	Yes	Profile ID

Query parameters

Name	Type	Required	Description
`kind`	array of string	No	Return only connections of these kinds (repeatable), as getConnections does.
`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.

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

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/profiles/{profileId}/connections/{connectionId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/profiles/{profileId}/connections/{connectionId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/profiles/{profileId}/connections/{connectionId}

Parameters

Path parameters

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

Returned data

Responses

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

Junction record linking a profile to a connection.

Field	Type	Required	Description
`connectionId`	string (uuid)	Yes	ID of the linked connection.
`createdAt`	string (date-time)	No	Timestamp when the mapping was created.
`deletedAt`	string \| null (date-time)	No	Timestamp when the mapping was soft-deleted. Null while the mapping remains active.
`id`	string (uuid)	Yes	Mapping record ID.
`profileId`	string (uuid)	Yes	ID of the linked profile.
`updatedAt`	string (date-time)	No	Timestamp when the mapping was last updated.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/profiles/{profileId}/connections/{connectionId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/profiles/{profileId}/connections/{connectionId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/profiles/{profileId}/connections/{connectionId}

Parameters

Path parameters

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

Returned data

Responses

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

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/registry/connections

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/registry/connections

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/registry/connections/{connectionDefinitionId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/registry/connections/{connectionDefinitionId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/registry/connections/{connectionDefinitionId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/resource/{resourceType}/share/{resourceId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/resource/{resourceType}/share/{resourceId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/resource/{resourceType}/share/{resourceId}

Path parameters

Name	Type	Required	Description
`resourceType`	string	Yes	No description provided.
`resourceId`	string	Yes	No description provided.

application/json Required

Schema: object

Returned data

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

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/resource/{resourceType}/share/{resourceId}/{actorType}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/resource/{resourceType}/share/{resourceId}/{actorType}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/resource/{resourceType}/share/{resourceId}/{actorType}

Path parameters

Name	Type	Required	Description
`resourceType`	string	Yes	No description provided.
`resourceId`	string	Yes	No description provided.
`actorType`	string	Yes	No description provided.

Returned data

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

Field	Type	Required	Description
`users`	array of object	No	The users of the resourceaccessactorsresponse.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/schedules

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/schedules

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/schedules

Parameters

Query parameters

Name	Type	Required	Description
`page`	integer	No	Get responses by page
`pageSize`	integer	No	Number of items per page.
`search`	string	No	Get responses that match search param value
`order`	string	No	Get ordered responses
`workspaceId`	string (uuid)	No	Only schedules linked to this workspace.
`status`	string	No	Only schedules in this status.

Returned data

Responses

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

Paginated collection of schedules.

Field	Type	Required	Description
`page`	integer	Yes	Current page number of the result set.
`pageSize`	integer	Yes	Number of items per page.
`schedules`	array of object	Yes	Schedules included on this page of results.
`totalCount`	integer	Yes	Total number of items available.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/schedules

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/schedules

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/schedules

Request body

application/json Required

Payload for creating or updating a schedule. Contains only client-settable fields; the owning organizationId, createdBy, the claim, pausedAt, pausedBy, lastRunAt, lastError and the timestamps are server-managed and refused as unknown fields. Pausing is a field, not an operation: paused pauses or resumes the schedule. status accepts only pending, scheduled and cancelled here (otherwise 400); the other values are set by the server as the schedule is claimed and released.

Field	Type	Required	Description
`action`	string	Yes	The action the worker runs, for example a command name.
`enabled`	boolean	No	Whether the schedule is eligible to run.
`id`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`maxRetries`	integer	No	Maximum retries before the run is marked failed.
`name`	string	Yes	Human-readable name for the schedule.
`nextRunAt`	string \| null (date-time)	No	Next time the schedule becomes due. Omitted on create, it defaults to `runAt`; omitted on update, it is kept. Send null for never due again.
`params`	object	No	Action parameters, stored as a JSON blob.
`paused`	boolean	No	`true` pauses the schedule so it is never claimed; `false` resumes it. Omit to leave the pause unchanged. The server records `pausedAt` and `pausedBy`.
`pauseReason`	string	No	Reason for pausing; stored only while `paused` is true and cleared on resume.
`posture`	string	No	Optional Posture this schedule runs under, resolved above the profile x platform resolution and below an explicit per-run flag. Omit to inherit: the schedule then runs under whatever profile x platform, configuration, environment, account or default resolves to, exactly as before.
`recurrence`	string	No	How the schedule repeats once it has run. Empty, `once` and `none` mean run once. `hourly` repeats every hour; `daily`, `weekly` and `monthly` repeat at the same wall-clock time one calendar day, week or month later in the schedule’s `timezone`, so a daily schedule keeps its local time across daylight-saving changes. `every:<n>` repeats every `n` minutes (1 to 999999). Occurrences are counted from `runAt` (else from the current `nextRunAt`); the next due time is the first occurrence after the run is released, so missed runs are not replayed.
`retryCount`	integer	No	Retries used so far for the current run, for example 0 to re-arm a schedule. Omitted on update, it is kept.
`retryDelayMinutes`	integer	No	Minutes to wait before a retry becomes due.
`runAt`	string \| null (date-time)	No	Time the schedule first becomes due.
`status`	string	No	Lifecycle status of a schedule. `pending`: created, not yet due-scheduled. `scheduled`: waiting for its due time. `assigned`: designated for a particular worker but not yet claimed. `claimed`: a worker holds the claim and has not started. `running`: the claim holder is executing it. `retrying`: the last attempt failed and another is due. `completed`, `failed` and `cancelled` are terminal for a run-once schedule; a recurring schedule returns to `scheduled` when its claim is released with a `completed` outcome.
`targetId`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`targetType`	string	No	Type of the resource the schedule acts on, named the way a claim’s `resourceType` is (lowercase snake_case construct name, for example `content_item` or `profile`). A server verifies the target types it serves and refuses others with 400. Set together with `targetId` or not at all.
`timezone`	string	No	IANA time zone name (for example `UTC` or `America/Chicago`) in which `daily`, `weekly` and `monthly` recurrences keep their wall-clock time. Instants (`runAt`, `nextRunAt`) are always absolute. The server refuses a name it does not know with 400.
`workspaceId`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.

Returned data

Responses

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

Server-returned schedule. A schedule is a job: an action to run, what it acts on (targetType, targetId) and its parameters, when it is due (runAt, nextRunAt, recurrence in timezone), its retry budget and its outcome. Schedules belong to an organization and may be linked to a workspace. A worker takes a schedule through the generic claim construct (POST /api/claims with resourceType schedule); there is no schedule-specific claim route. While the claim is live no other worker can take the schedule, and a claim past its expiresAt is stale so the schedule is claimable again. Releasing the claim records the run’s outcome on the schedule in the same transaction (see status). The claim and the status values assigned, claimed and running are server-managed. Pausing is data, not an operation: a client sets paused (and optionally pauseReason) on create or update, and the server records pausedAt and pausedBy. Fields marked readOnly are server-managed and ignored on input.

Field	Type	Required	Description
`id`	string (uuid)	Yes	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.
`workspaceId`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`createdBy`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`name`	string	Yes	Human-readable name for the schedule.
`action`	string	Yes	The action the worker runs when it holds the schedule’s claim, for example a command name.
`targetType`	string	No	Type of the resource the schedule acts on, named the way a claim’s `resourceType` is (lowercase snake_case construct name, for example `content_item` or `profile`). A server verifies the target types it serves and refuses others with 400. Set together with `targetId` or not at all.
`targetId`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`params`	object	No	Action parameters, stored as a JSON blob. What the schedule acts on belongs in `targetType` and `targetId`, not here.
`enabled`	boolean	Yes	Whether the schedule is eligible to run. A disabled schedule is never claimed.
`runAt`	string \| null (date-time)	No	Time the schedule first becomes due.
`nextRunAt`	string \| null (date-time)	No	Next time the schedule becomes due. Null when it is never due again.
`recurrence`	string	No	How the schedule repeats once it has run. Empty, `once` and `none` mean run once. `hourly` repeats every hour; `daily`, `weekly` and `monthly` repeat at the same wall-clock time one calendar day, week or month later in the schedule’s `timezone`, so a daily schedule keeps its local time across daylight-saving changes. `every:<n>` repeats every `n` minutes (1 to 999999). Occurrences are counted from `runAt` (else from the current `nextRunAt`); the next due time is the first occurrence after the run is released, so missed runs are not replayed.
`timezone`	string	Yes	IANA time zone name (for example `UTC` or `America/Chicago`) in which `daily`, `weekly` and `monthly` recurrences keep their wall-clock time. Instants (`runAt`, `nextRunAt`) are always absolute. The server refuses a name it does not know with 400.
`status`	string	Yes	Lifecycle status of a schedule. `pending`: created, not yet due-scheduled. `scheduled`: waiting for its due time. `assigned`: designated for a particular worker but not yet claimed. `claimed`: a worker holds the claim and has not started. `running`: the claim holder is executing it. `retrying`: the last attempt failed and another is due. `completed`, `failed` and `cancelled` are terminal for a run-once schedule; a recurring schedule returns to `scheduled` when its claim is released with a `completed` outcome.
`retryCount`	integer	Yes	Attempts already retried for the current run.
`maxRetries`	integer	Yes	Maximum retries before the run is marked failed.
`retryDelayMinutes`	integer	No	Minutes to wait before a retry becomes due.
`lastRunAt`	string \| null (date-time)	No	Time the most recent attempt ended (the release time of its claim). Server-managed.
`lastError`	string	No	Error reported by the most recent attempt; empty after a successful one. Server-managed.
`claim`	object	No	The schedule’s live claim, when one is held. A read-only view of the claim construct; omitted when the schedule is unclaimed.
`pausedAt`	string \| null (date-time)	No	Time the schedule was paused. Null when the schedule is not paused. Server-managed.
`pausedBy`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`pauseReason`	string	No	Reason given for pausing the schedule, set with `paused` on create or update. Empty when not paused.
`createdAt`	string (date-time)	Yes	Timestamp of schedule creation.
`updatedAt`	string (date-time)	Yes	Timestamp of last schedule modification.
`deletedAt`	string \| null (date-time)	No	Timestamp when the schedule was soft-deleted. Null while live.
`posture`	string	No	Optional Posture this schedule runs under, resolved above the profile x platform resolution and below an explicit per-run flag. Omitted when the schedule has no override: it then runs under whatever profile x platform, configuration, environment, account or default resolves to, exactly as before. Any value outside the Posture enum is refused with 400.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/schedules/{scheduleId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/schedules/{scheduleId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/schedules/{scheduleId}

Parameters

Path parameters

Name	Type	Required	Description
`scheduleId`	string (uuid)	Yes	Schedule ID

Returned data

Responses

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

Server-returned schedule. A schedule is a job: an action to run, what it acts on (targetType, targetId) and its parameters, when it is due (runAt, nextRunAt, recurrence in timezone), its retry budget and its outcome. Schedules belong to an organization and may be linked to a workspace. A worker takes a schedule through the generic claim construct (POST /api/claims with resourceType schedule); there is no schedule-specific claim route. While the claim is live no other worker can take the schedule, and a claim past its expiresAt is stale so the schedule is claimable again. Releasing the claim records the run’s outcome on the schedule in the same transaction (see status). The claim and the status values assigned, claimed and running are server-managed. Pausing is data, not an operation: a client sets paused (and optionally pauseReason) on create or update, and the server records pausedAt and pausedBy. Fields marked readOnly are server-managed and ignored on input.

Field	Type	Required	Description
`id`	string (uuid)	Yes	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.
`workspaceId`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`createdBy`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`name`	string	Yes	Human-readable name for the schedule.
`action`	string	Yes	The action the worker runs when it holds the schedule’s claim, for example a command name.
`targetType`	string	No	Type of the resource the schedule acts on, named the way a claim’s `resourceType` is (lowercase snake_case construct name, for example `content_item` or `profile`). A server verifies the target types it serves and refuses others with 400. Set together with `targetId` or not at all.
`targetId`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`params`	object	No	Action parameters, stored as a JSON blob. What the schedule acts on belongs in `targetType` and `targetId`, not here.
`enabled`	boolean	Yes	Whether the schedule is eligible to run. A disabled schedule is never claimed.
`runAt`	string \| null (date-time)	No	Time the schedule first becomes due.
`nextRunAt`	string \| null (date-time)	No	Next time the schedule becomes due. Null when it is never due again.
`recurrence`	string	No	How the schedule repeats once it has run. Empty, `once` and `none` mean run once. `hourly` repeats every hour; `daily`, `weekly` and `monthly` repeat at the same wall-clock time one calendar day, week or month later in the schedule’s `timezone`, so a daily schedule keeps its local time across daylight-saving changes. `every:<n>` repeats every `n` minutes (1 to 999999). Occurrences are counted from `runAt` (else from the current `nextRunAt`); the next due time is the first occurrence after the run is released, so missed runs are not replayed.
`timezone`	string	Yes	IANA time zone name (for example `UTC` or `America/Chicago`) in which `daily`, `weekly` and `monthly` recurrences keep their wall-clock time. Instants (`runAt`, `nextRunAt`) are always absolute. The server refuses a name it does not know with 400.
`status`	string	Yes	Lifecycle status of a schedule. `pending`: created, not yet due-scheduled. `scheduled`: waiting for its due time. `assigned`: designated for a particular worker but not yet claimed. `claimed`: a worker holds the claim and has not started. `running`: the claim holder is executing it. `retrying`: the last attempt failed and another is due. `completed`, `failed` and `cancelled` are terminal for a run-once schedule; a recurring schedule returns to `scheduled` when its claim is released with a `completed` outcome.
`retryCount`	integer	Yes	Attempts already retried for the current run.
`maxRetries`	integer	Yes	Maximum retries before the run is marked failed.
`retryDelayMinutes`	integer	No	Minutes to wait before a retry becomes due.
`lastRunAt`	string \| null (date-time)	No	Time the most recent attempt ended (the release time of its claim). Server-managed.
`lastError`	string	No	Error reported by the most recent attempt; empty after a successful one. Server-managed.
`claim`	object	No	The schedule’s live claim, when one is held. A read-only view of the claim construct; omitted when the schedule is unclaimed.
`pausedAt`	string \| null (date-time)	No	Time the schedule was paused. Null when the schedule is not paused. Server-managed.
`pausedBy`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`pauseReason`	string	No	Reason given for pausing the schedule, set with `paused` on create or update. Empty when not paused.
`createdAt`	string (date-time)	Yes	Timestamp of schedule creation.
`updatedAt`	string (date-time)	Yes	Timestamp of last schedule modification.
`deletedAt`	string \| null (date-time)	No	Timestamp when the schedule was soft-deleted. Null while live.
`posture`	string	No	Optional Posture this schedule runs under, resolved above the profile x platform resolution and below an explicit per-run flag. Omitted when the schedule has no override: it then runs under whatever profile x platform, configuration, environment, account or default resolves to, exactly as before. Any value outside the Posture enum is refused with 400.

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.

Schedule Schedules PUT

/api/schedules/{scheduleId}

Update a schedule

Updates the client-settable fields present in the payload; an omitted optional field keeps its stored value, and null clears a nullable one (workspaceId, runAt, nextRunAt, and targetType with targetId). status accepts only pending, scheduled and cancelled. Pause or resume the schedule by setting paused (with an optional pauseReason); the server then records pausedAt and pausedBy. Pausing a paused schedule keeps its original pausedAt; omitting paused leaves the pause unchanged. The optional If-Match header makes the write conditional on the entity tag the schedule carried when it was read: when it no longer matches, the request is refused with 412 and nothing is written. Without If-Match the write is unconditional.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/schedules/{scheduleId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/schedules/{scheduleId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/schedules/{scheduleId}

Parameters

Path parameters

Name	Type	Required	Description
`scheduleId`	string (uuid)	Yes	Schedule ID

Header parameters

Name	Type	Required	Description
`If-Match`	string	No	Entity tag of the schedule as last read, from the `ETag` header of getScheduleById, createSchedule or updateSchedule. When present the write applies only if it still matches; otherwise 412.

Request body

application/json Required

Payload for creating or updating a schedule. Contains only client-settable fields; the owning organizationId, createdBy, the claim, pausedAt, pausedBy, lastRunAt, lastError and the timestamps are server-managed and refused as unknown fields. Pausing is a field, not an operation: paused pauses or resumes the schedule. status accepts only pending, scheduled and cancelled here (otherwise 400); the other values are set by the server as the schedule is claimed and released.

Field	Type	Required	Description
`action`	string	Yes	The action the worker runs, for example a command name.
`enabled`	boolean	No	Whether the schedule is eligible to run.
`id`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`maxRetries`	integer	No	Maximum retries before the run is marked failed.
`name`	string	Yes	Human-readable name for the schedule.
`nextRunAt`	string \| null (date-time)	No	Next time the schedule becomes due. Omitted on create, it defaults to `runAt`; omitted on update, it is kept. Send null for never due again.
`params`	object	No	Action parameters, stored as a JSON blob.
`paused`	boolean	No	`true` pauses the schedule so it is never claimed; `false` resumes it. Omit to leave the pause unchanged. The server records `pausedAt` and `pausedBy`.
`pauseReason`	string	No	Reason for pausing; stored only while `paused` is true and cleared on resume.
`posture`	string	No	Optional Posture this schedule runs under, resolved above the profile x platform resolution and below an explicit per-run flag. Omit to inherit: the schedule then runs under whatever profile x platform, configuration, environment, account or default resolves to, exactly as before.
`recurrence`	string	No	How the schedule repeats once it has run. Empty, `once` and `none` mean run once. `hourly` repeats every hour; `daily`, `weekly` and `monthly` repeat at the same wall-clock time one calendar day, week or month later in the schedule’s `timezone`, so a daily schedule keeps its local time across daylight-saving changes. `every:<n>` repeats every `n` minutes (1 to 999999). Occurrences are counted from `runAt` (else from the current `nextRunAt`); the next due time is the first occurrence after the run is released, so missed runs are not replayed.
`retryCount`	integer	No	Retries used so far for the current run, for example 0 to re-arm a schedule. Omitted on update, it is kept.
`retryDelayMinutes`	integer	No	Minutes to wait before a retry becomes due.
`runAt`	string \| null (date-time)	No	Time the schedule first becomes due.
`status`	string	No	Lifecycle status of a schedule. `pending`: created, not yet due-scheduled. `scheduled`: waiting for its due time. `assigned`: designated for a particular worker but not yet claimed. `claimed`: a worker holds the claim and has not started. `running`: the claim holder is executing it. `retrying`: the last attempt failed and another is due. `completed`, `failed` and `cancelled` are terminal for a run-once schedule; a recurring schedule returns to `scheduled` when its claim is released with a `completed` outcome.
`targetId`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`targetType`	string	No	Type of the resource the schedule acts on, named the way a claim’s `resourceType` is (lowercase snake_case construct name, for example `content_item` or `profile`). A server verifies the target types it serves and refuses others with 400. Set together with `targetId` or not at all.
`timezone`	string	No	IANA time zone name (for example `UTC` or `America/Chicago`) in which `daily`, `weekly` and `monthly` recurrences keep their wall-clock time. Instants (`runAt`, `nextRunAt`) are always absolute. The server refuses a name it does not know with 400.
`workspaceId`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.

Returned data

Responses

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

Server-returned schedule. A schedule is a job: an action to run, what it acts on (targetType, targetId) and its parameters, when it is due (runAt, nextRunAt, recurrence in timezone), its retry budget and its outcome. Schedules belong to an organization and may be linked to a workspace. A worker takes a schedule through the generic claim construct (POST /api/claims with resourceType schedule); there is no schedule-specific claim route. While the claim is live no other worker can take the schedule, and a claim past its expiresAt is stale so the schedule is claimable again. Releasing the claim records the run’s outcome on the schedule in the same transaction (see status). The claim and the status values assigned, claimed and running are server-managed. Pausing is data, not an operation: a client sets paused (and optionally pauseReason) on create or update, and the server records pausedAt and pausedBy. Fields marked readOnly are server-managed and ignored on input.

Field	Type	Required	Description
`id`	string (uuid)	Yes	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.
`workspaceId`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`createdBy`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`name`	string	Yes	Human-readable name for the schedule.
`action`	string	Yes	The action the worker runs when it holds the schedule’s claim, for example a command name.
`targetType`	string	No	Type of the resource the schedule acts on, named the way a claim’s `resourceType` is (lowercase snake_case construct name, for example `content_item` or `profile`). A server verifies the target types it serves and refuses others with 400. Set together with `targetId` or not at all.
`targetId`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`params`	object	No	Action parameters, stored as a JSON blob. What the schedule acts on belongs in `targetType` and `targetId`, not here.
`enabled`	boolean	Yes	Whether the schedule is eligible to run. A disabled schedule is never claimed.
`runAt`	string \| null (date-time)	No	Time the schedule first becomes due.
`nextRunAt`	string \| null (date-time)	No	Next time the schedule becomes due. Null when it is never due again.
`recurrence`	string	No	How the schedule repeats once it has run. Empty, `once` and `none` mean run once. `hourly` repeats every hour; `daily`, `weekly` and `monthly` repeat at the same wall-clock time one calendar day, week or month later in the schedule’s `timezone`, so a daily schedule keeps its local time across daylight-saving changes. `every:<n>` repeats every `n` minutes (1 to 999999). Occurrences are counted from `runAt` (else from the current `nextRunAt`); the next due time is the first occurrence after the run is released, so missed runs are not replayed.
`timezone`	string	Yes	IANA time zone name (for example `UTC` or `America/Chicago`) in which `daily`, `weekly` and `monthly` recurrences keep their wall-clock time. Instants (`runAt`, `nextRunAt`) are always absolute. The server refuses a name it does not know with 400.
`status`	string	Yes	Lifecycle status of a schedule. `pending`: created, not yet due-scheduled. `scheduled`: waiting for its due time. `assigned`: designated for a particular worker but not yet claimed. `claimed`: a worker holds the claim and has not started. `running`: the claim holder is executing it. `retrying`: the last attempt failed and another is due. `completed`, `failed` and `cancelled` are terminal for a run-once schedule; a recurring schedule returns to `scheduled` when its claim is released with a `completed` outcome.
`retryCount`	integer	Yes	Attempts already retried for the current run.
`maxRetries`	integer	Yes	Maximum retries before the run is marked failed.
`retryDelayMinutes`	integer	No	Minutes to wait before a retry becomes due.
`lastRunAt`	string \| null (date-time)	No	Time the most recent attempt ended (the release time of its claim). Server-managed.
`lastError`	string	No	Error reported by the most recent attempt; empty after a successful one. Server-managed.
`claim`	object	No	The schedule’s live claim, when one is held. A read-only view of the claim construct; omitted when the schedule is unclaimed.
`pausedAt`	string \| null (date-time)	No	Time the schedule was paused. Null when the schedule is not paused. Server-managed.
`pausedBy`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`pauseReason`	string	No	Reason given for pausing the schedule, set with `paused` on create or update. Empty when not paused.
`createdAt`	string (date-time)	Yes	Timestamp of schedule creation.
`updatedAt`	string (date-time)	Yes	Timestamp of last schedule modification.
`deletedAt`	string \| null (date-time)	No	Timestamp when the schedule was soft-deleted. Null while live.
`posture`	string	No	Optional Posture this schedule runs under, resolved above the profile x platform resolution and below an explicit per-run flag. Omitted when the schedule has no override: it then runs under whatever profile x platform, configuration, environment, account or default resolves to, exactly as before. Any value outside the Posture enum is refused with 400.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/schedules/{scheduleId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/schedules/{scheduleId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/schedules/{scheduleId}

Parameters

Path parameters

Name	Type	Required	Description
`scheduleId`	string (uuid)	Yes	Schedule ID

Returned data

Responses

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

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.

Support POST

/api/support/anonymous

Submit an anonymous support request

Accepts a support request without requiring a signed-in user, so a desktop client can offer a “Contact support” action whether or not the person is signed in. A signed-out client authenticates with the same per-client-kind X-Client-Key as submitFailureDiagnostic; a signed-in caller may use its bearer token instead, and only then is the organization attached. A request carrying neither is a 401. The email address is only ever sent when the person types it in, and diagnosticId links this report to the automatic failure diagnostic submitted for the same incident, when one exists. Served by Layer5 Cloud; see Blowhorn issue #771.

Authentication

Support ClientKey or Bearer JWT

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/support/anonymous

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/support/anonymous

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/support/anonymous

Request body

application/json Required

Payload for submitting a help-and-support request without signing in. It carries the same subject, message, and scope as SupportRequest, plus two optional fields: an email address the person typed in for a follow-up, and the diagnosticId of the automatic failure diagnostic for the same incident, when one was submitted. The fields are spelled out here rather than composed with allOf so generated clients expose them flat, exactly like SupportRequest. The object is closed: Cloud decodes it strictly and refuses an unknown field with a 400.

Field	Type	Required	Description
`diagnosticId`	string (uuid)	No	Optional id of the FailureDiagnostic submitted for the same incident (schemas/constructs/v1beta1/diagnostics/api.yml), linking the human report to the automatic diagnostic.
`email`	string (email)	No	Optional email address the person typed in for a follow-up. Absent when they did not ask to be contacted; never inferred from an account, because this request may come from a signed-out client.
`message`	string	Yes	Detailed description of the issue or question.
`scope`	string	No	Category that best represents the nature of the inquiry.
`subject`	string	Yes	Concise and descriptive title for the support request.

Returned data

Responses

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

Field	Type	Required	Description
`diagnosticId`	string (uuid)	No	Echoes the request’s diagnosticId; omitted when the request linked none.
`status`	string	Yes	Always `received`.

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.

Field	Type	Required	Description
`message`	string	Yes	The refusal, for example “Client key required for operation is invalid or missing”.

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.

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.

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.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/system/email/test

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/system/email/test

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/system/email/test

Request body

application/json Required

Recipient and optional subject for the test email.

Request body for sending a test email through the configured SMTP provider.

Field	Type	Required	Description
`subject`	string	No	Subject line for the test message. A default subject is used when omitted.
`to`	string (email)	Yes	Recipient email address for the test message.

Returned data

Responses

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

Result of a test email send attempt.

Field	Type	Required	Description
`message`	string	Yes	Human-readable result message.
`sentTo`	string (email)	Yes	Recipient address the test email was sent to.
`status`	string	Yes	Outcome status of the send attempt (e.g. `success`).
`timestamp`	string	Yes	Unix-epoch seconds, as a decimal string, when the test email was sent.

Authentication

No authentication required

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/system/version

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/users

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/workspaces

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/workspaces

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/workspaces/{workspaceId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/workspaces/{workspaceId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/workspaces/{workspaceId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/workspaces/{workspaceId}/designs

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/workspaces/{workspaceId}/designs/{designId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

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

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/workspaces/{workspaceId}/designs/{designId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/workspaces/{workspaceId}/environments

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/workspaces/{workspaceId}/environments

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/workspaces/{workspaceId}/environments/{environmentId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/workspaces/{workspaceId}/environments/{environmentId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/workspaces/{workspaceId}/environments/{environmentId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/workspaces/{workspaceId}/environments/{environmentId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Authentication

Bearer JWT

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/workspaces/{workspaceId}/events

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/workspaces/{workspaceId}/events

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/workspaces/{workspaceId}/events

Parameters

Path parameters

Name	Type	Required	Description
`workspaceId`	string (uuid)	Yes	Workspace 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.
`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 events.

Field	Type	Required	Description
`data`	array of object	No	The events returned on the current 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.

Generic error envelope returned for non-2xx responses.

Field	Type	Required	Description
`error`	string	No	Human-readable error message.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/workspaces/{workspaceId}/profiles

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/workspaces/{workspaceId}/profiles

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/workspaces/{workspaceId}/profiles

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 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	Profiles in this page.
`totalCount`	integer	Yes	Total number of items across all pages.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/workspaces/{workspaceId}/profiles/{profileId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/workspaces/{workspaceId}/profiles/{profileId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/workspaces/{workspaceId}/profiles/{profileId}

Parameters

Path parameters

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

Returned data

Responses

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

Paginated list of workspace-profile 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.
`workspacesProfilesMapping`	array of object	No	Workspace-profile mapping entries.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/workspaces/{workspaceId}/profiles/{profileId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/workspaces/{workspaceId}/profiles/{profileId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/workspaces/{workspaceId}/profiles/{profileId}

Parameters

Path parameters

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

Returned data

Responses

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

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/workspaces/{workspaceId}/schedules

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/workspaces/{workspaceId}/schedules

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/workspaces/{workspaceId}/schedules

Parameters

Path parameters

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

Query parameters

Name	Type	Required	Description
`page`	integer	No	Get responses by page
`pageSize`	integer	No	Number of items per page.
`search`	string	No	Get responses that match search param value
`order`	string	No	Get ordered responses
`status`	string	No	Only schedules in this status.

Returned data

Responses

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

Paginated collection of schedules.

Field	Type	Required	Description
`page`	integer	Yes	Current page number of the result set.
`pageSize`	integer	Yes	Number of items per page.
`schedules`	array of object	Yes	Schedules included on this page of results.
`totalCount`	integer	Yes	Total number of items available.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/workspaces/{workspaceId}/schedules/{scheduleId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/workspaces/{workspaceId}/schedules/{scheduleId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/workspaces/{workspaceId}/schedules/{scheduleId}

Parameters

Path parameters

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

Returned data

Responses

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

Server-returned schedule. A schedule is a job: an action to run, what it acts on (targetType, targetId) and its parameters, when it is due (runAt, nextRunAt, recurrence in timezone), its retry budget and its outcome. Schedules belong to an organization and may be linked to a workspace. A worker takes a schedule through the generic claim construct (POST /api/claims with resourceType schedule); there is no schedule-specific claim route. While the claim is live no other worker can take the schedule, and a claim past its expiresAt is stale so the schedule is claimable again. Releasing the claim records the run’s outcome on the schedule in the same transaction (see status). The claim and the status values assigned, claimed and running are server-managed. Pausing is data, not an operation: a client sets paused (and optionally pauseReason) on create or update, and the server records pausedAt and pausedBy. Fields marked readOnly are server-managed and ignored on input.

Field	Type	Required	Description
`id`	string (uuid)	Yes	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.
`workspaceId`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`createdBy`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`name`	string	Yes	Human-readable name for the schedule.
`action`	string	Yes	The action the worker runs when it holds the schedule’s claim, for example a command name.
`targetType`	string	No	Type of the resource the schedule acts on, named the way a claim’s `resourceType` is (lowercase snake_case construct name, for example `content_item` or `profile`). A server verifies the target types it serves and refuses others with 400. Set together with `targetId` or not at all.
`targetId`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`params`	object	No	Action parameters, stored as a JSON blob. What the schedule acts on belongs in `targetType` and `targetId`, not here.
`enabled`	boolean	Yes	Whether the schedule is eligible to run. A disabled schedule is never claimed.
`runAt`	string \| null (date-time)	No	Time the schedule first becomes due.
`nextRunAt`	string \| null (date-time)	No	Next time the schedule becomes due. Null when it is never due again.
`recurrence`	string	No	How the schedule repeats once it has run. Empty, `once` and `none` mean run once. `hourly` repeats every hour; `daily`, `weekly` and `monthly` repeat at the same wall-clock time one calendar day, week or month later in the schedule’s `timezone`, so a daily schedule keeps its local time across daylight-saving changes. `every:<n>` repeats every `n` minutes (1 to 999999). Occurrences are counted from `runAt` (else from the current `nextRunAt`); the next due time is the first occurrence after the run is released, so missed runs are not replayed.
`timezone`	string	Yes	IANA time zone name (for example `UTC` or `America/Chicago`) in which `daily`, `weekly` and `monthly` recurrences keep their wall-clock time. Instants (`runAt`, `nextRunAt`) are always absolute. The server refuses a name it does not know with 400.
`status`	string	Yes	Lifecycle status of a schedule. `pending`: created, not yet due-scheduled. `scheduled`: waiting for its due time. `assigned`: designated for a particular worker but not yet claimed. `claimed`: a worker holds the claim and has not started. `running`: the claim holder is executing it. `retrying`: the last attempt failed and another is due. `completed`, `failed` and `cancelled` are terminal for a run-once schedule; a recurring schedule returns to `scheduled` when its claim is released with a `completed` outcome.
`retryCount`	integer	Yes	Attempts already retried for the current run.
`maxRetries`	integer	Yes	Maximum retries before the run is marked failed.
`retryDelayMinutes`	integer	No	Minutes to wait before a retry becomes due.
`lastRunAt`	string \| null (date-time)	No	Time the most recent attempt ended (the release time of its claim). Server-managed.
`lastError`	string	No	Error reported by the most recent attempt; empty after a successful one. Server-managed.
`claim`	object	No	The schedule’s live claim, when one is held. A read-only view of the claim construct; omitted when the schedule is unclaimed.
`pausedAt`	string \| null (date-time)	No	Time the schedule was paused. Null when the schedule is not paused. Server-managed.
`pausedBy`	string (uuid)	No	A Universally Unique Identifier used to uniquely identify entities in Meshery. The UUID core definition is used across different schemas.
`pauseReason`	string	No	Reason given for pausing the schedule, set with `paused` on create or update. Empty when not paused.
`createdAt`	string (date-time)	Yes	Timestamp of schedule creation.
`updatedAt`	string (date-time)	Yes	Timestamp of last schedule modification.
`deletedAt`	string \| null (date-time)	No	Timestamp when the schedule was soft-deleted. Null while live.
`posture`	string	No	Optional Posture this schedule runs under, resolved above the profile x platform resolution and below an explicit per-run flag. Omitted when the schedule has no override: it then runs under whatever profile x platform, configuration, environment, account or default resolves to, exactly as before. Any value outside the Posture enum is refused with 400.

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/workspaces/{workspaceId}/schedules/{scheduleId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/workspaces/{workspaceId}/schedules/{scheduleId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/api/workspaces/{workspaceId}/schedules/{scheduleId}

Parameters

Path parameters

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

Returned data

Responses

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

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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/workspaces/{workspaceId}/teams

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/workspaces/{workspaceId}/teams

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/workspaces/{workspaceId}/teams/{teamId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/workspaces/{workspaceId}/teams/{teamId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/workspaces/{workspaceId}/teams/{teamId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/workspaces/{workspaceId}/teams/{teamId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/workspaces/{workspaceId}/views

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/workspaces/{workspaceId}/views

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/workspaces/{workspaceId}/views/{viewId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/workspaces/{workspaceId}/views/{viewId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/api/workspaces/{workspaceId}/views/{viewId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/api/workspaces/{workspaceId}/views/{viewId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/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.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/user/schedules

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/user/schedules

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/user/schedules

Parameters

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

Returned data

Responses

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

A paginated list of schedules.

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

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/user/schedules

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/user/schedules

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/user/schedules

Request body

application/json Required

Payload for upserting a schedule. Includes only client-settable fields.

Field	Type	Required	Description
`cronExpression`	string	Yes	Cron expression defining the schedule’s recurrence (e.g. “0 0 * * *” for daily at midnight).
`id`	string (uuid)	No	Existing schedule ID for updates; omit on create.
`name`	string	Yes	Human-readable name for the schedule.
`userId`	string (uuid)	No	Owner user ID; inferred from the authenticated user when omitted.

Returned data

Responses

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

A schedule defines a recurring cron-based trigger for performance tests or other automated tasks.

Field	Type	Required	Description
`id`	string (uuid)	No	Unique identifier for the schedule.
`name`	string	Yes	Human-readable name for the schedule.
`userId`	string (uuid)	Yes	UUID of the user who owns this schedule.
`cronExpression`	string	Yes	Cron expression defining the schedule’s recurrence (e.g. “0 0 * * *” for daily at midnight).
`lastRun`	string (date-time)	No	Server-computed timestamp of the schedule’s most recent execution. Null until the first run completes. Server-managed; clients must not set this on create/update.
`nextRun`	string (date-time)	No	Server-computed timestamp of the schedule’s next planned execution, derived from the cron expression. Server-managed; clients must not set this on create/update.
`createdAt`	string (date-time)	No	Timestamp when the schedule was created.
`updatedAt`	string (date-time)	No	Timestamp when the schedule was last updated.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/user/schedules/{scheduleId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/user/schedules/{scheduleId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/user/schedules/{scheduleId}

Parameters

Path parameters

Name	Type	Required	Description
`scheduleId`	string (uuid)	Yes	Schedule ID

Returned data

Responses

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

A schedule defines a recurring cron-based trigger for performance tests or other automated tasks.

Field	Type	Required	Description
`id`	string (uuid)	No	Unique identifier for the schedule.
`name`	string	Yes	Human-readable name for the schedule.
`userId`	string (uuid)	Yes	UUID of the user who owns this schedule.
`cronExpression`	string	Yes	Cron expression defining the schedule’s recurrence (e.g. “0 0 * * *” for daily at midnight).
`lastRun`	string (date-time)	No	Server-computed timestamp of the schedule’s most recent execution. Null until the first run completes. Server-managed; clients must not set this on create/update.
`nextRun`	string (date-time)	No	Server-computed timestamp of the schedule’s next planned execution, derived from the cron expression. Server-managed; clients must not set this on create/update.
`createdAt`	string (date-time)	No	Timestamp when the schedule was created.
`updatedAt`	string (date-time)	No	Timestamp when the schedule was last updated.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/user/schedules/{scheduleId}

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/user/schedules/{scheduleId}

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/user/schedules/{scheduleId}

Parameters

Path parameters

Name	Type	Required	Description
`scheduleId`	string (uuid)	Yes	Schedule ID

Returned data

Responses

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

ProviderCapability GET

/{version}/capabilities

Get the provider's capabilities

Returns the capabilities document for a client of the given version. Authentication is optional: with a valid token the document reflects the caller’s roles, and with a valid token plus X-Current-Orgid it also carries membership. An invalid or absent token is not an error; the document is returned without membership. A malformed X-Current-Orgid is a client error and returns 400. With client, the document carries compatibility for that client at {version}; an outdated client still receives 200 with compatible false. With a valid token the document carries session; for a live member of the X-Current-Orgid organization it includes that organization’s plan, entitlements and device usage.

Try this endpoint

Substitute your own Layer5 Cloud hostname when you are working against a hosted or self-managed instance.

Meshery Cloud production server URL

https://cloud.meshery.io/{version}/capabilities

Meshery Cloud staging server URL

https://staging-cloud.meshery.io/{version}/capabilities

Meshery Cloud development server URL (controlled via PORT environment variable)

http://localhost:9876/{version}/capabilities

Parameters

Path parameters

Name	Type	Required	Description
`version`	string	Yes	Version of the requesting client, for example `v0.8.0`.

Query parameters

Name	Type	Required	Description
`client`	string	No	Identifier of the requesting client application, for example the product name of a desktop app. When present, the document carries `compatibility` for this client at the `{version}` path parameter.
`os`	string	No	Operating system of the client, used to select packages.

Header parameters

Name	Type	Required	Description
`X-Current-Orgid`	string (uuid)	No	Organization whose membership the caller wants reported.

Returned data

Responses

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

The remote provider’s capabilities document. Existing fields describe the provider and its extensions; contractVersion and membership let a native client gate on the provider’s contract and on its organization membership after authenticating; compatibility tells a client that named itself whether its version is still accepted, and session describes the authenticated caller’s roles, plan and entitlements. New fields arrive only with a new contractVersion (1.1 added compatibility and session).

Field	Type	Required	Description
`capabilities`	array of object	No	Features the provider serves and their endpoints. Clients read paths from here instead of hard-coding them. A provider serving desktop connections lists `register-connection`, `connection-heartbeat` and `deregister-desktop-connection`; an endpoint may hold `{connectionId}` or `{installationId}` placeholders.
`compatibility`	object	No	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`.
`contractVersion`	string	No	Version of the provider’s REST contract for native clients, as `MAJOR.MINOR`. A client refuses a provider whose major differs from the one it was built against. A provider that predates this field omits it, which a client treats as not serving the contract.
`extensions`	object	No	Extension points; shape owned by the provider.
`membership`	object	No	Whether the authenticated caller is a live member of the organization named by `X-Current-Orgid`. Present only on an authenticated request that carried that header.
`packageUrl`	string	No	Download URL of that package.
`packageVersion`	string	No	Version of the extension package the provider offers this client.
`providerDescription`	array of string	No	Lines describing the provider.
`providerName`	string	No	Display name of the provider.
`providerType`	string	Yes	Provider type, for example `remote`.
`providerUrl`	string	No	Home page URL of the provider.
`redirects`	object	No	Redirect targets the provider serves to this client, keyed by name.
`restrictedAccess`	object	No	Access restrictions applied to this client; shape owned by the provider.
`session`	object	No	The authenticated caller’s session as the provider sees it: who the caller is, the caller’s roles, and, for the organization named by `X-Current-Orgid` when the caller is a live member of it, that organization’s roles, plan, entitlements and device usage. Present only on an authenticated request.

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.