---
schema_version: "1"
id: 269c010f0ff0d4dc4597d8ca7159e69ab41d4e3ccb51db445403349ca2ab4c8e
title: Managed Runtime API
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/using-the-managed-runtime-api.md
canonical_url: https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/using-the-managed-runtime-api.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: df6168204e6540dee37aea194af4871eda9d9f7caf72f25469b298e14b64911e
products:
  - Composable Storefront
  - Salesforce APIs
---
# Managed Runtime API

Use the Managed Runtime API to control applications deployed to B2C Commerce’s Managed Runtime. You can create custom tooling that has the same functionality as the [Runtime Admin](https://runtime.commercecloud.com/) web application, but you get even more administration abilities and configuration options.

**note:** Instead of Managed Runtime API, use the B2C Commerce API (SCAPI) endpoints to manage storefront environments and deployments. SCAPI authorization is based on Account Manager and is suitable for automating storefront tasks by using a bot user. See [Automate Storefront Administration with APIs](https://developer.salesforce.com/docs/commerce/sfnext/guides/sfnext-mrt-api.md).

## Considerations

**warning:** **The Managed Runtime API is for administration purposes only.** Do _not_ make requests to the API in your storefront code. Requests that exceed [rate limits](#rate-limits) are blocked.

- To read [environment variables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/environment-variables.md) from the storefront, use [`process.env`](https://nodejs.org/api/process.html#processenv).
- To read and load [redirects](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.md#redirects) use the managed endpoint `/mobify/redirects/$path`.

## Before You Begin

This guide assumes that you're already familiar with Managed Runtime and related concepts, such as: projects, environments, bundles, and deployments. To learn more, see the [Managed Runtime Overview](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/mrt-overview.md).

**note:** The Mobify brand name still appears in the `mobify.com` domain in the base URL for the Managed Runtime API. Although new Salesforce domains will eventually take the place of the Mobify domain, support for the Mobify domain will continue.

To make API requests, you must include an API key in the HTTP request `Authorization` header with the value, `Bearer $API_KEY`.

To find your API key, log in to the [Runtime Admin](https://runtime.commercecloud.com/) tool and go to the [Account Settings](https://runtime.commercecloud.com/account/settings) page.

**note:** Treat your API key like a password because it allows scripts to perform operations on your behalf.

## Tutorial

We’re about to show you how to use the API with a brief tutorial based on some sample requests, which are formatted as `curl` commands.

Before running the commands, replace any placeholders with actual values. Placeholders are formatted like this: `$PLACEHOLDER`.

For most requests, you must replace `$PROJECT_ID` with your actual project ID. To look up your project ID, log in to the [Runtime Admin](https://runtime.commercecloud.com/) tool and go to your project’s settings page.

Project IDs can be up to 20 characters long and must be unique globally.

### List Environments

Our first request to the Managed Runtime API lists all the environments (or "targets" as they're called in the API) that belong to a project:

Call the [projects_target_list](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_list) API endpoint to list the environments:

Use the [B2C CLI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md):

```bash
export MRT_API_KEY="$API_KEY"

npx @salesforce/b2c-cli mrt env list --project "$PROJECT_ID"
```

Alternatively, use the API:

```bash
curl "https://cloud.mobify.com/api/projects/$PROJECT_ID/target/" \
  --header "Authorization: Bearer $API_KEY"
```

### Create an Environment

Now let’s create an environment called `staging` that we can use to verify changes before deploying them to `production`:

First call the [projects_target_create](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_create) API endpoint. If you’re creating a project, you can call the [projects_create](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_create) API endpoint to also create an environment:

Use the [B2C CLI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md):

```bash
npx @salesforce/b2c-cli mrt env create staging --project "$PROJECT_ID"
```

Alternatively, use the API:

```bash
curl "https://cloud.mobify.com/api/projects/$PROJECT_ID/target/" \
  --request 'POST' \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"name": "staging"}'
```

Then call the [cc_b2c_target_info_update](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-b2c-config?meta=cc_b2c_target_info_update) API endpoint to connect a B2C Commerce instance and one or more sites to the environment.

Use the [B2C CLI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md):

```bash
npx @salesforce/b2c-cli mrt env b2c \
  --project "$PROJECT_ID" --environment staging \
  --instance-id aaaa_stg --sites DemoSite1,DemoSite2
```

Alternatively, use the API:

```bash
curl "https://cloud.mobify.com/api/cc/b2c/projects/$PROJECT_ID/b2c-target-info/staging/" \
  --request 'PUT' \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"instance_id": "aaaa_stg", "sites": ["DemoSite1", "DemoSite2"]}'
```

_To use your new environment, you must [*deploy a bundle*](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pushing-and-deploying-bundles.html) to it._

Let’s call the [projects_target_retrieve](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_retrieve) API endpoint to review the details of the `staging` environment that we created:

```bash
curl "https://cloud.mobify.com/api/projects/$PROJECT_ID/target/staging/" \
  --header "Authorization: Bearer $API_KEY"
```

### Modify Proxy Configuration

Finally, let’s call the [projects_target_partial_update](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_partial_update) API endpoint to modify the proxy configuration for `staging`:

```bash
curl "https://cloud.mobify.com/api/projects/$PROJECT_ID/target/staging/" \
  --request 'PATCH'  \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"ssr_proxy_configs": [{"path": "api", "host": "kv7kzm78.api.commercecloud.salesforce.com"}]}'
```

_Changing the configuration redeploys the deployed bundle so that the configuration update takes effect._

## Troubleshooting

If you’re having trouble using the API, try these troubleshooting steps.

- Add the `--fail` argument to your `curl` command.
- Check your API key.
- Check your project’s ID.

The API endpoints also work in a browser. Log in to the [Runtime Admin](https://runtime.commercecloud.com/) tool then open the endpoint you’re using directly in your browser.

## Automation Users 🤖

To support continuous integration and deployment using the Managed Runtime API, create an Account Manager user for automation:

- Create a user account in Account Manager using a shared email address like a Google Group. _Store the associated credentials and MFA code in a password manager like LastPass._
- Give the user the `Managed Runtime User` role.
- Assign the user the required permissions in Runtime Admin. _The user's Managed Runtime API key can only access what is allowed by the user's permissions. Keep them specific to the projects that CI/CD needs to interact with._
- Create the API key for the user and save it in your continuous integration system.

To keep the Managed Runtime API key active, you must keep the related Account Manager account active by updating its password as required by your organization's Account Manager configuration. If the user is deactivated, reactivate it by resetting the password to re-enable the API key.

## Rate Limits

The Managed Runtime API has rate limits in place for the number of requests allowed per unit of time. Rate limits are applied on a per-user basis, and help ensure fair access for all users.

If your request exceeds a rate limit, the API returns an HTTP `429 Too Many Requests` error, and a `Retry-After` HTTP header that indicates the number of seconds to wait until you can retry.

Rate limits cannot be adjusted.

### How to Read the Numbers

The tables below indicate the rate limits for different API families.

**important:** Some endpoints have cumulative rate limits, which means they are not throttled on a per-endpoint basis. Instead, cumulative rate limits throttle the combined number of requests across multiple endpoints. All GET requests have a cumulative rate limit. Similarly, all POST, PATCH, and DELETE requests for endpoints that are not individually called out in the following tables have a cumulative rate limit. These limits are described [below](#default-rate-limits).

### Projects and Environments

| Method | Endpoint                           |
| ------ | ---------------------------------- |
| POST   | `/api/projects/`                   |
| PATCH  | `/api/projects/*/`                 |
| DELETE | `/api/projects/*/`                 |
| POST   | `/api/projects/*/builds/*/`        |
| POST   | `/api/projects/*/target/`          |
| PATCH  | `/api/projects/*/target/*/`        |
| DELETE | `/api/projects/*/target/*/`        |
| POST   | `/api/projects/*/target/*/deploy/` |

| Cumulative 1 Minute Limit | Cumulative 1 Hour Limit |
| ------------------------- | ----------------------- |
| 10                        | 100                     |

### Cache Invalidations

| Method | Endpoint                                 | 5 Minute Limit | 1 Hour Limit |
| ------ | ---------------------------------------- | -------------- | ------------ |
| POST   | `/api/projects/*/target/*/invalidation/` | 15             | 100          |

### Default Rate Limits

| Method              | Endpoint                          | 1 Minute Limit | 1 Hour Limit |
| ------------------- | --------------------------------- | -------------- | ------------ |
| GET                 | All endpoints combined.           | 1000           | N/A          |
| POST, PATCH, DELETE | All remaining endpoints combined. | 100            | N/A          |

## Read-Only Mode During Maintenance

During planned maintenance windows, the Managed Runtime API rejects write requests (POST, PUT, PATCH, DELETE) with an HTTP `503 Service Unavailable` response and error code `service_read_only`. Read requests (GET) continue to work normally. Retry write requests after the maintenance window concludes.

## Next Steps

Now you’re familiar with what the API can do—and even made some sample requests!

To learn more about the API, refer to the [API Specification](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-b2c-config?meta=Summary).

The Open API schemas for the API are available at:

- **MRT Admin:** https://cloud.mobify.com/api/schema.json
- **MRT B2C Config:** https://cloud.mobify.com/api/cc/b2c/schema.json