Replicated instances API
The instances API from Replicated — 10 operation(s) for instances.
The instances API from Replicated — 10 operation(s) for instances.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/replicated-instances-api"
curl "https://apis.io/api/v1/apis?limit=25"
Discovery needs no key. Ratings and market analysis are Pro.
openapi: 3.2.0
info:
description: Manage enterprise portal users, install options, branding, documentation, email templates, and access control.
title: Vendor API V3 apps Instances API
contact:
name: Replicated, Inc.
url: http://www.replicated.com/
email: info@replicated.com
version: 3.0.0
servers:
- url: https://api.replicated.com/vendor/v3
tags:
- name: instances
paths:
/app/{app_id}/customer/{customer_id}/instance/{instance_id}/running-images:
get:
security:
- api_key: []
description: 'Required RBAC Policy: kots/app/[:appid]/license/[:licenseid]/read'
tags:
- instances
summary: Get running images for an instance.
operationId: getCustomerInstanceRunningImages
parameters:
- x-go-name: AppID
description: App identifier
name: app_id
in: path
required: true
schema:
type: string
- x-go-name: InstanceID
description: Instance identifier
name: instance_id
in: path
required: true
schema:
type: string
- x-go-name: CustomerID
description: Customer identifier
name: customer_id
in: path
required: true
schema:
type: string
- description: Optional cluster identifier to disambiguate instance_id
name: ClusterID
in: query
schema:
type: string
responses:
'200':
$ref: '#/components/responses/getCustomerInstanceRunningImagesResponse'
'401':
$ref: '#/components/responses/responseErrUnauthorized'
'403':
$ref: '#/components/responses/responseErrForbidden'
'404':
$ref: '#/components/responses/responseErrNotFound'
servers:
- url: https://api.replicated.com/vendor/v3
/app/{app_id}/customer/{customer_id}/instance/{instance_id}/scan:
get:
security:
- api_key: []
description: 'Retrieve security scan summaries for all images reported by a specific instance.
The response contains scan summaries in the same shape as the channel-based endpoint.
Required RBAC Policy: kots/app/[:appid]/license/[:licenseid]/read'
tags:
- instances
summary: Get security scan summaries for an instance.
operationId: getCustomerInstanceScan
parameters:
- x-go-name: AppID
description: App identifier
name: app_id
in: path
required: true
schema:
type: string
- x-go-name: CustomerID
description: Customer identifier
name: customer_id
in: path
required: true
schema:
type: string
- x-go-name: InstanceID
description: Instance identifier
name: instance_id
in: path
required: true
schema:
type: string
- description: Optional cluster identifier to disambiguate instance_id
name: ClusterID
in: query
schema:
type: string
responses:
'200':
$ref: '#/components/responses/getCustomerInstanceScan'
'401':
$ref: '#/components/responses/responseErrUnauthorized'
'403':
$ref: '#/components/responses/responseErrForbidden'
'404':
$ref: '#/components/responses/responseErrNotFound'
servers:
- url: https://api.replicated.com/vendor/v3
/app/{app_id}/customer/{customer_id}/instance/{instance_id}/scan/trigger:
post:
security:
- api_key: []
description: 'Sends a request to SecureBuild to scan a specific image from a customer instance.
This is typically used when no SBOM exists for an image.
Required RBAC Policy: kots/app/[:appid]/license/[:licenseid]/update'
tags:
- instances
summary: Trigger a security scan for an instance image.
operationId: triggerCustomerInstanceScan
parameters:
- x-go-name: AppID
description: App identifier
name: app_id
in: path
required: true
schema:
type: string
- x-go-name: CustomerID
description: Customer identifier
name: customer_id
in: path
required: true
schema:
type: string
- x-go-name: InstanceID
description: Instance identifier
name: instance_id
in: path
required: true
schema:
type: string
responses:
'200':
$ref: '#/components/responses/triggerCustomerInstanceScan'
'400':
$ref: '#/components/responses/responseErrBadRequest'
'401':
$ref: '#/components/responses/responseErrUnauthorized'
'403':
$ref: '#/components/responses/responseErrForbidden'
'404':
$ref: '#/components/responses/responseErrNotFound'
servers:
- url: https://api.replicated.com/vendor/v3
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerCustomerInstanceScanBody'
description: Request body for triggering a scan
required: true
/app/{app_id}/customer/{customer_id}/instance/{instance_id}/tags:
get:
security:
- api_key: []
description: 'Retrieve the tags associated with a specific customer instance, allowing teams to view metadata or categorization applied to that instance.
Required RBAC Policy: kots/app/[:appid]/license/[:licenseid]/read'
tags:
- instances
summary: Get tags for a instance.
operationId: getCustomerInstanceTags
parameters:
- x-go-name: AppID
description: App identifier
name: app_id
in: path
required: true
schema:
type: string
- x-go-name: InstanceID
description: Instance identifier
name: instance_id
in: path
required: true
schema:
type: string
- x-go-name: CustomerID
description: Customer identifier
name: customer_id
in: path
required: true
schema:
type: string
- description: Optional cluster identifier to disambiguate instance_id
name: ClusterID
in: query
schema:
type: string
responses:
'201':
$ref: '#/components/responses/getCustomerInstanceTagsResponse'
'401':
$ref: '#/components/responses/responseErrUnauthorized'
'403':
$ref: '#/components/responses/responseErrForbidden'
'404':
$ref: '#/components/responses/responseErrNotFound'
servers:
- url: https://api.replicated.com/vendor/v3
put:
security:
- api_key: []
description: 'Create or update tags for a specific customer instance.
Tags can be used for categorization, filtering, or metadata. Keys with empty values will remove the tag.
Required RBAC Policy: kots/app/[:appid]/license/[:licenseid]/update'
tags:
- instances
summary: Create or update the tags for an instance.
operationId: updateCustomerInstanceTags
parameters:
- x-go-name: AppID
description: App identifier
name: app_id
in: path
required: true
schema:
type: string
- x-go-name: InstanceID
description: Instance identifier
name: instance_id
in: path
required: true
schema:
type: string
- x-go-name: CustomerID
description: Customer identifier
name: customer_id
in: path
required: true
schema:
type: string
responses:
'201':
$ref: '#/components/responses/updateCustomerInstanceTagsResponse'
'401':
$ref: '#/components/responses/responseErrUnauthorized'
'403':
$ref: '#/components/responses/responseErrForbidden'
'404':
$ref: '#/components/responses/responseErrNotFound'
servers:
- url: https://api.replicated.com/vendor/v3
requestBody:
content:
application/json:
schema:
type: object
properties:
cluster_id:
description: Optional cluster identifier to disambiguate instance_id
type: string
x-go-name: ClusterID
tags:
description: Upsert (create or update) instance tags. A key with an empty value will result in a delete operation for the key=value pair.
type: array
items:
$ref: '#/components/schemas/InstanceTag'
x-go-name: Tags
description: 'Requried: true'
/app/{app_id}/customer/{customer_id}/instances:
get:
security:
- api_key: []
description: 'Return a list of all instances associated with a specific customer and app, including instance metadata and status.
Useful for tracking deployments and usage per customer.
Required RBAC Policy: kots/app/[:appid]/license/[:licenseid]/read'
tags:
- instances
summary: List customer instances.
operationId: listCustomerInstances
parameters:
- x-go-name: CustomerID
description: Customer identifier
name: customer_id
in: path
required: true
schema:
type: string
- x-go-name: AppID
description: App identifier
name: app_id
in: path
required: true
schema:
type: string
responses:
'200':
$ref: '#/components/responses/listCustomerInstancesResponse'
'400':
$ref: '#/components/responses/responseErrBadRequest'
'401':
$ref: '#/components/responses/responseErrUnauthorized'
'403':
$ref: '#/components/responses/responseErrForbidden'
'404':
$ref: '#/components/responses/responseErrNotFound'
servers:
- url: https://api.replicated.com/vendor/v3
/app/{app_id}/instance-tag-schema:
get:
security:
- api_key: []
description: 'Returns a map of distinct tag keys to their distinct values across all instances belonging to the app.
Required RBAC Policy: kots/app/[:appid]/read'
tags:
- instances
summary: Get the instance tag schema for an app.
operationId: getInstanceTagSchema
parameters:
- x-go-name: AppID
description: App identifier
name: app_id
in: path
required: true
schema:
type: string
responses:
'200':
$ref: '#/components/responses/getInstanceTagSchemaResponse'
'401':
$ref: '#/components/responses/responseErrUnauthorized'
'403':
$ref: '#/components/responses/responseErrForbidden'
'404':
$ref: '#/components/responses/responseErrNotFound'
servers:
- url: https://api.replicated.com/vendor/v3
/app/{app_id}/instance-tags:
post:
security:
- api_key: []
description: 'Accepts a list of instance IDs and returns their tags in a single response.
Required RBAC Policy: kots/app/[:appid]/license/[:licenseid]/read'
tags:
- instances
summary: Get tags for multiple instances.
operationId: getCustomerInstancesTagsBulk
parameters:
- x-go-name: AppID
description: App identifier
name: app_id
in: path
required: true
schema:
type: string
responses:
'200':
$ref: '#/components/responses/getCustomerInstancesTagsBulkResponse'
'400':
$ref: '#/components/responses/responseErrBadRequest'
'401':
$ref: '#/components/responses/responseErrUnauthorized'
'403':
$ref: '#/components/responses/responseErrForbidden'
'404':
$ref: '#/components/responses/responseErrNotFound'
servers:
- url: https://api.replicated.com/vendor/v3
requestBody:
content:
application/json:
schema:
type: object
properties:
clusterIds:
type: array
items:
type: string
x-go-name: ClusterIDs
instanceIds:
type: array
items:
type: string
x-go-name: InstanceIDs
required: true
/app/{app_id}/instances/archive:
post:
security:
- api_key: []
description: 'Archives multiple customer instances in a single request. Only development,
airgap, or inactive instances are eligible. Instances that cannot be archived
(e.g., active production instances or instances the caller lacks permission
for) are skipped and returned in the skipped array with a reason.
Required RBAC Policy: kots/app/[:appid]/license/[:licenseid]/update'
tags:
- instances
summary: Batch archive customer instances.
operationId: batchArchiveCustomerInstances
parameters:
- x-go-name: AppID
description: App identifier
name: app_id
in: path
required: true
schema:
type: string
responses:
'200':
$ref: '#/components/responses/batchArchiveCustomerInstancesResponse'
'400':
$ref: '#/components/responses/responseErrBadRequest'
'401':
$ref: '#/components/responses/responseErrUnauthorized'
'403':
$ref: '#/components/responses/responseErrForbidden'
'404':
$ref: '#/components/responses/responseErrNotFound'
servers:
- url: https://api.replicated.com/vendor/v3
requestBody:
content:
application/json:
schema:
type: object
properties:
instances:
type: array
items:
$ref: '#/components/schemas/BatchArchiveInstance'
x-go-name: Instances
required: true
/instance/{instance_id}/archive:
put:
security:
- api_key: []
description: 'Deactivate a customer instance, making it inactive and unavailable for future use.
Only development, airgap, or inactive instances can be archived.
Required RBAC Policy: kots/app/[:appid]/license/[:licenseid]/update'
tags:
- instances
summary: Archive an instance.
operationId: archiveCustomerInstance
parameters:
- x-go-name: InstanceID
description: Instance identifier
name: instance_id
in: path
required: true
schema:
type: string
- description: Optional cluster identifier to disambiguate instance_id
name: ClusterID
in: query
schema:
type: string
responses:
'200':
$ref: '#/components/responses/archiveCustomerInstanceResponse'
'401':
$ref: '#/components/responses/responseErrUnauthorized'
'403':
$ref: '#/components/responses/responseErrForbidden'
'404':
$ref: '#/components/responses/responseErrNotFound'
servers:
- url: https://api.replicated.com/vendor/v3
/instance/{instance_id}/unarchive:
put:
security:
- api_key: []
description: 'Restore a previously archived customer instance, making it active and available for use again.
Required RBAC Policy: kots/app/[:appid]/license/[:licenseid]/update'
tags:
- instances
summary: Unarchive an instance.
operationId: unarchiveCustomerInstance
parameters:
- x-go-name: InstanceID
description: Instance identifier
name: instance_id
in: path
required: true
schema:
type: string
- description: Optional cluster identifier to disambiguate instance_id
name: ClusterID
in: query
schema:
type: string
responses:
'200':
$ref: '#/components/responses/unarchiveCustomerInstanceResponse'
'401':
$ref: '#/components/responses/responseErrUnauthorized'
'403':
$ref: '#/components/responses/responseErrForbidden'
'404':
$ref: '#/components/responses/responseErrNotFound'
servers:
- url: https://api.replicated.com/vendor/v3
components:
responses:
responseErrUnauthorized:
description: Return if the caller is not authorized
content:
application/json:
schema:
type: object
properties:
message:
type: string
x-go-name: Message
responseErrForbidden:
description: Returned if the caller does not have the needed permission
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
message:
type: string
x-go-name: Message
messageCode:
type: string
x-go-name: MessageCode
x-go-name: Error
triggerCustomerInstanceScan:
description: TriggerCustomerInstanceScanResponse contains the response for triggering a scan
content:
application/json:
schema:
type: object
properties:
message:
type: string
x-go-name: Message
success:
type: boolean
x-go-name: Success
updateCustomerInstanceTagsResponse:
description: UpdateCustomerInstanceTagsResponse contains the response to update a instance tags
content:
application/json:
schema:
type: object
properties:
customerInstance:
$ref: '#/components/schemas/CustomerInstance'
error:
type: string
x-go-name: Error
listCustomerInstancesResponse:
description: ListCustomerInstancesResponse contains the JSON instances list
content:
application/json:
schema:
type: object
properties:
instances:
type: array
items:
$ref: '#/components/schemas/CustomerInstance'
x-go-name: Instances
batchArchiveCustomerInstancesResponse:
description: BatchArchiveCustomerInstancesResponse contains the bulk archive response.
content:
application/json:
schema:
type: object
properties:
archived:
type: integer
format: int64
x-go-name: Archived
error:
type: string
x-go-name: Error
skipped:
type: array
items:
$ref: '#/components/schemas/SkippedInstance'
x-go-name: Skipped
total:
type: integer
format: int64
x-go-name: Total
getInstanceTagSchemaResponse:
description: GetInstanceTagSchemaResponse contains the tag schema response
content:
application/json:
schema:
type: object
properties:
error:
type: string
x-go-name: Error
tags:
type: object
additionalProperties:
type: array
items:
type: string
x-go-name: Tags
unarchiveCustomerInstanceResponse:
description: UnarchiveCustomerInstanceResponse contains the response to unarchive an instance
content:
application/json:
schema:
type: object
properties:
customerInstance:
$ref: '#/components/schemas/CustomerInstance'
error:
type: string
x-go-name: Error
archiveCustomerInstanceResponse:
description: ArchiveCustomerInstanceResponse contains the response to archive an instance
content:
application/json:
schema:
type: object
properties:
customerInstance:
$ref: '#/components/schemas/CustomerInstance'
error:
type: string
x-go-name: Error
getCustomerInstanceRunningImagesResponse:
description: ''
content:
application/json:
schema:
type: object
properties:
error:
type: string
x-go-name: Error
running_images:
type: object
additionalProperties:
type: array
items:
type: string
x-go-name: RunningImages
getCustomerInstanceTagsResponse:
description: GetCustomerInstanceTagsResponse contains the response to update a instance tags
content:
application/json:
schema:
type: object
properties:
error:
type: string
x-go-name: Error
tags:
$ref: '#/components/schemas/InstanceTags'
getCustomerInstancesTagsBulkResponse:
description: GetCustomerInstancesTagsBulkResponse contains the bulk tags response
content:
application/json:
schema:
type: object
properties:
error:
type: string
x-go-name: Error
results:
type: array
items:
type: object
properties:
clusterId:
type: string
x-go-name: ClusterID
instanceId:
type: string
x-go-name: InstanceID
tags:
type: array
items:
$ref: '#/components/schemas/InstanceTagDTO'
x-go-name: Tags
x-go-name: Results
responseErrNotFound:
description: Returned on resource not found
content:
application/json:
schema:
type: object
properties:
message:
type: string
x-go-name: Message
responseErrBadRequest:
description: Returned on bad input
content:
application/json:
schema:
type: object
properties:
error_code:
description: Error code if available
type: string
x-go-name: ErrorCode
message:
description: Error message text if available
type: string
x-go-name: Message
getCustomerInstanceScan:
description: GetCustomerInstanceScanResponse contains the security scan summaries for the instance images.
content:
application/json:
schema:
type: object
properties:
scans:
type: array
items:
$ref: '#/components/schemas/SecurityScanWrapper'
x-go-name: Scans
schemas:
SecurityScanWrapper:
type: object
properties:
digest:
type: string
x-go-name: Digest
digest_first_seen_at:
type: string
x-go-name: DigestFirstSeenAt
image_size_bytes:
type: integer
format: int64
x-go-name: ImageSizeBytes
input:
type: string
x-go-name: Input
installation_phase:
description: 'InstallationPhase indicates the Embedded Cluster phase for the image ("", "online", or "airgap").
Application images have the phase "".
Infrastructure images used for Embedded Cluster in both online and airgap have the phase "online" or "airgap".
Infrastructure images used for Embedded Cluster only in airgap have the phase "airgap".'
type: string
x-go-name: InstallationPhase
last_scanned_at:
type: string
x-go-name: LastScannedAt
not_found:
type: boolean
x-go-name: NotFound
result:
$ref: '#/components/schemas/SecurityScanInfo'
sbom_status:
description: SBOM status tracking
type: string
x-go-name: SBOMStatus
sbom_status_message:
type: string
x-go-name: SBOMStatusMessage
sbom_status_updated_at:
type: string
x-go-name: SBOMStatusUpdatedAt
scan_status:
description: Scan status tracking
type: string
x-go-name: ScanStatus
scan_status_message:
type: string
x-go-name: ScanStatusMessage
scan_status_updated_at:
type: string
x-go-name: ScanStatusUpdatedAt
source_type:
$ref: '#/components/schemas/SourceType'
sources:
type: array
items:
$ref: '#/components/schemas/ImageSource'
x-go-name: Sources
x-go-package: github.com/replicatedhq/vandoor/pkg/securebuild/types
CustomerInstanceVersionHistory:
type: object
properties:
clusterId:
type: string
x-go-name: ClusterID
downstreamChannelId:
type: string
x-go-name: DownstreamChannelID
downstreamReleaseSequence:
type: integer
format: int64
x-go-name: DownstreamReleaseSequence
instanceId:
type: string
x-go-name: InstanceID
intervalLast:
type: string
format: date-time
x-go-name: IntervalLast
intervalStart:
type: string
format: date-time
x-go-name: IntervalStart
nativeHelmCount:
type: integer
format: int32
x-go-name: NativeHelmCount
replHelmCount:
type: integer
format: int32
x-go-name: ReplHelmCount
versionLabel:
type: string
x-go-name: VersionLabel
x-go-package: github.com/replicatedhq/vandoor/pkg/kots/customer/types
InstanceTags:
type: array
items:
$ref: '#/components/schemas/InstanceTag'
x-go-package: github.com/replicatedhq/vandoor/pkg/kots/customer/types
ImageSource:
type: object
properties:
chart_name:
type: string
x-go-name: ChartName
is_installer_only:
type: boolean
x-go-name: IsInstallerOnly
resource_kind:
type: string
x-go-name: ResourceKind
resource_name:
type: string
x-go-name: ResourceName
resource_namespace:
type: string
x-go-name: ResourceNamespace
x-go-package: github.com/replicatedhq/vandoor/pkg/securebuild/types
TriggerCustomerInstanceScanBody:
description: TriggerCustomerInstanceScanBody contains the body parameters for triggering a scan
type: object
required:
- image_name
- image_digest
properties:
cluster_id:
description: Optional cluster identifier to disambiguate instance_id
type: string
x-go-name: ClusterID
image_digest:
description: Image digest to scan
type: string
x-go-name: ImageDigest
image_name:
description: Image name to scan
type: string
x-go-name: ImageName
x-go-package: github.com/replicatedhq/vandoor/handlers/vendor-api/replv3/customers
ScannerDescriptor:
type: object
title: ScannerDescriptor captures the scanner metadata (e.g., Grype version).
properties:
name:
type: string
x-go-name: Name
version:
type: string
x-go-name: Version
x-go-package: github.com/replicatedhq/vandoor/pkg/securebuild/types
InstanceTagDTO:
description: InstanceTagDTO is a response-only shape without instanceId
type: object
properties:
key:
type: string
x-go-name: Key
origin:
type: string
x-go-name: Origin
value:
type: string
x-go-name: Value
x-go-package: github.com/replicatedhq/vandoor/handlers/vendor-api/replv3/customers
InstanceSecuritySummary:
description: InstanceSecuritySummary represents aggregated security information for an instance
type: object
properties:
imageCount:
type: integer
format: int64
x-go-name: ImageCount
lastScannedAt:
type: string
format: date-time
x-go-name: LastScannedAt
vulnerabilityCounts:
$ref: '#/components/schemas/VulnCounts'
x-go-package: github.com/replicatedhq/vandoor/pkg/securebuild/types
SecurityScanInfo:
type: object
properties:
counts:
$ref: '#/components/schemas/VulnCounts'
created_at:
type: string
x-go-name: CreatedAt
critical:
type: object
additionalProperties:
type: string
x-go-name: Critical
descriptor:
$ref: '#/components/schemas/ScannerDescriptor'
fixed_counts:
$ref: '#/components/schemas/VulnCounts'
high:
type: object
additionalProperties:
type: string
x-go-name: High
low:
type: object
additionalProperties:
type: string
x-go-name: Low
medium:
type: object
additionalProperties:
type: string
x-go-name: Medium
vulnerability_details:
type: array
items:
$ref: '#/components/schemas/VulnDetail'
x-go-name: VulnerabilityDetails
x-go-package: github.com/replicatedhq/vandoor/pkg/securebuild/types
BatchArchiveInstance:
type: object
properties:
clusterId:
type: string
x-go-name: ClusterID
instanceId:
type: string
x-go-name: InstanceID
licenseId:
type: string
x-go-name: LicenseID
x-go-package: github.com/replicatedhq/vandoor/handlers/vendor-api/replv3/customers
VulnCounts:
type: object
properties:
critical:
type: integer
format: int64
x-go-name: Critical
high:
type: integer
format: int64
x-go-name: High
low:
type: integer
format: int64
x-go-name: Low
medium:
type: integer
format: int64
x-go-name: Medium
total:
type: integer
format: int64
x-go-name: Total
x-go-package: github.com/replicatedhq/vandoor/pkg/securebuild/types
VulnDetail:
type: object
properties:
artifact_name:
type: string
x-go-name: ArtifactName
artifact_type:
type: string
x-go-name: ArtifactType
artifact_version:
type: string
x-go-name: ArtifactVersion
cve:
type: string
x-go-name: CVE
description:
type: string
x-go-name: Description
epss_percentile:
type: number
format: double
x-go-name: EpssPercentile
fix_state:
type: string
x-go-name: FixState
fix_versions:
type: array
items:
type: string
x-go-name: FixVersions
risk:
type: number
format: double
x-go-name: Risk
severity:
type: string
x-go-name: Severity
x-go-package: github.com/replicatedhq/vandoor/pkg/securebuild/types
SourceType:
description: 'SourceType classifies an image as either a Replicated platform image or a
vendor application image, so that consumers can distinguish vulnerabilities in
Replicated-shipped components from vulnerabilit
# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/replicated/refs/heads/main/openapi/replicated-instances-api-openapi.yml