--- title: "REST API" description: "User Documentation for the Nirmata REST API" diataxis: reference applies_to: product: "nirmata-control-hub" audience: ["platform-engineer","developer"] last_updated: 2026-03-25 url: https://docs.nirmata.io/docs/reference/rest-api/ --- > **Applies to:** Nirmata Control Hub 4.0 and later Nirmata provides a REST API for easy integrations using any language of your choice. The API provides support for all operations that can be performed from the Nirmata Web Console or Command Line Tools. --- ## API Compatibility The API is currently in development and is likely to change. Although we will strive to maintain compatibility, some changes may break existing integrations. --- ## Get Deployment Details ## Get all Catalog Applications Request: GET /api/catalog/applications Accept: application/json Authorization: NIRMATA-API ## Get Deployment Details The mode parameter is used to export all relations. Request: GET /api/catalog/deployments/fbd5098b-a096-41f0-9f95-a012b9c86d96?mode=exportDetails Accept: application/json Authorization: NIRMATA-API ### Create an Application Request: POST https://www.nirmata.io/api/applications/ Accept: application/json Authorization: NIRMATA-API { "name": "test-app", } ### Delete an Application Request: DELETE /api/catalog/applications/c7bf4bfa-346e-44f8-b62c-9b8fdf5c1980 Accept: application/json Authorization: NIRMATA-API ### Get the UUID of an Application named 'helloworld' in YAML format Request: GET /catalog/api/applications?query={"name": "helloworld"}&fields=id&output=YAML Accept: application/json Authorization: NIRMATA-API Response Headers: HTTP/1.1 200 OK ... Response Body: --- - id: bdf910d6-f12d-4a9d-84e6-bfbae806c558 ### Get all running Applications' IDs, names, and states Request: GET /environments/api/applications?fields=id,name,state Accept: application/json Authorization: NIRMATA-API Response Headers: HTTP/1.1 200 OK ... Response Body: [ { "id" : "76e72cd9-01dd-490e-be8b-a36951a21881", "name" : "nginx", "state" : "running", "run" : "nginx" }, { "id" : "97a1352d-4a0c-44b7-8ca6-0e264a203a59", "name" : "shopme", "state" : "running", "run" : "shopme" }, { "id" : "6a863004-02d7-4a64-85e6-004a140a5823", "name" : "aqua-csp", "state" : "running", "run" : "aqua-csp" }, { "id" : "bbab3d4f-17d7-45df-883a-e96d5a35def0", "name" : "shopmek8s", "state" : "running", "run" : "dealsapp" }, { "id" : "9b559b77-4d88-42ca-8280-5145ac3fe9f3", "name" : "shopmek8s", "state" : "running", "run" : "dealsapp" }, { "id" : "252cdc4b-69f2-4bb4-a688-170b95e516cc", "name" : "guestbook", "state" : "running", "run" : "guestbook" }, { "id" : "829e362c-cde2-4d06-b1c2-96bef10faed9", "name" : "guestbook", "state" : "running", "run" : "guestbook" }, { "id" : "343b46f2-6b93-45ac-b38b-bdbc2d133f1e", "name" : "guestbook", "state" : "running", "run" : "guestbook-2" } ] ### Create a new Environment Request: POST /api/environments/ Accept: application/json Authorization: NIRMATA-API { "name": "dev-test", "hostCluster": {"name" : "devtest-aks-us-east"} } Note the different ways you can specify a relation in the JSON. For a 1-1 relationship you can: 1. Specify an UUID 2. Specify a JSON object with fields that can be used to find the relation. In the example above, we use the name field to query the Cluster. ### Run an Application in an Environment Request Headers: POST /catalog/api/applications/248ea469-50f2-4b8c-af55-f13a5527a356/run Accept: application/json Authorization: NIRMATA-API Request Body: { "run": "hello1", "environment": "dev-test" } ### Find all Deployments and replica counts in running Applications Request: GET /environments/api/applications?mode=exportDetails&fields=id,name,deployments,spec,replicas Accept: application/json Authorization: NIRMATA-API Response Headers: HTTP/1.1 200 OK ... Response Body: [ { "id": "76e72cd9-01dd-490e-be8b-a36951a21881", "name": "nginx" }, { "id": "97a1352d-4a0c-44b7-8ca6-0e264a203a59", "name": "shopme", "deployments": [ { "id": "f23fb091-ec86-4b1c-aff9-744132d218b5", "name": "payment", "spec": [ { "id": "8497448a-8cb0-4a38-9aac-ea941e226bce", "replicas": 1 } ] }, { "id": "00979b37-05be-4b09-b5c7-7af68cb7d0c6", "name": "deals", "spec": [ { "id": "1d6ef0d7-91df-452c-b8af-ebf91f3e6b09", "replicas": 1 } ] }, { "id": "a01d5c5d-d5ae-4fc2-9fe9-6ee57ded98b0", "name": "ratings", "spec": [ { "id": "8e0ed849-282a-40b0-8e7c-26ed7f4d8f26", "replicas": 2 } ] } ] }, { "id": "6a863004-02d7-4a64-85e6-004a140a5823", "name": "aqua-csp", "deployments": [ { "id": "62a4ff2f-ad59-4479-9ba0-ee4104a13ce4", "name": "aqua-all-in-one", "spec": [ { "id": "3ae07e78-0ae2-4672-b1df-56330a0c8b47", "replicas": 1 } ] } ] }, { "id": "bbab3d4f-17d7-45df-883a-e96d5a35def0", "name": "shopmek8s", "deployments": [ { "id": "ec383532-8659-4a34-8d76-7eb5d85ffda3", "name": "deals", "spec": [ { "id": "2da3cf04-2cee-4166-9491-566f5c9b3e27", "replicas": 3 } ] } ] }, { "id": "9b559b77-4d88-42ca-8280-5145ac3fe9f3", "name": "shopmek8s", "deployments": [ { "id": "a9313032-1b82-40dd-b45a-4dabd0689102", "name": "deals", "spec": [ { "id": "f9f861e8-defc-433c-b8f0-32c58d2a2fb1", "replicas": 3 } ] } ] }, { "id": "252cdc4b-69f2-4bb4-a688-170b95e516cc", "name": "guestbook", "deployments": [ { "id": "27d56ae0-c58f-46a0-8b59-ca752f2fa109", "name": "frontend", "spec": [ { "id": "ad1dcaf3-46fe-4c7d-8891-adfeadc1dc95", "replicas": 3 } ] }, { "id": "0b4f6d2e-28ac-4411-b98b-c9fe4875fc7d", "name": "redis-master", "spec": [ { "id": "6f5659de-0a4c-4dbb-8baa-62a690d8538f", "replicas": 1 } ] }, { "id": "6d58b6cd-3179-4cdf-97f6-a273970540bf", "name": "redis-slave", "spec": [ { "id": "7a01d526-0aaf-47ee-885d-b695a8ac8d2b", "replicas": 2 } ] } ] }, { "id": "829e362c-cde2-4d06-b1c2-96bef10faed9", "name": "guestbook", "deployments": [ { "id": "1f539cf6-41cd-4739-8872-13409bba612d", "name": "frontend", "spec": [ { "id": "32c81a2d-145f-4858-8be9-6669c2044079", "replicas": 5 } ] }, { "id": "8cd3b93e-2994-4f11-acef-5b4e830e252c", "name": "redis-master", "spec": [ { "id": "87986a72-c250-4002-b4b6-c95cdada3b42", "replicas": 1 } ] }, { "id": "003bf3e2-065c-4a32-ac7b-fd2802e49a55", "name": "redis-slave", "spec": [ { "id": "2069f1fd-1410-4569-9968-60cbabd140e1", "replicas": 2 } ] } ] }, { "id": "343b46f2-6b93-45ac-b38b-bdbc2d133f1e", "name": "guestbook", "deployments": [ { "id": "50a1ed10-0167-4c8e-b8b1-a6319bef3cfb", "name": "frontend", "spec": [ { "id": "576d2453-b139-4b38-a973-bda0afd9fa6c", "replicas": 6 } ] }, { "id": "cad14b31-7d14-46c1-81db-bb1430adb300", "name": "redis-master", "spec": [ { "id": "de9d4e5e-f044-46b6-b147-2e9009c07f1b", "replicas": 1 } ] }, { "id": "0ef0caf9-b6ad-4a56-9f35-0e4c47a85627", "name": "redis-slave", "spec": [ { "id": "1e487ab6-509a-4906-9717-49a2beb59cab", "replicas": 2 } ] } ] }, { "id": "40d39730-ea05-4b0c-b78b-5d2d0008606b", "name": "dev-test2" } ] ### Scale a Deployment in a running Application Request: PUT /environments/api/deploymentSpecs/1d6ef0d7-91df-452c-b8af-ebf91f3e6b09 Accept: application/json Authorization: NIRMATA-API Request Body: { "replicas" : 3 } Response Headers: HTTP/1.1 200 OK ... Response Body: { "id" : "1d6ef0d7-91df-452c-b8af-ebf91f3e6b09", "service" : "Environments", "modelIndex" : "DeploymentSpec", "uri" : "/environments/api/deploymentSpecs/1d6ef0d7-91df-452c-b8af-ebf91f3e6b09", "parent" : { "id" : "00979b37-05be-4b09-b5c7-7af68cb7d0c6", "service" : "Environments", "modelIndex" : "Deployment", "uri" : "/environments/api/deployments/00979b37-05be-4b09-b5c7-7af68cb7d0c6", "childRelation" : "spec" }, "createdBy" : "ritesh@nirmata.com", "createdOn" : 1526011140575, "modifiedBy" : "jim@nirmata.com", "modifiedOn" : 1526854556236, "generation" : 1, "ancestors" : [ { "modelIndex" : "Deployment", "uuid" : "00979b37-05be-4b09-b5c7-7af68cb7d0c6", "service" : "Environments" }, { "modelIndex" : "Application", "uuid" : "97a1352d-4a0c-44b7-8ca6-0e264a203a59", "service" : "Environments" }, { "modelIndex" : "Environment", "uuid" : "ca8b2b15-1920-4910-9c34-846bee4ce6fe", "service" : "Environments" }, { "modelIndex" : "Root", "uuid" : "0b02a1ac-fae0-4b49-86e9-ff7a421cdf5c", "service" : "Environments" } ], "additionalProperties" : { }, "alarms" : [ ], "additionalProperties" : { }, "minReadySeconds" : null, "paused" : null, "progressDeadlineSeconds" : null, "replicas" : 3, "revisionHistoryLimit" : 5, "selector" : { "matchLabels" : { "nirmata.io/application.run" : "shopme", "nirmata.io/environment.name" : "centos-env", "nirmata.io/service.name" : "deals", "nirmata.io/application.name" : "shopme", "nirmata.io/component" : "deals" }, "matchExpressions" : [ ] }, "strategy" : [ { "id" : "cdc7cb74-6f27-4908-a358-55e4d79205e8", "service" : "Environments", "modelIndex" : "DeploymentStrategy", "uri" : "/environments/api/deploymentStrategies/cdc7cb74-6f27-4908-a358-55e4d79205e8" } ], "template" : [ { "id" : "b53af823-dbdd-41d9-b08f-e1c37378b7e9", "service" : "Environments", "modelIndex" : "PodTemplateSpec", "uri" : "/environments/api/podTemplateSpecs/b53af823-dbdd-41d9-b08f-e1c37378b7e9" } ] } ### Get the image versions for a container Request: GET https://nirmata.io/environments/api/containers?fields=name,id,image&query={"name" : "php-redis"} Accept: application/json Authorization: NIRMATA-API Response Headers: HTTP/1.1 200 OK ... Response Body: [ { "id": "04c9ada6-8e62-408e-8bb7-4c5bc5e1db3b", "name": "php-redis", "image": "gcr.io/google-samples/gb-frontend:v4" }, { "id": "1ca543fd-f406-4591-b786-382f8d34cac1", "name": "php-redis", "image": "gcr.io/google-samples/gb-frontend:v4" }, { "id": "9f70e9b5-7aa0-4056-ac0a-1c4c6edb0c6b", "name": "php-redis", "image": "gcr.io/google-samples/gb-frontend:v4" }, { "id": "53ac22ae-5d32-4341-bf19-fc2e3a27b4f4", "name": "php-redis", "image": "gcr.io/google-samples/gb-frontend:v4" }, { "id": "24ae386e-ecc3-4b66-aab0-6e5364f06491", "name": "php-redis", "image": "gcr.io/google-samples/gb-frontend:v5" }, { "id": "c4a11f29-48f1-4184-a05d-4f8d1a1760ab", "name": "php-redis", "image": "gcr.io/google-samples/gb-frontend:v5" }, { "id": "e7f753f1-9ab6-458d-a743-3bf4f9b3e44e", "name": "php-redis", "image": "gcr.io/google-samples/gb-frontend:v5" }, { "id": "40e95708-5bac-4b70-8591-7543aea01c6b", "name": "php-redis", "image": "gcr.io/google-samples/gb-frontend:v5" }, { "id": "8cf514ca-f969-49f3-acc1-8d3dfbeef323", "name": "php-redis", "image": "gcr.io/google-samples/gb-frontend:v5" }, { "id": "cd429f72-356e-41f6-b481-7c3cb1218b79", "name": "php-redis", "image": "gcr.io/google-samples/gb-frontend:v5" }, { "id": "f33d7bb0-ecf3-403e-9d6f-5715bbe6cee4", "name": "php-redis", "image": "gcr.io/google-samples/gb-frontend:v5" }, { "id": "97ca084f-e7cb-42c5-9b8b-f3d7f4c6914c", "name": "php-redis", "image": "gcr.io/google-samples/gb-frontend:v5" }, { "id": "f4b0cb92-8aa6-4b5a-81a1-c51b7d0e3234", "name": "php-redis", "image": "gcr.io/google-samples/gb-frontend:v5" }, { "id": "ffe03a27-be3f-4e81-b3f3-068bae378451", "name": "php-redis", "image": "gcr.io/google-samples/gb-frontend:v5" }, { "id": "6b37a537-fce8-41f0-a5c1-bce980f23391", "name": "php-redis", "image": "gcr.io/google-samples/gb-frontend:v5" }, { "id": "dbc0f31c-bc02-4a08-adb1-f994e9e130df", "name": "php-redis", "image": "gcr.io/google-samples/gb-frontend:v5" }, { "id": "9bb53549-572c-499b-9bad-1d51079e13f2", "name": "php-redis", "image": "gcr.io/google-samples/gb-frontend:v5" } ] ### Update image version for a running container Request Headers: PUT /environments/api/containers/9bb53549-572c-499b-9bad-1d51079e13f2 Request Body: { "image" : "gcr.io/google-samples/gb-frontend:v6" } Response Headers: HTTP/1.1 200 OK ... Response Body: { "id" : "9bb53549-572c-499b-9bad-1d51079e13f2", "service" : "Environments", "modelIndex" : "Container", "uri" : "/environments/api/containers/9bb53549-572c-499b-9bad-1d51079e13f2", "tenantId" : "45b34043-2844-48ca-b14c-a1944d322c8c", "parent" : { "id" : "6f40ca06-80c7-4a56-b582-5e05586b3b49", "service" : "Environments", "modelIndex" : "PodSpec", "uri" : "/environments/api/podSpecs/6f40ca06-80c7-4a56-b582-5e05586b3b49", "childRelation" : "containers" }, "createdBy" : "Nirmata", "createdOn" : 1526333823626, "modifiedBy" : "jim@nirmata.com", "modifiedOn" : 1526855075468, "generation" : 1, "ancestors" : [ { "modelIndex" : "PodSpec", "uuid" : "6f40ca06-80c7-4a56-b582-5e05586b3b49", "service" : "Environments" }, { "modelIndex" : "Pod", "uuid" : "e0d8c535-fd4f-4a5c-a36c-2defbbc1f124", "service" : "Environments" }, { "modelIndex" : "Application", "uuid" : "343b46f2-6b93-45ac-b38b-bdbc2d133f1e", "service" : "Environments" }, { "modelIndex" : "Environment", "uuid" : "37594c41-bbb3-4ee4-a04c-a84cc2ca7a10", "service" : "Environments" }, { "modelIndex" : "Root", "uuid" : "0b02a1ac-fae0-4b49-86e9-ff7a421cdf5c", "service" : "Environments" } ], "additionalProperties" : { "envFrom" : [ ] }, "alarms" : [ ], "name" : "php-redis", "image" : "gcr.io/google-samples/gb-frontend:v6", "command" : [ ], "args" : [ ], "workDir" : null, "terminationMessagePath" : "/dev/termination-log", "terminationMessagePolicy" : "File", "imagePullPolicy" : "IfNotPresent", "stdin" : null, "stdinOnce" : null, "tty" : null, "ports" : [ { "id" : "964460ff-0508-432c-a0db-78390ab85e09", "service" : "Environments", "modelIndex" : "ContainerPort", "uri" : "/environments/api/containerPorts/964460ff-0508-432c-a0db-78390ab85e09" } ], "env" : [ { "id" : "d07dc2d5-d583-45f7-a05e-b9e249c94412", "service" : "Environments", "modelIndex" : "EnvVar", "uri" : "/environments/api/envVars/d07dc2d5-d583-45f7-a05e-b9e249c94412" } ], "volumeMounts" : [ { "id" : "87b4b177-88a7-4d2f-aaa1-622d4dd41ddf", "service" : "Environments", "modelIndex" : "VolumeMount", "uri" : "/environments/api/volumeMounts/87b4b177-88a7-4d2f-aaa1-622d4dd41ddf" } ], "livenessProbe" : [ ], "readinessProbe" : [ ], "lifecycle" : [ ], "resources" : [ { "id" : "1050e112-8898-4d57-8be6-f426f1905a90", "service" : "Environments", "modelIndex" : "ResourceRequirements", "uri" : "/environments/api/resourceRequirements/1050e112-8898-4d57-8be6-f426f1905a90" } ], "securityContext" : [ ] } ### Select a PodTemplateSpec and output as YAML Request: GET https://nirmata.io/environments/api/podTemplateSpecs?labelSelector="nirmata.io/environment.name=qa-environment,nirmata.io/application.run=guestbook,nirmata.io/component=redis-slave"&mode=export&output=yaml Accept: application/json Authorization: NIRMATA-API Response Headers: HTTP/1.1 200 OK Content-type: text/x-yaml;charset=UTF-8 ... Response Body: metadata: - labels: app: redis role: slave tier: backend nirmata.io/deployment.name: redis-slave nirmata.io/application.run: guestbook nirmata.io/environment.name: qa-environment nirmata.io/service.name: redis-slave nirmata.io/application.name: guestbook nirmata.io/component: redis-slave spec: - terminationGracePeriodSeconds: 30 containers: - name: slave image: gcr.io/google_samples/gb-redisslave:v1 ports: - containerPort: 6379 protocol: TCP env: - name: GET_HOSTS_FROM value: dns ### Apply YAML updates to a running Application Request: curl -X POST -H "Content-type: text/yaml" -H "Authorization: NIRMATA-API $APIKEY" "https://nirmata.io/environments/api/applications/829e362c-cde2-4d06-b1c2-96bef10faed9/import" --data-binary @redis-slave.yml Response: { "status" : 200, "message" : "Success", "changes" : { "user" : "jim@nirmata.com", "createdIds" : [ ], "modifiedIds" : [ { "modelIndex" : "Container", "uuid" : "1dff2449-a4f3-46a8-9b85-ad97eb0926d3", "service" : "Environments" } ], "deletedIds" : [ ], "sequenceId" : "dbe828e0-c079-4cc5-9562-f8c680fd8529", "timestamp" : 1526888853548, "empty" : false, "id" : "38c87ee5-0585-406e-82ac-5840551a8bef" } } ### Get CPU and memory usage for all Clusters Request: GET /cluster/api/hostClusters?mode=exportDetails&fields=id,name,kubernetesCluster,clusterStats,cpuUsagePercent,memoryUsagePercent Accept: application/json Authorization: NIRMATA-API Response Headers: HTTP/1.1 200 OK ... Response Body: [ { "id": "b33efdd1-7c10-4ca9-9c7d-a6e6baf65c4e", "name": "prod-cluster", "kubernetesCluster": [ { "id": "a6795f23-0801-4023-849c-9a7595e1e921", "clusterStats": [ { "id": "eafb354f-5c7e-4c6b-a6b7-e2ea0053c00f", "cpuUsagePercent": 15.6, "memoryUsagePercent": 59.060432 } ] } ] }, { "id": "fc91f1f5-6bb8-49d0-a506-cb770515a141", "name": "test-centos", "kubernetesCluster": [ { "id": "6619ae16-a8a0-4374-9ad7-baf5d0590f7d", "clusterStats": [ { "id": "6118e6dd-2536-43f7-9a79-1d2885a1aa7a", "cpuUsagePercent": 8.175, "memoryUsagePercent": 55.651302 } ] } ] }, { "id": "49202821-a458-45c8-8799-1a79e012471b", "name": "devtest-aks-us-east", "kubernetesCluster": [ { "id": "22259547-fd15-4a66-ba42-ae24ccb82563", "clusterStats": [ { "id": "286912b7-70ce-439e-8a59-0f51d9d2c0f4", "cpuUsagePercent": 0, "memoryUsagePercent": 0 } ] } ] }, { "id": "f8aa846f-9c2d-4b2c-838f-23a8132ba78e", "name": "prod-azure-cluster", "kubernetesCluster": [ { "id": "3b026363-7f11-4ef7-a418-c8f73a34f6da", "clusterStats": [ { "id": "dbcea04b-7263-49b8-b9cd-f610782da5f0", "cpuUsagePercent": 3.975, "memoryUsagePercent": 13.631612 } ] } ] }, { "id": "cde8bdd5-37f4-445c-bf67-399fc22fffde", "name": "prod-aks-us-east2", "kubernetesCluster": [ { "id": "e8535a60-122a-41cc-9aac-b619dc3a3b8b", "clusterStats": [ { "id": "3ca358c1-c21a-43e1-a24a-770438515d57", "cpuUsagePercent": 0, "memoryUsagePercent": 0 } ] } ] }, { "id": "933951fe-da2e-4bb1-a7d5-8dd092ff4ca2", "name": "aks-demo", "kubernetesCluster": [ { "id": "b4d8884d-e4c9-4881-8997-74b9a1bffa39", "clusterStats": [ { "id": "0dd79692-4ded-442d-a3a2-6519ee114901", "cpuUsagePercent": 0, "memoryUsagePercent": 0 } ] } ] }, { "id": "c9bc4e81-4140-4120-afd1-4c8dc4b88574", "name": "diamanti-cluster-1", "kubernetesCluster": [ { "id": "c2d32dce-9e7b-4f03-9f2c-93936635c793", "clusterStats": [ { "id": "f21799b0-0ad7-40e3-a999-9c61fe022b00", "cpuUsagePercent": 0, "memoryUsagePercent": 0 } ] } ] } ] ### Get select properties of all hosts Request: GET https://nirmata.io/config/api/cloudProviders?fields=id,name,hostGroups,hosts,desiredCount,type,minHosts,maxHosts,type&mode=exportDetails Accept: application/json Authorization: NIRMATA-API Sample Response Body: [ { "id": "a41f0493-f6e0-45d6-b56b-41ab93d9d392", "type": "Other", "name": "Direct Connect", "hostGroups": [ { "id": "2d6e6890-0c7a-4339-b6d0-8550fc98766b", "name": "baremetal", "desiredCount": 3, "minHosts": 0, "maxHosts": 5, "hosts": [ { "id": "d5941122-8a9a-485f-a63a-f3b57bc220da", "name": "baremetal-3" }, { "id": "edc8addf-756a-4427-9286-4f93aff2530a", "name": "baremetal-2" }, { "id": "3901d892-b8c5-4495-a6e7-23bc71b9ba0a", "name": "baremetal-1" } ] }, { "id": "f8f978db-8047-41db-95c4-dbab4501317c", "name": "test-centos", "desiredCount": 1, "minHosts": 0, "maxHosts": 5, "hosts": [ { "id": "09fa7f0b-b06b-4f6d-a802-9013a16c731c", "name": "ritesh-centos-92966" }, { "id": "b15a29f0-01b9-4986-bc60-da59f92ac5ab", "name": "ritesh-centos-84460" } ] }, { "id": "efbe477f-7f18-40b2-87ec-a8078602fb30", "name": "devtest-aks-us-east-hg", "desiredCount": 1, "minHosts": 0, "maxHosts": 5, "hosts": [ { "id": "68581e8b-66fc-4504-b8b2-00a763360dfb", "name": "aks-nodepool1-14903811-0" }, { "id": "0338e6ec-2da7-4c92-9e47-0fa0601f065e", "name": "aks-nodepool1-14903811-1" } ] }, { "id": "2226c92c-ff0f-4b71-88e6-5c85d079d4d3", "name": "prod-aks-us-east2-hg", "desiredCount": 1, "minHosts": 0, "maxHosts": 5, "hosts": [ { "id": "f3dfab95-949c-4b17-8691-fbe45660b364", "name": "aks-nodepool1-39911597-0" }, { "id": "0a1fd855-e942-4c9d-bdcd-d59c086f12d8", "name": "aks-nodepool1-39911597-1" } ] }, { "id": "b4ff6180-b0e7-4951-a4cb-29572c481061", "name": "aks-demo-hg", "desiredCount": 1, "minHosts": 0, "maxHosts": 5, "hosts": [ { "id": "9560d6e6-18ef-4087-9bf2-7981549d04e2", "name": "aks-nodepool1-15724977-0" }, { "id": "5e7ccd73-a1e2-40b6-b0cc-2085fe8e8934", "name": "aks-nodepool1-15724977-1" } ] } ] }, { "id": "2e0c3c81-09ba-4633-b085-555040efc2dd", "type": "AWS", "name": "Nirmata-AWS", "hostGroups": [ { "id": "30fe5761-4ee6-45e4-b5ea-075cd91ae04b", "name": "aws-demo", "desiredCount": 0, "minHosts": 0, "maxHosts": 5, "hosts": [ { "id": "9cfff737-b6fc-4512-8d4b-4eb3964361ed", "name": "ip-10-10-131-70" }, { "id": "e1b514f1-ff4f-4df5-94f6-b0c1738c843e", "name": "ip-10-10-130-51" }, { "id": "120fa82f-e70c-4d3f-b334-b06a9b655f98", "name": "ip-10-10-130-190" } ] } ] }, { "id": "45950d43-bac0-4ddb-9165-3fe91d3c0bc4", "type": "Azure", "name": "nirmata-azure", "hostGroups": [ { "id": "e3a14d35-5245-4acc-ad11-cfbb8a8a7cf3", "name": "prod-hostgroup", "desiredCount": 3, "minHosts": 0, "maxHosts": 5, "hosts": [ { "id": "b3b26a3b-733d-4506-a6b0-629059ebeed9", "name": "prod-hostgroup-72648" }, { "id": "b1f7c5ac-95ac-48ed-9c7e-67956db8c26b", "name": "prod-hostgroup-35076" } ] }, { "id": "cb674cab-407d-48ef-924c-c83eb0379f00", "name": "jim-prod-az", "desiredCount": 3, "minHosts": 0, "maxHosts": 5, "hosts": [ { "id": "f43145e8-cfb8-4bfc-ae31-69fdba133404", "name": "jim-prod-az-12734" }, { "id": "7095c2af-8a51-4080-95bb-1f2d4ad107eb", "name": "jim-prod-az-99904" }, { "id": "786b153f-8db0-41d7-9d6e-2963ad90f142", "name": "jim-prod-az-11107" } ] } ] }, { "id": "ebad7359-e4b3-4225-a6cc-0ababe1ae230", "type": "vSphere", "name": "vsphere-private-cloud", "hostGroups": [ { "id": "aec50dd9-64c5-4159-a9a5-dbe8ec079188", "name": "vsphere-new-hg", "desiredCount": 5, "minHosts": 0, "maxHosts": 5, "hosts": [ { "id": "45ab49db-a32f-4aa3-93c1-12b10bc48df1", "name": "vsphere-new-hg-44412" }, { "id": "3cc13241-2355-42f0-b912-87cdfd61a315", "name": "vsphere-new-hg-68263" }, { "id": "71aa07a5-9f2e-4432-8bad-30724d0941b7", "name": "vsphere-new-hg-23203" }, { "id": "f55d29f6-9855-4253-9f98-77e86b9eebd7", "name": null }, { "id": "6bdb2cd2-4f8c-42fa-80b7-c36ece8a7cb6", "name": "vsphere-new-hg-54753" }, { "id": "0e848355-1faa-4725-bb7a-4ee5aaceb694", "name": "vsphere-new-hg-47703" } ] } ] }, { "id": "b3c9bd96-48ce-4666-a5ed-46f08e06331a", "type": "Diamanti", "name": "Diamanti", "hostGroups": [ { "id": "08628b4c-703d-487b-adfb-2bb5c010e050", "name": "diamanti-cluster-1-hg", "desiredCount": 1, "minHosts": 0, "maxHosts": 5, "hosts": [ { "id": "c0ea5a98-a810-4082-a472-e153a2f8949b", "name": "se21" }, { "id": "736ec330-fc5c-4ddf-90cb-a4d68507e2aa", "name": "se22" }, { "id": "619e299a-403c-4e28-b2cc-ea4a769c6062", "name": "se23" } ] } ] } ] ### Create a new Kubernetes Cluster Request: POST /api/cluster/hostClusters Accept: application/json Authorization: NIRMATA-API { "name": "", "mode" : "managed", "policySelector" : "", "hostGroupSelector": { "matchLabels": { "name": "" } } } Sample Response Body: { "id" : "47870870-3a08-4a2b-991a-a028be7272f0", "service" : "Cluster", "modelIndex" : "HostCluster", "uri" : "/cluster/api/hostClusters/47870870-3a08-4a2b-991a-a028be7272f0", "parent" : { "id" : "4bf122ed-68d8-4d98-a3de-7ec2a6f766c8", "service" : "Cluster", "modelIndex" : "Root", "uri" : "/cluster/api/roots/4bf122ed-68d8-4d98-a3de-7ec2a6f766c8", "childRelation" : "hostClusters" }, "createdBy" : "jim@nirmata.com", "createdOn" : 1526779036404, "modifiedBy" : "jim@nirmata.com", "modifiedOn" : 1526779036404, "generation" : 0, "ancestors" : [ { "uuid" : "4bf122ed-68d8-4d98-a3de-7ec2a6f766c8", "modelIndex" : "Root", "service" : "Cluster" } ], "labels" : { "nirmata.io/hostcluster.name" : "my-cluster" }, "additionalProperties" : { }, "alarms" : [ ], "name" : "my-cluster", "orchestrator" : "kubernetes", "state" : "pendingCreate", "mode" : null, "status" : [ ], "action" : null, "hostGroups" : [ { "service" : "config", "modelIndex" : "HostGroup", "id" : "30fe5761-4ee6-45e4-b5ea-075cd91ae04b" } ], "environments" : null, "clusterEnvironment" : null, "isDefaultCluster" : null, "connectionState" : "notConnected", "executionState" : null, "hostGroupSelector" : { "matchLabels" : { "name" : "aws-demo" }, "matchExpressions" : [ ] }, "notConnectedSince" : 1526779036405, "policySelector" : null, "description" : null, "adminState" : "enabled", "isAutoscalable" : null, "createDefaultEnvironment" : true, "isInitialized" : false, "lastSyncTime" : null, "volumes" : [ ], "kubernetesCluster" : [ { "id" : "8340a831-b805-4a01-9fc5-d14a673f56a7", "service" : "Cluster", "modelIndex" : "KubernetesCluster", "uri" : "/cluster/api/kubernetes/8340a831-b805-4a01-9fc5-d14a673f56a7" } ], "systemTasks" : [ ] } ### Query a cluster's state Request: GET https://nirmata.io/cluster/api/hostClusters?fields=id,state&query={"name" : "devtest-aks-us-east"} Accept: application/json Authorization: NIRMATA-API Response Headers: HTTP/1.1 200 OK ... Response Body: [ { "id": "49202821-a458-45c8-8799-1a79e012471b", "state": "ready" } ] ### Discover the REST API schema The Nirmata REST API schema can be queried using the HTTP OPTIONS method. Here is a query and JQ filter to obtain all endpoints (model classes): Request: curl -X OPTIONS -H "Accept: application/json" -H "Authorization: NIRMATA-API " https://nirmata.io/config/api | jq ".modelClasses | .[] .modelIndex" Response: "Root" "Application" "EnvironmentType" "ContainerType" "ResourceSelectionPolicy" "ResourceSelectionRule" "CloudProvider" "HostGroup" "Host" "Container" "Service" "Environment" "ServiceInstance" "ServicePort" "ServiceSpec" "Registry" "LaunchConfiguration" "PortRange" "VSphereConfig" "WebHook" "ScalingPolicy" "DesiredService" "ScalingRule" "VCloudConfig" "ServiceInstanceAction" "ServiceAffinityRule" "ServiceScalingRule" "RoutingPolicy" "RoutingRule" "GatewayRoute" "GatewayPolicy" "GatewayRule" "AzureConfig" "DesiredServiceAction" "PrivateCloud" "HealthCheck" "ClusterNode" "Cluster" "UpdatePolicy" "ImageUpdateEvent" "GatewayConfig" "ContainerAction" "DesiredServiceLabelSelector" "LabelSelectorItem" "EnvironmentVariable" "HostAction" "AwsConfig" "HostScalingRule" ### Discover attributes and relations You can query a single class, to get its attributes and relations. Request: curl -X OPTIONS -H "Accept: application/json" -H "Authorization: NIRMATA-API " https://nirmata.io/config/api/ContainerType Response Body: { "name" : "Config", "id" : "d05f7751-8dae-4733-9e14-601d6f3516b3", "rootIndex" : "Root", "modelClasses" : [ { "modelIndex" : "ContainerType", "uri" : "/config/api/containerTypes", "methods" : [ "OPTIONS", "GET", "POST", "DELETE", "PUT" ], "apiLabel" : "containerTypes", "isDeleteable" : true, "keyField" : "name", "parents" : [ "Root" ], "attributes" : [ { "name" : "name", "type" : "String", "isRequired" : true, "uniqueScope" : "PARENT", "isKey" : false, "length" : 0 }, { "name" : "description", "type" : "String", "isRequired" : false, "uniqueScope" : "NONE", "isKey" : false, "length" : 0 }, { "name" : "cpuShares", "type" : "Integer", "isRequired" : false, "uniqueScope" : "NONE", "isKey" : false, "min" : 0, "max" : 1024, "default" : 0 }, { "name" : "memory", "type" : "Integer", "isRequired" : false, "uniqueScope" : "NONE", "isKey" : false, "min" : 0, "max" : 64000, "default" : 0 } ], "relations" : [ { "name" : "resourceSelectionRules", "type" : "Reference", "relationClass" : "ResourceSelectionRule", "cardinality" : { "min" : 0, "type" : "zeroOrMore" }, "isMany" : true, "relationField" : "containerTypes", "isStrongReference" : false, "uri" : "/config/api/containerTypes/{id}/resourceSelectionRules", "methods" : [ "OPTIONS", "GET" ] }, { "name" : "services", "type" : "Reference", "relationClass" : "Service", "cardinality" : { "min" : 0, "type" : "zeroOrMore" }, "isMany" : true, "relationField" : "containerType", "isStrongReference" : false, "uri" : "/config/api/containerTypes/{id}/services", "methods" : [ "OPTIONS", "GET" ] } ] } ] } --- ## API Basics The Nirmata API model is composed of resources. Each resource type is described by a class and is made up of *attributes* and *relations*. Each resource has a *modelIndex* that indicates its class, and a *uri* that describes how it can be queried. At runtime, each resource can contain relations to other resources. The relations can be *parent-child* relations or *reference* relations. The Nirmata API is accessible at: ```bash https://www.nirmata.io/api/ ```text **Note:** trying the API URL in a browser will return an empty page, as the required HTTP headers are not specified. You can use a REST client, like Postman (), to try and learn the API. ## Authentication To authenticate your account, you can use HTTP BASIC authentication or an API Key: Authorization BASIC or: Authorization NIRMATA-API Since the Nirmata API is only accessible via HTTPS, your credentials are sent over an encrypted connection. To manage your API Key, login to Nirmata and navigate to *Settings -> Account -> Generate API Key*. An API key is associated with a User account. When you authenticate an application using the API key, it will get the role and privileges associated with the account. A best practice recommendation is to create separate accounts for each application, and provide the minimum required role and privileges to the account. ## Operations Operation | HTTP Method | URI Syntax | Description ----------|-------------|------------|------------ Create | POST | /{modelIndex} | Creates a new resource. The *modelIndex* is the resource name. | | /{parent}/{id}/{relation} | Create a new resource, as child of the '{parent}/{id}' resource Retrieve | GET | /{modelIndex} | Returns all resources of type specified by 'modelIndex' | | /{modelIndex}/{id} | Returns a single resource Update | PUT | /{modelIndex}/{id} | Updates a resource Delete | DELETE | /{modelIndex}/{id} | Deletes a resource Discover | OPTIONS | / | Returns the class definitions for all resources | | /{modelIndex} | Returns the class definition for a single resource ### HTTP Response Status Codes The following table lists common HTTP response codes used by the API: HTTP Status Code | Description ------------------|----------------- 200 | The operation succeeded 401 | The user authentication failed 403 | The request was not permitted 406 | The request results in an invalid configuration 500 | The request caused a server error ### Resources The following are some of the commonly used endpoints available via the API: - catalog/api/applications - catalog/api/application/{id}/import - catalog/api/application/{id}/export - catalog/api/application/{id}/run - catalog/api/deployments - catalog/api/statefulSets - catalog/api/podTemplateSpecs - catalog/api/podSpecs - catalog/api/volumes - catalog/networkPolicies - catalog/api/services - catalog/api/ingresses - catalog/api/configMaps - catalog/api/secrets - environments/api/environments - environments/api/applications - environments/api/application/{id}/import - environments/api/application/{id}/export - environments/api/deployments - environments/api/statefulSets - environments/api/podTemplateSpecs - environments/api/podSpecs - environments/api/volumes - environments/networkPolicies - environments/api/services - environments/api/ingresses - environments/api/configMaps - environments/api/secrets - environments/api/podSpecs - environments/api/volumes - environments/networkPolicies - environments/api/services - environments/api/ingresses - environments/api/configMaps - cluster/api/hostClusters - cluster/api/nodes - cluster/api/nodes - cluster/api/events - cluster/api/namespaces - cluster/api/storageClasses - cluster/api/persistentVolumes - cluster/api/nodeStats - cluster/api/clusterStats - cluster/api/pendingPods - cluster/api/clusterPolicies - cluster/api/clusterRoles - cluster/api/clusterRoleBindings --- ## HTTP Headers The following HTTP headers are required: Header | Sample | Description ---------------|-------------------------|--------------------------------- Authorization | NIRMATA-API \ | API key based authentication Accept | application/json | Specifies request for JSON data --- ## URL Parameters URL Parameters are used to control the returned JSON data. ## mode The mode parameter is used to control the JSON output format for a GET request. Here are the allowed values: - normal - export - exportDetails In the *normal* mode the JSON data for each object contains all attributes and relations are output as links. In the *export* mode the JSON data contains all attributes and child relation objects are directly embedded into the parent. Reference relations are represented as links, and also contain the unique attributes of the referred to object. The mode parameter can be applied to all GET requests and can be combined with other parameters. The export mode is useful when an entire sub-document needs to be retrieved and stored externally. For example, the following query will export the full {model} as JSON: GET https://www.nirmata.io/catalog/api/applications/{id}?mode=export Accept: application/json The *exportDetails* mode also includes meta-data fields and relations to external entities (outside of the target document). ## query The query parameter is used to control which objects are included in a JSON response. The query data is specified as a JSON object. The query parameter can be applied to any GET request that returns multiple objects. For example the following query returns the application named 'helloworld': GET https://www.nirmata.io/environments/api/applications?query={"name":"helloworld"} Accept: application/json Multiple attributes can be specified for a logical AND operation: GET https://www.nirmata.io/environments/api/applications?query={"name":"helloworld", "run" : "hello1"} Accept: application/json ## fields The fields parameter is used to control which fields, of an resource, should be included in the JSON response. The fields parameter can be applied to any GET request. The fields parameter value is specified as a single field name, or a comma separated list of field names, that should be included in the response. For example, this query returns only the *id* and *name* fields of all Deployments in the catalog: GET https://www.nirmata.io/catalog/api/deployments?fields=id,name,kind,apiVersion Accept: application/json ## excludeFields The excludeFields parameter is used to exclude one or more fields from the response. The excludeFields parameter can be applied to any GET request. The fields parameter value is specified as a single field name, or a comma separated list of field names, that should be excluded from the response. For example, this query excludes the *metadata* field from Deployments: GET https://www.nirmata.io/catalog/api/deployments?excludefields=metadata Accept: application/json ## count The count parameter is used to specify the maximum number of resources to be returned. It can be used when querying a relation, a list of resources, or using a query parameter. A positive value is expected. When not specified, all matching resources are returned. For example the following query returns the podIP and state fields for up to 10 instances of the resource *podStatus*: GET https://www.nirmata.io/environments/api/podStatus?count=10&fields=podIP,state Accept: application/json ## start The start parameter is used to specify the start index in a list of resources. It can be used when querying a relation, a list of resources, or using a query parameter. A positive value is expected. When not specified a value of 0 is assumed. For example the following query returns *podStatus* instances 10-20 (or less) that have attribute state with the *state* of *running*: GET https://www.nirmata.io/environments/api/podStatus?start=10&count=10&query={"state" : "running"}&fields=id Accept: application/json --- ## Common Endpoints All resources implement a few common endpoints for querying related resources: ## descendants Returns all descendants of a model type. The full URL is of the form: /{service}/api/{model}/{id}/descendants/{model} Note that the *descendants* keyword is optional. So the following is an equivalent query to retrieve all direct or sub-descendants: /{service}/api/{model}/{id}/{model} ## ancestors Returns all ancestors (parents and their parents) of a model instance. The full URL is of the form: /{service}/api/{model}/{id}/ancestors ## ancestor Returns an ancestors of a model instance, that matches the provided model type. The full URL is of the form: /{service}/api/{model}/{id}/ancestor/{model} ## currentAlarms Returns all current (active and not-cleared) alarms of a model instance: /{service}/api/{model}/{id}/currentAlarms ## currentAlarmCounts Returns the count of all current (active and not-cleared) alarms of a model instance: /{service}/api/{model}/{id}/currentAlarmCounts --- ## Resource Paths In some cases, identifying a resource requires information from multiple objects. For example Deployments with the same name may exist in different Applications. While an UUID can be used to identify the resource, this is not very easy to use. In these situations, A *Path* can be used to identify a resource contained in a sub-tree. Each path element identifies a unique Resource: "/" - Selects the root resource "/Entity[field=value, field=value]" - Selects a resource named 'Entity' queried by the field-value pairs For example, suppose you have two Applications "Hello-World-1" and "Hello-World-2", and each of these applications has a single Deployment "hello". The following path will select the Deployment "hello" in the Application "Hello-World-1": /applications/[name=Hello-World-1]/deployment[name=hello] Since the Application "Hello-World-1" has a single service in it, the path could also be written as: /application[name=Hello-World-1]/deployment Paths can only be used when referring to a related resource (i.e. a reference relationship) as an alternative to using the UUID for the resource. In this form, a path is written as: { "id": "path:/application[name=Hello-World-1]/deployment" ... } Another way to specify the path, instead of a string with the "path:" prefix, is to use a JSON attribute: { "path": "/application[name=Hello-World-1]/deployment" ... }