--- title: "API Basics" 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/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 --- ## 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**> **Profile**>**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 Code Status 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 ### Endpoints The following are some of the commonly used endpoints available via the API: - activity/api/Query - 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 - 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 - 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 ### Usage Details For the activity API, use the `POST` method and specify the `Query` spec in the payload. Example, ```json { "index": "audit_trail*", "timeframe": "Custom", "eventType": "User", "numRecords": 10, "page": 1, "start": 1722495600000, "end": 1722841199000, "filter": { "modelIndex": [ "Alarm", "AlarmNotifier", "AlarmType", "ClusterAddOnAction", "ClusterComplianceReport", "ComplianceControl", "ComplianceStandard", "KyvernoConfig", "KyvernoPolicy", "KyvernoPolicySpec", "OidcIdpSettings", "OperatorEvent", "PolicyException", "PolicyExceptionRequest", "PolicyGroup", "PolicyGroupCluster", "PolicyKustomization", "PolicyReportNotification", "PolicyReportSchedule" ], "label": [ "^Pod: kyverno.*$", "^Service: kyverno.*$", "^Deployment: kyverno.*$", "^Application: kyverno.*$" ] } } ``` * `index` must be `audit_trail*`. * `timeframe` is a `required` field. The acceptable values are `LastFiveMinutes`, `LastFifteenMinutes`, `LastHour`, `LastDay`, `LastWeek`, `LastMonth`, or `Custom`. * `start` is required when `Custom` is specified for `timeframe`. * `end` is required when `Custom` is specified for `timeframe`. * `eventType` can accept values to be `System`, `User`, `All`. The default value is `All`. * `page / numRecords` can be used for pagination.