Skip to main content

Introduction

The API documentation section includes documentation for Palette API and Local Management API.

Palette API

Palette offers a range of capabilities you can access through the REST APIs. These REST APIs are designed in accordance with open API standards, which ensure that the platform's features can be integrated with other applications and systems. By utilizing these APIs, you can tap into the platform's capabilities through programmatic methods. Use the APIs to build custom integrations and workflows that leverage the power of the Palette.

Paths

Every API's URI has the prefix of the version and the Palette resource, such as: v1/spectroclusters/...

Authentication

Palette supports two types of API authentication methods that can be used to authenticate API requests:

Authorization Token

You can acquire authorization tokens from Palette that have a 15-minute lifetime. The authorization token is passed as part of the HTTP request header. You can use the authorization token to authenticate and authorize the request. The header name is Authorization, and the token is the header value. Refer to the Authorization Token section to learn more about the authorization token.

API Key

You can use API keys to authenticate with the Palette API. API keys allow you to interact with Palette APIs without requiring user credentials such as username and password. The API key must be present in each API request to authenticate and authorize the request. The API Key is passed as part of the HTTP request header. The header name is apiKey, and the API key is the header value.

The following example shows how to pass the API key in the HTTP request header:

curl --location "https://api.spectrocloud.com/v1/spectroclusters/123456789?ProjectUid=12345678" \
--header 'Accept: application/json' \
--header "apiKey: 123456789"

Refer to the API Key section to learn how to create and manage API keys.

Requests

All requests are in the JSON format. In general, the request payload has three sections: metadata, spec and status.

  • Metadata consists of common attributes for all the resources such as ids, names, creation timestamps etc.
  • Spec consists of attributes that define the resource
  • Status contains the status information of the resource. The API does not support creating or modifying the status section.
info

Certain update request schemas have restricted spec resource definitions, and specific fields like uid and creation timestamp cannot be modified post-creation.

HTTP MethodDescription
POSTTo create a resource or a sub-resource.
PUTTo update the resource or a sub-resource. The PUT request will overwrite the existing resource data.
PATCHTo add, modify, remove a specific attribute or sub-resource within a resource.
DELETETo delete the resource.

Response Codes

The API returns standard HTTP response codes:

HTTP CodeDescription
200Request succeeded. The response payload will vary depending upon the API. Refer to the respective API response schema.
201A resource was successfully created. The response payload contains the uid of the created resource.
204Response without any content for a successful operation. These operations include update, delete and the other actions on the resource.
400Bad request. The request does not adhere to the API request payload schema.
401Missing authorization token or invalid authorization token.
403The API operation is forbidden for the user.
404The resource or the dependent resource is not found for the operation.
500Operational error. For 500 error code, the server responds with an explicit error code and an error message.

Palette API Lifecycle

Palette APIs maintain backward compatibility until deprecation. The three API phases in the lifecycle are Production, Sunset, and Deprecated. Spectro Cloud will inform users when APIs transition through this lifecycle.

Production

The Palette APIs are designed to work as intended and expected.

Sunset

As the API approaches deprecation because it is being replaced or will no longer be supported, a notice will be provided in the documentation that outlines our intent and provides a cut-off date. Within three months of the deprecation date, a notice will be shared that counts down to the end date and recommends the API to use instead.

Deprecated

We indicate that an API is deprecated when it is no longer supported or recommended for use by including a tag to indicate its state. The API documentation will remain available as a subsection of deprecated APIs.

info

The API lifecycle also applies to external-facing tools such as Terraform.

Versioning

The version information is included in the API URI, such as v1alpha1 or v1. Future APIs will increment the version, leaving the earlier version intact. The existing API request and response schema will be modified to add new attributes or query parameters while maintaining backward compatibility with earlier schemas. Prior notice will be given before advancing to the next version, and users will be advised to migrate to the new API.

Scope

Palette groups resources under either a Tenant or Project scope. When making API requests targeting resources belonging to a project, the project scope should be specified. To specify the project scope, use the HTTP header key ProjectUid with the value <Project Uid> in the API request. The ProjectUid needs to be specified for a request to be applied under a specific project scope.

Example:

 curl --location --request \
GET 'https://api.spectrocloud.com/v1/edgehosts/ad3d90ab-de6e-3e48-800f-4d663cec3060?resolvePackValues=false' \
--header 'Accept: application/json' \
--header 'ProjectUid: ad3d90ab-de6e-3e48-800f-4d663cec3060'
info

If you do not provide the ProjectUid header, then the assumed scope is of the tenant.

Pagination

API endpoints that return a list have a limit of 50 items per return payload. Pagination is necessary for this purpose. The API response for the list includes the listMeta resource that contains the continue token. To perform pagination, you need to check whether the continue token value is present in the API response. For subsequent requests, use the continue token as a query parameter to paginate the remaining resource items.

    "listmeta": {
"continue": "eyJvZmZzZXQiOjUwLCJjb3VudCI6MTE3LCJ0b2tlbiI6IiJ9",
"count": 117,
"limit": 50,
"offset": 50
}

Example of a subsequent request using the continue token.

curl --location 'https://api.spectrocloud.com/v1/packs?continue=eyJvZmZzZXQiOjUwLCJjb3VudCI6MTE3LCJ0b2tlbiI6IiJ9' \
--header 'Accept: application/json' \
--header 'ProjectUid: yourProjectUid' \
--header 'apiKey: yourAPIKey'

Rate Limits

The API rate limits are as follows:

  • There is a limit of ten API requests per second for each source IP address. The API supports additional bursts through the usage of a burst queue. The default burst queue size is set to five. You could make 50 (10 * 5) requests in seconds before the API returns a 429 - TooManyRequests error. Refer to the Endpoint Prefix Rate for additional information.

  • API request limits are categorized by the parent resources, such as /v1/cloudconfig/:uid and /v1/roles. You can find a list of all resource types in the API documentation. The requests are counted together if you make multiple requests to the same resource type but use different sub-resources. For example, if you make five requests to /v1/clusterprofiles and five requests to /v1/clusterprofiles/macros, the requests are counted together as ten requests to the resource clusterprofiles.

  • If too many requests are issued, you may receive an error with HTTP code 429 - TooManyRequests. We recommend retrying the API call after a few moments.

Endpoint Prefix Rate

Endpoint PrefixRequest Per SecondBurst SizeMax with Burst
/v1/auth10550
/v1/nats10550
/v1/users10550
/v1/userprofiles10550
/v1/permissions10550
/v1/roles10550
/v1/teams10550
/v1/tenants10550
/v1/projects10550
/v1/plans10550
/v1/payments10550
/v1/audits10550
/v1/apiKeys10550
/v1/datasinks10550
/v1/notifications10550
/v1/events10550
/v1/crypto10550
/v1/async10550
/v1/errlogs10550
/v1/jobs10550
/v1/health10550
/v1/cache10550
/v1/cloudaccounts10550
/v1/packs10550
/v1/workspaces10550
/v1/installers10550
/v1/git/webhook10550
/v1/registries10550
/v1/services10550
/v1/overlords10550
/v1/cluster10550
/v1/cloudconfigs10550
/v1/cloudconfigs/{cloudType}/{uid}/machinePools10550
/v1/edgehosts10550
/v1/metrics10550
/v1/system10550
/v1/mgmt10550
/v1/oidc10550
/v1/clouds10550
/v1/events/components10550
/v1/dashboard10550
/v1/cloudconfigs/{cloudType}/:uid/machinePools/{machinePoolName}/machines10550
/v1/cloudconfigs/{cloudType}/:uid/machinePools/{machinePoolName}/machines/:machineUid10550
/v1/auth/authenticate10550
/v1/auth/services/login10550
/v1/auth/services/edge/login10550
/v1/files10550
/v1/edgehosts/registers10550
/v1/edgehosts/:uid/health10550
/v1/edgehosts/:uid/spc/download10550
/v1/spectroclusters/features/logFetcher10550
/v1/spectroclusters/:uid/assets10550
/v1/spectroclusters/cost10550
/v1/spectroclusters/usage10550
/v1/spectroclusters/:uid/download10550
/v1/spectroclusters/acquire10550
/v1/auth/user/password/reset2510
/v1/spectroclusters505250
/v1/clusterprofiles505250
/v1/clusterprofiles/:uid/packs505250
/v1/clusterprofiles/:uid/packs/manifests505250
/v1/clusterprofiles/:uid/packs/{packName}/manifests505250
/v1/clusterprofiles/validate/packs505250
/v1/clusterprofiles/:uid/validate/packs505250
/v1/spectroclusters/:uid/profiles505250

Local Management API

An Edge host has its own set of API endpoints. These API endpoints are available on each Edge host instead of on a Palette instance. You can use Local Management API endpoints to programmatically perform tasks such as retrieve information about Edge clusters, retrieve the list of available images on your Edge host, and create local clusters using embedded cluster definitions.

You can find the Open API Swagger specification for the Local Management API at the following location: https://raw.githubusercontent.com/spectrocloud/librarium/version-4-3/docs/api-content/api-docs/edge-v1/emc-api.json

tech preview
This is a Tech Preview feature and is subject to change. Do not use this feature in production workloads.

Authentication

Use the POST /v1/users/default/login endpoint to generate an authentication token with your OS username and password. The following curl command is an example. Replace edge-host-ip with the IP of your Edge host and replace os-username and os-password with your OS user credentials.

curl --location 'https://edge-host-ip:5080/v1/users/default/login' \
--header 'Content-Type: application/json' \
--data '{
"username": "os-username",
"password": "os-password"
}'

If your credentials are valid, you will receive a authorization token.

{
"Token": {
"Authorization": "******"
}
}

Include this token in the header of your subsequent requests to the Local Management API to authenticate your requests. For example, the following request retrieves information about the Edge host such as the processor architecture and the host name.

curl --location 'https://10.10.135.182:5080/v1/edge-mgmt/edgehosts/current' \
--header 'Authorization: *******'
{
"metadata": {
"creationTimestamp": "2024-02-29T20:31:42.204Z",
"id": "edge-bc4a38428b71300e371150263b651b8d",
"lastModifiedTimestamp": "0001-01-01T00:00:00.000Z",
"name": "edge-bc4a38428b71300e371150263b651b8d"
},
"spec": {
"connectionMode": "airgap",
"hardwareSpec": {
"archType": "amd64",
"cpu": {
"cores": 4
},
"disks": [
{
"controller": "SCSI",
"partitions": [
{
"fileSystemType": "ext4",
"freeSpace": 13,
"mountPoint": "/run/initramfs/cos-state",
"totalSpace": 24,
"usedSpace": 9
}
],
"size": 300,
"vendor": "VMware"
},
{
"controller": "SCSI",
"partitions": [],
"size": 4,
"vendor": "NECVMWar"
},
{
"controller": "SCSI",
"partitions": [],
"vendor": "NECVMWar"
}
],
"gpus": [],
"memory": {
"sizeInMB": 7930
},
"os": {
"family": "kairos-core-sles",
"version": "v2.4.3"
}
},
"networkInfo": [
{
"dns": [
"10.10.128.8"
],
"gateway": "10.10.128.1",
"ip": "10.10.135.182",
"isDefault": true,
"macAddr": "00:50:56:b8:9e:98",
"nicName": "ens160",
"subnet": "255.255.192.0"
}
]
},
"status": {
"agentVersion": "4.3.0-rc4",
"configurationStatus": "pending",
"dns": {
"nameservers": [
"10.10.128.8"
],
"options": [],
"searchDomains": [
"."
]
},
"hostName": "edge-bc4a38428b71300e371150263b651b8d",
"ntp": {
"fallbackNtpServers": [],
"ntpServers": []
},
"registrationStatus": "not applicable"
}
}