---
schema_version: "1"
id: b63e2d6877ee3dccc5d769d2ecdaa58e12197e9a3cde556bb87c1bd293716a92
title: Object Store v2 REST APIs
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/object-store/osv2-apis.md
canonical_url: https://docs.mulesoft.com/object-store/osv2-apis
source_site: docs.mulesoft.com
content_type: documentation
content_hash: de8644a0ad02184fd2f57dfc91117592bff5f627633e80086392bc5aaf69e9b4
description: MuleSoft Documentation Site
latest: true
---
---
product: Object Store
---

# Object Store v2 REST APIs

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

> [!NOTE] Where possible, we changed noninclusive terms to align with our company value of Equality.
> We maintained certain terms to avoid any effect on customer implementations.

The Object Store v2 APIs enable you to use REST to:

- Retrieve a list of object stores and keys associated with an application.

- Store and retrieve key-value pairs in an object store.

- Delete key-value pairs from an object store.

Object Store provides these APIs:

- [Object Store v2 API](#osv2-api)

## Before You Begin

- Create an app that uses Object Store v2 and
  [deploy it to CloudHub](https://docs.mulesoft.com/cloudhub/deploying-to-cloudhub).

- [Store a key-value pair in the object store](https://docs.mulesoft.com/object-store/osv2-guide#send-data-to-an-object-store).

- [Get the bearer token](#get-bearer-token) for an Anypoint Platform user using the Access
  Management API:

  You need the bearer token to access all Object Store v2 APIs.

- [Get the ORG\_ID and ENV\_ID](#get-org-env-id).

  You need the organization ID and environment ID for operations with all Object Store v2 APIs.

- [Get the REGION\_ID](#get-region-id).

  You need the region ID for operations with the Object Store v2 API.

- [Get the STORE\_ID](#get-store-id).

  You need the store ID for operations with the Object Store v2 API.

## Get a Bearer Token to Use with the Object Store v2 APIs

If MFA (multi-factor authentication) is enabled

Use a connected app to get the bearer token:

1.  [Configure a connected app](https://docs.mulesoft.com/object-store/osv2-connected-apps).

    Assign the connected app the Organization Administrator scope to access the organization and
    environment queries.

2.  From the **Connected Apps** page, click **Copy Id** and **Copy Secret** for the app you just
    created.

    Use this client ID and client secret to get the bearer token required to authenticate with the
    Object Store v2 API.

3.  Run this command to get the bearer token from the connected app client ID and client secret:

    ```bash
    curl --location '<AUTH_SERVER_HOST>/accounts/api/v2/oauth2/token' \
       --header 'Content-Type: application/json' \
        --data '{
          "client_id": "<CLIENT_ID>",
          "client_secret": "<CLIENT_SECRET>",
          "grant_type": "client_credentials"
          }'
    ```

    Replace AUTH\_SERVER\_HOST with the URL of the authorization server, for example
    `https://anypoint.mulesoft.com/`.

    The output includes the bearer token:

    ```json
    {
      "access_token": "<BEARER_TOKEN>",
      "token_type": "bearer"
    }
    ```

4.  Use this bearer token to access any Object Store v2 API that requires a bearer token.

If MFA isn’t enabled

Authenticate with the credentials of a user with the Organization Administrator permission:

1.  Run this command to get the bearer token:

    ```bash
    curl -H \
      "Content-Type: application/json" \
      -X POST -d '{"username":"<USERNAME>","password":"<PASSWORD>"}' \
      "<AUTH_SERVER_HOST>accounts/login"
    ```

    Replace AUTH\_SERVER\_HOST with the URL of the authorization server, for example
    `https://anypoint.mulesoft.com/`.

    Make sure the user has the Organization Administrator permission to access the organization and
    environment queries.

    The output includes the bearer token:

    ```json
    {
      "access_token": "<BEARER_TOKEN>",
      "expires_in": 3600,
      "token_type": "bearer"
    }
    ```

2.  Use this bearer token to access any Object Store v2 API that requires a bearer token.

### Get the Organization ID and Environment ID

To get the ORG\_ID, run this command, replacing AUTH\_SERVER\_HOST with the authorization server:

```bash
curl -X GET https://<AUTH_SERVER_HOST>/accounts/api/me \
  -H "Authorization: Bearer <BEARER_TOKEN>"
```

The response includes output similar to:

```json
"organization": {
    "name": "MyCompany",
    "id": "ORG_ID",
  },
```

To get the ENV\_ID, run this command, replacing AUTH\_SERVER\_HOST with the authorization server:

```bash
curl -X GET https://<AUTH_SERVER_HOST>/accounts/api/organizations/<ORG_ID>/environments \
  -H "Authorization: Bearer <BEARER_TOKEN>"
```

The response includes output similar to:

```json
"environments": [
  {
    "id": "ENV_ID",
    "name": "Production",
    "organizationId": "ORG_ID",
  },
]
```

### Get the Region ID

To get the region ID (REGION\_ID), run this command, replacing [BASE\_URL](#access-osv2-api):

```bash
curl -X GET \
 'https://<BASE_URL>/api/v1/organizations/<ORG_ID>/regions' \
 -H 'authorization: Bearer <BEARER_TOKEN>'
```

See [Example: Retrieve a List of Regions](#example-retrieve-region).

### Get the Store ID

To get the store ID (STORE\_ID), run this command, replacing [BASE\_URL](#access-osv2-api):

```bash
curl -X GET \
 'https://<BASE_URL>/api/v1/organizations/<ORG_ID>/environments/<ENV_ID>/stores' \
 -H 'authorization: bearer <BEARER_TOKEN>'
```

See [Example: Retrieve a List of Object Stores](#example-retrieve-list).

## Object Store v2 API

The Object Store v2 API reads and writes `key,list` values, which is different from Anypoint
Connector for Object Store (Object Store Connector), which reads and writes in the `key,value`
format.

This table compares the Object Store REST API operations to Object Store Connector operations:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Object Store v2 API</th><th>Object Store v2 REST API Operations</th><th>Object Store Connector Operation</th></tr></thead><tbody><tr><td><div><div><p>POST</p></div></div></td><td><div><div><ul><li><p>Object Store</p><div><ul><li><p>Object store TTL, in seconds</p><div><p>The maximum TTL is 2592000 seconds (30 days).</p></div><div><p>If the <code>entryTtl</code> value specified is greater than 30 days, the value defaults to 2592000 seconds (30 days), without returning an error.</p></div></li><li><p>Persistence property</p></li><li><p>Usage limits for each application or environment, including options for limits based on keys or size, and how to enforce them</p></li></ul></div></li><li><p>Key and list (item) value</p></li></ul></div></div></td><td><div><div><p>Store</p></div></div></td></tr><tr><td><div><div><p>GET</p></div></div></td><td><div><div><ul><li><p>Get keys</p></li><li><p>Get item</p></li><li><p>Get items</p></li><li><p>Get all items</p></li><li><p>Get regions for an organization</p></li></ul></div></div></td><td><div><div><p>Contains + Retrieve + Retrieve all keys + Retrieve and store (Retrieve part)</p></div></div></td></tr><tr><td><div><div><p>PUT</p></div></div></td><td><div><div><ul><li><p>Put item as string</p></li><li><p>Put item as number</p></li><li><p>Put item as confirmable string</p></li><li><p>Put store</p></li></ul></div></div></td><td><div><div><p>Store</p></div></div></td></tr><tr><td><div><div><p>DELETE</p></div></div></td><td><div><div><ul><li><p>Remove object store</p></li><li><p>Delete key</p></li><li><p>Delete item</p></li></ul></div></div></td><td><div><div><p>Remove</p></div></div></td></tr></tbody></table>

You can retrieve a maximum of 25 keys with each GET operation.

### Access the Object Store v2 API

1.  [Get a Bearer Token to Use with the Object Store v2 APIs](#get-bearer-token).

2.  Set up an application, such as Postman, to access the object store.

3.  Configure the object store access URL, replacing ORG\_ID with your organization ID and ENV\_ID
    with your environment ID:

    ```bash
    <BASE_URL>/api/v1/organizations/<ORG_ID>/environments/<ENV_ID>/stores/myTestStoreId/objects
    ```

    Depending on the deployment region, use one of these domains for the value of BASE\_URL in the
    access URL:

    <table><colgroup><col> <col> <col></colgroup><thead><tr><th>Control Plane</th><th>BASE_URL</th><th>Region</th></tr></thead><tbody><tr><td rowspan="12"><p>U.S.</p></td><td><div><div><p><code>object-store-us-east-1.anypoint.mulesoft.com</code></p></div></div></td><td><div><div><p>US East (N. Virginia)</p></div></div></td></tr><tr><td><p><code>object-store-us-east-2.anypoint.mulesoft.com</code></p></td><td><div><div><p>US East (Ohio)</p></div></div></td></tr><tr><td><p><code>object-store-us-west-1.anypoint.mulesoft.com</code></p></td><td><div><div><p>US West (N. California)</p></div></div></td></tr><tr><td><p><code>object-store-us-west-2.anypoint.mulesoft.com</code></p></td><td><div><div><p>US West (Oregon)</p></div></div></td></tr><tr><td><p><code>object-store-ap-southeast-1.anypoint.mulesoft.com</code></p></td><td><div><div><p>Asia Pacific (Singapore)</p></div></div></td></tr><tr><td><p><code>object-store-ap-southeast-2.anypoint.mulesoft.com</code></p></td><td><div><div><p>Asia Pacific (Sydney)</p></div></div></td></tr><tr><td><p><code>object-store-ap-northeast-1.anypoint.mulesoft.com</code></p></td><td><div><div><p>Asia Pacific (Tokyo)</p></div></div></td></tr><tr><td><p><code>object-store-ca-central-1.anypoint.mulesoft.com</code></p></td><td><div><div><p>Canada (Central)</p></div></div></td></tr><tr><td><p><code>object-store-eu-central-1.anypoint.mulesoft.com</code></p></td><td><div><div><p>Europe (Frankfurt)</p></div></div></td></tr><tr><td><p><code>object-store-eu-west-1.anypoint.mulesoft.com</code></p></td><td><div><div><p>Europe (Ireland)</p></div></div></td></tr><tr><td><p><code>object-store-eu-west-2.anypoint.mulesoft.com</code></p></td><td><div><div><p>UK (London)</p></div></div></td></tr><tr><td><p><code>object-store-sa-east-1.anypoint.mulesoft.com</code></p></td><td><div><div><p>South America (São Paulo)</p></div></div></td></tr><tr><td><p>U.S.</p><p>MuleSoft Government Cloud</p></td><td><div><div><p><code>object-store-us-gov-west-1.gov.anypoint.mulesoft.com</code></p></div></div></td><td><div><div><p>US Gov West</p></div></div></td></tr><tr><td rowspan="2"><p>EU</p></td><td><div><div><p><code>object-store-eu-central-1.eu1.anypoint.mulesoft.com</code></p></div></div></td><td><div><div><p>Europe (Frankfurt)</p></div></div></td></tr><tr><td><p><code>object-store-eu-west-1.eu1.anypoint.mulesoft.com</code></p></td><td><div><div><p>Europe (Ireland)</p></div></div></td></tr><tr><td><p>Canada Cloud</p></td><td><div><div><p><code>object-store-ca-central-1.ca1.platform.mulesoft.com</code></p></div></div></td><td><div><div><p>Canada (Central)</p></div></div></td></tr><tr><td rowspan="2"><p>Japan Cloud</p></td><td><div><div><p><code>object-store-ap-northeast-1.jp1.platform.mulesoft.com</code></p></div></div></td><td><div><div><p>Asia Pacific (Tokyo)</p></div></div></td></tr></tbody></table>

4.  Configure the application with HTTP headers and body for values to store to or read from the
    object store.

5.  Send the operation to the Object Store v2 API.

### Examples: Object Store v2 API

- [Example: Retrieve a List of Object Stores](#example-retrieve-list)

- [Example: Retrieve a List of Regions](#example-retrieve-region)

- [Example: Retrieve a List of Partitions](#example-retrieve-partitions)

- [Example: Retrieve a List of Keys in a Partition](#example-retrieve-keys)

- [Example: Retrieve the Value of a Key](#example-retrieve-key-value)

- [Example: Store a Key-Value Pair](#example-store-key-value)

- [Example: Update a Key-Value Pair](#example-update-key-value)

- [Example: Delete a Key and Value](#example-delete-key-value)

#### Example: Retrieve a List of Object Stores

To view the list of object stores, run a `curl` command, replacing BASE\_URL with the regional
domain, ORG\_ID with your organization ID, ENV\_ID with your environment ID, and BEARER\_TOKEN with
your bearer token:

```bash
curl -X GET \
 'https://<BASE_URL>/api/v1/organizations/<ORG_ID>/environments/<ENV_ID>/stores' \
 -H 'authorization: bearer <BEARER_TOKEN>'
```

This command returns output similar to:

```json
  {"values":[{"storeId":"APP_os-simple-flow__defaultPersistentObjectStore","encrypted":true,"permanentOsFlag":false,
    "persistent":true,"defaultTtlSeconds":2592000,"defaultConfirmationTtlSeconds":600,"isFixedTtl":null},
  {"storeId":"APP_scheduler-tests__defaultPersistentObjectStore","encrypted":true,"permanentOsFlag":false,
    "persistent":true,"defaultTtlSeconds":2592000,"defaultConfirmationTtlSeconds":600,"isFixedTtl":null}
  {"storeId":"APP_sending-a-csv-file-thru-email-using-smtp__defaultPersistentObjectStore","encrypted":true,"permanentOsFlag":false,
    "persistent":true,"defaultTtlSeconds":2592000,"defaultConfirmationTtlSeconds":600,"isFixedTtl":null}],"nextPageToken":null}
```

#### Example: Retrieve a List of Regions

To view the list of regions, submit a `curl` command, replacing BASE\_URL with the regional domain,
ORG\_ID with your organization ID, and BEARER\_TOKEN with your bearer token:

```bash
curl -X GET \
 'https://<BASE_URL>/api/v1/organizations/<ORG_ID>/regions' \
 -H 'authorization: Bearer <BEARER_TOKEN>'
```

This command returns output similar to:

```json
[
  {
    "id": "us-east-1",
    "name": "US East (N. Virginia)",
    "url": "http://object-store.us-east-1.anypoint.mulesoft.com"
  },
  {
    "id": "us-west-1",
    "name": "US West (N. California)",
    "url": "http://object-store.us-west-1.anypoint.mulesoft.com"
  }
]
```

#### Example: Retrieve a List of Partitions

To view the list of partitions, submit a `curl` command, replacing BASE\_URL with the regional
domain, ORG\_ID with your organization ID, ENV\_ID with your environment ID, and STORE\_ID with the
`storeId` from the list of object stores, and BEARER\_TOKEN with your bearer token:

```bash
curl -X GET \
  https://<BASE_URL>/api/v1/organizations/<ORG_ID>/environments/<ENV_ID>/stores/<STORE_ID>/partitions \
  -H "Authorization: Bearer <BEARER_TOKEN>"
```

This command returns output similar to:

```json
{ "values": ["PARTITION_ID"], "nextPageToken": null }
```

#### Example: Retrieve a List of Keys in a Partition

To view the keys in a partition, submit a `curl` command, replacing BASE\_URL with the regional
domain, ORG\_ID with your organization ID, ENV\_ID with your environment ID, STORE\_ID with the name
of the object store, PARTITION\_ID with the name of the partition, and BEARER\_TOKEN with your
bearer token:

```bash
curl -X GET \
  https://<BASE_URL>/api/v1/organizations/<ORG_ID>/environments/<ENV_ID>/stores/<STORE_ID>/partitions/<PARTITION_ID>/keys \
  -H "Authorization: Bearer <BEARER_TOKEN>"
```

This command returns output similar to:

```json
{ "values": [{ "keyId": "KeyTwo" }, { "keyId": "KeyOne" }], "nextPageToken": null }
```

#### Example: Retrieve the Value of a Key

To view the value of a key, submit a `curl` command, replacing BASE\_URL with the regional domain,
ORG\_ID with your organization ID, ENV\_ID with your environment ID, STORE\_ID with the name of the
object store, PARTITION\_ID with the name of the partition, KEY\_ID with the key ID, and
BEARER\_TOKEN with your bearer token:

```bash
curl -X GET \
  https://<BASE_URL>/api/v1/organizations/<ORG_ID>/environments/<ENV_ID>/stores/<STORE_ID>/partitions/<PARTITION_ID>/keys/<KEY_ID> \
  -H "Authorization: Bearer <BEARER_TOKEN>"
```

This command returns output similar to:

```json
{
  "binaryValue": "++Kn0AIBAQBbwoABDiJLZXkgMiBWYWx1ZSL8rNmhAQEBAWphdmEuaW8uU2VyaWFsaXphYmzlgGFwcGxpY2F0aW9uL2pzb247IGNoYXJzZXQ9VVRGLbgAAAAAAAAADQ==",
  "keyId": "KeyTwo",
  "valueType": "BINARY"
}
```

#### Example: Store a Key-Value Pair

To store a key-value pair, submit a `curl` command, replacing BASE\_URL with the regional domain,
ORG\_ID with your organization ID, ENV\_ID with your environment ID, STORE\_ID with the name of the
object store, PARTITION\_ID with the name of the partition, BEARER\_TOKEN with your bearer token,
and specify a value (`myTestKey`) for KEY\_ID:

```bash
KEY_ID=myTestKey; \
curl -X POST \
  https://<BASE_URL>/api/v1/organizations/<ORG_ID>/environments/<ENV_ID>/stores/<STORE_ID>/partitions/<PARTITION_ID>/keys/myTestKey \
  -H "Authorization: Bearer <BEARER_TOKEN>" \
  -H "Content-Type: application/json" \
  --data '{"stringValue":"Hello World","keyId":"myTestKey","valueType":"STRING"}'
```

In this command, the value is a JSON string.

To verify that the key-pair is in the object store, get a list of the keys in the partition:

```bash
curl -X GET \
  https://<BASE_URL>/api/v1/organizations/<ORG_ID>/environments/<ENV_ID>/stores/<STORE_ID>/partitions/<PARTITION_ID>/keys \
  -H "Authorization: Bearer <BEARER_TOKEN>"
```

This command returns output similar to:

```json
{
  "values": [{ "keyId": "KeyTwo" }, { "keyId": "KeyOne" }, { "keyId": "myTestKey" }],
  "nextPageToken": null
}
```

#### Example: Update a Key-Value Pair

To update the value of an existing key or create a new one, use a `PUT` request. Replace the
placeholders with your specific values:

```bash
curl -X PUT \
  'https://<BASE_URL>/api/v1/organizations/<ORG_ID>/environments/<ENV_ID>/stores/<STORE_ID>/partitions/<PARTITION_ID>/keys/<KEY_ID>' \
  -H 'authorization: bearer <BEARER_TOKEN>' \
  -H 'content-type: application/json' \
  -d '{
        "stringValue": "Updated value",
        "valueType": "STRING",
        "metadata": {
          "source": "api"
        }
      }'
```

This command returns output similar to:

```json
{
  "stringValue": "Updated value",
  "valueType": "STRING",
  "metadata": {
    "source": "api"
  }
}
```

#### Example: Delete a Key and Value

To delete a key-value pair, submit a `curl` command, replacing BASE\_URL with the regional domain,
ORG\_ID with your organization ID, ENV\_ID with your environment ID, STORE\_ID with the name of the
object store, PARTITION\_ID with the name of the partition, KEY\_ID with the key ID, and
BEARER\_TOKEN with your bearer token:

```bash
curl -X DELETE \
  https://<BASE_URL>/api/v1/organizations/<ORG_ID>/environments/<ENV_ID>/stores/<STORE_ID>/partitions/<PARTITION_ID>/keys/KEY_ID \
  -H "Authorization: Bearer <BEARER_TOKEN>"
```

In this command, the value is a JSON string.

To verify that the key-pair is no longer in the object store, get a list of the keys in the
partition:

```bash
curl -X GET \
  https://<BASE_URL>/api/v1/organizations/<ORG_ID>/environments/<ENV_ID>/stores/<STORE_ID>/partitions/<PARTITION_ID>/keys \
  -H "Authorization: Bearer <BEARER_TOKEN>"
```

This command returns output similar to:

```json
{ "values": [{ "keyId": "KeyTwo" }, { "keyId": "KeyOne" }], "nextPageToken": null }
```

## Download Object Store APIs from Exchange

To download the Object Store APIs from Exchange:

1.  Go to Exchange and click **Download**.

2.  Select the format to download:

    - RAML

    - OAS

    - Mule 4 connector file

![Download button for the Object Store v2 API in Exchange](/mulesoft/current/en-us/object-store/_images/os-exchange-download.png)

## See Also

- [Rolling TTL](https://docs.mulesoft.com/object-store/#rolling-ttl)

- [Object Store v2 API](https://dev-portal.mulesoft.com/apis/object-store-v2.html)

- [Access Management API](https://dev-portal.mulesoft.com/apis/access-management.html)

- [Object Store Connector for Mule 4](https://docs.mulesoft.com/object-store-connector/latest/)