# Replace reference

URL: https://docs.hanzo.ai/docs/openapi/reference/risksetreference

> Writes your organisation's own allow and deny entries over a set.

`PUT /v1/reference/{set}`

> [Reference →](https://docs.hanzo.ai/docs/openapi/reference) · [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides)

|               |                                           |
| ------------- | ----------------------------------------- |
| **Address**   | `https://api.hanzo.ai/v1/reference/{set}` |
| **Method**    | `PUT`                                     |
| **Operation** | `riskSetReference`                        |
| **Auth**      | `Authorization: Bearer $HANZO_API_KEY`    |

Writes your organisation's own allow and deny entries over a set.

Idempotent on the key: writing the same entry twice is one entry, and writing
it again replaces the verdict and the note. The whole batch is one
transaction, so a batch that would cross the per-set bound writes nothing
rather than half of itself — a half-applied deny list is worse than a refused
one, because nobody can tell which half applied.

Your entries are held in your organisation's own store and are never visible
to another organisation, and they never change what any other organisation
sees. The shared baseline is not writable from here at all.

## Request

5 fields, body `application/json` (required).

| Field               | In   | Type                             | Required | Description                                                                        |
| ------------------- | ---- | -------------------------------- | -------- | ---------------------------------------------------------------------------------- |
| `set`               | path | string                           | yes      |                                                                                    |
| `entries`           | body | reference.ReferenceOverrideIn\[] | —        | Entries are the overrides to write, up to 1000 per call.                           |
| `entries[].key`     | body | string                           | —        | Key is the member: a domain, a CIDR or address, an issuer prefix, a device digest. |
| `entries[].note`    | body | string                           | —        | Note is why, in your own words.                                                    |
| `entries[].verdict` | body | string                           | —        | Verdict is allow or deny, and nothing else.                                        |

## Response

| Status    | Body                      | Meaning |
| --------- | ------------------------- | ------- |
| `200`     | reference.SetReferenceOut | ok      |
| `default` | problem-details           | refused |

`200` body — 3 fields.

| Field       | In   | Type            | Always | Description                                           |
| ----------- | ---- | --------------- | ------ | ----------------------------------------------------- |
| `overrides` | body | integer (int64) | —      | Overrides is how many your org now holds in this set. |
| `set`       | body | string          | —      | Set is the set written in.                            |
| `written`   | body | integer (int64) | —      | Written is how many entries this call wrote.          |

Failure carries the platform error shape — see [Errors](https://docs.hanzo.ai/docs/errors).

## Examples

**CLI**

```bash
hanzo reference set <set>
```

**SDK**

**.ts**

```ts
import { Configuration, ReferenceApi } from 'hanzoai';

const api = new ReferenceApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.riskSetReference({ set: 'set', entries: [{"key":"<key>","note":"<note>","verdict":"<verdict>"}] });
```

**.py**

```python
from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import ReferenceApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = ReferenceApi(client).risk_set_reference(set='set', entries=[{"key":"<key>","note":"<note>","verdict":"<verdict>"}])
```

**.go**

```go
cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.ReferenceAPI.RiskSetReference(context.Background()).Execute()
if err != nil {
	return err
}
```

**.rs**

```rust
use hanzo_client::apis::{configuration::Configuration, reference_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = reference_api::risk_set_reference(&cfg, Default::default()).await?;
```

**.java**

```java
import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.ReferenceApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new ReferenceApi(client).riskSetReference();
```

**HTTP**

```bash
curl -X PUT https://api.hanzo.ai/v1/reference/<set> \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "entries": [
         {
           "key": "<key>",
           "note": "<note>",
           "verdict": "<verdict>"
         }
       ]
     }'
```

**MCP**

Tool `reference`, op `riskSetReference` — POST the JSON-RPC envelope to `https://api.hanzo.ai/v1/mcp`.

```bash
curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "reference",
         "arguments": {
           "op": "riskSetReference",
           "input": {
             "set": "<set>",
             "entries": [
               {
                 "key": "<key>",
                 "note": "<note>",
                 "verdict": "<verdict>"
               }
             ]
           }
         }
       }
     }'
```

---

[Reference API](https://docs.hanzo.ai/docs/openapi/reference) · [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)