> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mogenius.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Mogenius API

The mogenius REST API allows you to manage your mogenius workspaces and resources in scripts, automations, and third party tools.

## Creating an API key

To authenticate with the mogenius API, first create an API key. You can do this on cluster level, or workspace level. Go to the section **API key** in the respective settings and add a new key by filling out the form:

* Set a name to identify the API key later.
* Define the expiration date.
* Set the scope based on the [pre-defined groups](./members-and-roles.md).

## Set Image

You can use the API to perform a `set image`  for your deployments via the mogenius operator.

```
curl --location 'https://platform-api.mogenius.com/workspace/workload/set-image' \
--header 'Authorization: bearer YOUR_WORKSPACE_API_KEY' \
--data '{
    "kind": "Deployment",
    "namespace": "YOUR_NAMESPACE",
    "resourceName": "DEPLOYMENT_NAME",
    "containerName": "CONTAINER_NAME",
    "image": "CONTAINER_IMAGE"
}'
```

## Helm Upgrade

You can use the API to perform a `Helm upgrade` on a Helm release via the mogenius operator. For this to work, the Helm repository must be installed on the cluster first. The variable `REPO_NAME` in the request below refers to this Helm repository.

The Helm upgrade can be performed with an API key on workspace level, or cluster level.

<CodeGroup>
  ```Workspace Workspace theme={null}
  curl --location --request PATCH 'https://platform-api.mogenius.com/workspace/helm/release/upgrade' \
  --header 'Authorization: bearer YOUR_WORKSPACE_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
      "namespace": "YOUR_NAMESPACE",
      "chart": "CHART_NAME", // REPO_NAME/CHART_NAME
      "release": "RELEASE_NAME",
      "version": "UPGRADE_TO_VERSION",
      "values": {
          "key1":"value1" // can also be a yaml string
      },
      "dryRun": false
  }'
  ```

  ```Cluster Cluster theme={null}
  curl --location --request PATCH 'https://platform-api.mogenius.com/helm/admin/YOUR_CLUSTER_ID/release/upgrade' \
  --header 'Authorization: bearer YOUR_CLUSTER_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
      "namespace": "YOUR_NAMESPACE",
      "chart": "CHART_NAME", // REPO_NAME/CHART_NAME
      "release": "RELEASE_NAME",
      "version": "UPGRADE_TO_VERSION",
      "values": {
          "key1":"value1" // can also be a yaml string
      },
      "dryRun": false
  }'
  ```
</CodeGroup>

## Deploy a Blueprint

[Blueprints](/deploying-applications/blueprints) are pre-configured Helm charts. Deploying one via the API is a two-step flow:

1. Read the blueprint to get its chart coordinates and default values.
2. Install that chart with the Helm install endpoint.

The target cluster is selected with the `cluster-id` header. Use a cluster-level API key (or a workspace-level key with editor permissions); installing requires editor/admin rights on the cluster.

### 1. List blueprints

```
// HEADER
Authorization: Bearer YOUR_CLUSTER_API_KEY
cluster-id: YOUR_CLUSTER_ID

GET https://platform-api.mogenius.com/helm/blueprints
```

Returns the catalog with each blueprint's `id`, `displayName`, `description`, `category`, and `tags`.

### 2. Get a blueprint's details

```
// HEADER
Authorization: Bearer YOUR_CLUSTER_API_KEY
cluster-id: YOUR_CLUSTER_ID

GET https://platform-api.mogenius.com/helm/blueprints/BLUEPRINT_ID
```

The response includes the blueprint's Helm `repository` and `chart` (name and version) plus its default install target (`namespace`, `release`) and default `values`. Use these to build the install request.

### 3. Install the chart

Install the blueprint's chart as a standard Helm release. For repository-based charts, the Helm repository must be added to the cluster first (the `chart` value has the form `REPO_NAME/CHART_NAME`).

```
// HEADER
Authorization: Bearer YOUR_CLUSTER_API_KEY
cluster-id: YOUR_CLUSTER_ID
Content-Type: application/json

POST https://platform-api.mogenius.com/helm/chart/install
```

```curl expandable theme={null}
// BODY
{
    "namespace": "YOUR_NAMESPACE",
    "chart": "REPO_NAME/CHART_NAME",  // from the blueprint's chart
    "release": "RELEASE_NAME",
    "version": "CHART_VERSION",
    "values": "key1: value1",          // YAML string with your value overrides
    "dryRun": false
}
```

For charts hosted in an OCI registry, use the OCI install endpoint instead:

```
// HEADER
Authorization: Bearer YOUR_CLUSTER_API_KEY
cluster-id: YOUR_CLUSTER_ID
Content-Type: application/json

POST https://platform-api.mogenius.com/helm/chart/oci/install
```

```curl expandable theme={null}
// BODY
{
    "ociChartUrl": "oci://REGISTRY/CHART",
    "namespace": "YOUR_NAMESPACE",
    "release": "RELEASE_NAME",
    "version": "CHART_VERSION",   // optional
    "values": "key1: value1",      // optional YAML string
    "dryRun": false
}
```

Once installed, the blueprint becomes a standard Helm release that you can manage through the [Helm upgrade](#helm-upgrade) endpoint or the [Helm Charts](/deploying-applications/helm-charts) interface.

## Manage Ports & Hostnames

You can `get`, `add`, and `delete` ports and hostnames from deployments, just like from the UI. mogenius will automatically create or update the corresponding service and ingress resources.

Here's example requests with configuration options on each parameter. Make sure to remove the comments when copying the example.

### GET Ports & Domains

Returns a JSON with all Service and Ingress configurations related to a Controller.

```
// HEADER
Authorization: Bearer [your token]

GET https://platform-api.mogenius.com/resource/workload/ports-domains?kind=Deployment&plural=deployments&apiVersion=apps/v1&namespaced=true&resourceName=my-container&namespace=my-namespace
```

### PATCH Ports & Domains

Adds or deletes Service and Ingress configurations.

```
// HEADER
Authorization: Bearer [your token]

PATCH https://platform-api.mogenius.com/resource/workload/ports-domains
```

```curl expandable theme={null}
// BODY
{
    "kind": "Deployment",
    "plural": "deployments",
    "apiVersion": "apps/v1",
    "namespaced": true,
    "resourceName": "my-deployment", // deployment name
    "namespace": "my-namespace",
    
    "service": { // service
        // "resourceName": "test-service", // optional
        "ports": [
            {
                "action": "add", // optional -> add or delete
                "protocol": "TCP", // TCP/UDP
                "targetPort": 8080,
                "port": 8080,
                "ingress": { // ingress
                    // "resourceName": "test-ingress", // optional
                    "domains": [ 
                        {
                            "action": "add", // optional -> add or delete
                            "tls": true, // true or false
                            "domain": "yourdomain.com",
                            "tlsSecret": "" // optional, specify secret name if a custom TLS secret should be used
                        }
                    ]
                }
            }
        ]
    }
}
```