---
title: Replace element
url: https://www.tines.com/docs/api/resources/replace-element/
updated: 2026-03-17T20:45:07+00:00
description: Replace a top level element from an array or key from an object in a resource. The request returns the updated resource. If the resource has a test value this can be modified by using the is_test parameter.
---

*[tines.com](https://www.tines.com/llms.txt) › [Docs](https://www.tines.com/llms.txt) › [Tines API](https://www.tines.com/llms.txt) › [Resources](https://www.tines.com/llm/docs/api/resources.md)*

# Replace element

*[View on tines.com](https://www.tines.com/docs/api/resources/replace-element/)*

## Description

Replace a top level element from an array or key from an object in a resource. The request returns the updated resource. If the resource has a test value this can be modified by using the is_test parameter.

## Request

HTTP Method: **POST**

| Parameter   | Description                                                                                                                                                                                                                                                                                                                                                                                                               |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| resource_id | The ID of the live resource.                                                                                                                                                                                                                                                                                                                                                                                              |
| key         | The object key to replace if replacing from an object.                                                                                                                                                                                                                                                                                                                                                                    |
| index       | The index of the element to replace if replacing from an array (with indexes starting at 0).                                                                                                                                                                                                                                                                                                                              |
| value       | The new value to replace the existing element with                                                                                                                                                                                                                                                                                                                                                                        |
| if_value    | **Optional** When provided, the operation only proceeds if the current value at the specified key (for objects) or index (for arrays) matches this value. If the value does not match, a 422 error is returned with the current value included in the response. Supports any JSON value (string, number, boolean, object, array). A `null` value is treated the same as omitting the parameter (unconditional operation). |
| is_test     | **Optional** Boolean value stating if the test resource should be used                                                                                                                                                                                                                                                                                                                                                    |

### Sample request

Sample request for an array element

```bash
curl -X POST \
  https://<tenant-domain>/api/v1/global_resources/<<resource_id>>/replace \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <<CREDENTIAL.tines_api_key>>' \
  -d '{
        "index": "0",
        "value": "new-value"
    }'
```

Sample request for an object key

```bash
curl -X POST \
  https://<tenant-domain>/api/v1/global_resources/<<resource_id>>/replace \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <<CREDENTIAL.tines_api_key>>' \
  -d '{
        "key": "foo",
        "value": "new-value"
    }'
```

Sample request for conditional replacement (compare-and-swap)

```bash
curl -X POST \
  https://<tenant-domain>/api/v1/global_resources/<<resource_id>>/replace \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <<CREDENTIAL.tines_api_key>>' \
  -d '{
        "key": "count",
        "value": 6,
        "if_value": 5
    }'
```

## Examples

### Replacing an element in an array

Given a resource with value:

```json
["alice", "bob", "charlie"]
```

Sending `{ "index": "1", "value": "eve" }` updates the resource to:

```json
["alice", "eve", "charlie"]
```

### Replacing a key in an object

Given a resource with value:

```json
{ "city": "Cork", "country": "Ireland" }
```

Sending `{ "key": "city", "value": "Galway" }` updates the resource to:

```json
{ "city": "Galway", "country": "Ireland" }
```

### Conditional replacement (compare-and-swap)

Given a resource with value:

```json
{ "count": 5 }
```

Sending `{ "key": "count", "value": 6, "if_value": 5 }` updates the resource to:

```json
{ "count": 6 }
```

If `count` were any other value, the request would return a 422 error with the current value and the resource would remain unchanged.

## Response

A successful request will return the updated resource value.

### Sample response

```json
{ "city": "Galway", "country": "Ireland" }
```