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

# Resource metadata

> Store arbitrary key-value pairs on resources using the metadata field.

Some resources support a `metadata` field that allows you to store arbitrary key-value pairs. This is useful for attaching your own identifiers, references, or any other information that is meaningful to your integration.

## Format

Metadata is a flat JSON object where both keys and values must be strings.

```json theme={null}
{
  "metadata": {
    "external_id": "abc_123",
    "source": "zapier",
    "correlation.id": "req-001"
  }
}
```

## Constraints

| Constraint             | Limit                                                                                             |
| ---------------------- | ------------------------------------------------------------------------------------------------- |
| Maximum number of keys | 20                                                                                                |
| Key format             | Lowercase alphanumeric characters, dots (`.`), underscores (`_`), colons (`:`), and hyphens (`-`) |
| Maximum key length     | 40 characters                                                                                     |
| Maximum value length   | 500 characters                                                                                    |
| Value type             | String only                                                                                       |

## Update semantics

Metadata updates use **merge-patch** semantics ([RFC 7386](https://datatracker.ietf.org/doc/html/rfc7386)). When updating metadata, only the keys you include in the request are affected. Existing keys that are not included remain unchanged.

* **Add or update a key**: include the key with a string value
* **Remove a key**: include the key with a `null` value
* **Clear all metadata**: send an empty object `{}`
* **Leave metadata unchanged**: omit the `metadata` field from the request

```bash title="Create with metadata" theme={null}
curl -X POST "https://public-api.stora.co/2025-09/webhook_endpoints" \
 -H 'content-type: application/json' \
 -H 'authorization: Bearer ACCESS_TOKEN' \
 -d '{"name": "My Webhook", "url": "https://example.com/webhook", "api_version": "2025-09", "event_types": ["contact.created"], "metadata": {"source": "zapier", "external_id": "abc_123"}}'
```

```bash title="Update: change one key, remove another" theme={null}
curl -X PATCH "https://public-api.stora.co/2025-09/webhook_endpoints/we_..." \
 -H 'content-type: application/json' \
 -H 'authorization: Bearer ACCESS_TOKEN' \
 -d '{"metadata": {"source": "make", "external_id": null}}'
```

After the update, the metadata will be `{"source": "make"}` — the `source` key was updated and `external_id` was removed.