Redacting Dataset Samples

A dataset’s sample is up to 1,000 rows that Narrative copies from your data plane into the control plane so you can preview it. When those rows contain personal data, you can store a redaction for the sample: a record of which columns hold personal data, what kind of personal data each column holds, and how each value is masked when the sample is read. Once a redaction is stored, both sample endpoints apply it. GET /datasets/{dataset_id}/sample returns the masked rows by default; pass redacted=false to get the unmasked sample instead. GET /datasets/{dataset_id}/sample/redacted always returns the masked rows and requires a stored redaction. The underlying sample itself is not modified — deleting the redaction leaves the sample untouched, and GET /datasets/{dataset_id}/sample then returns unmasked rows either way.

Writing or deleting a redaction requires an API key with write access on datasets. See API key permissions.

Prerequisites

A dataset with a stored sample. Call POST /datasets/{dataset_id}/request-sample first if one does not exist.
An API key with write access on datasets.

The endpoints

Method	Path	Purpose
`GET`	`/datasets/{dataset_id}/redaction`	Read the stored redaction
`PUT`	`/datasets/{dataset_id}/redaction`	Store or replace the redaction
`DELETE`	`/datasets/{dataset_id}/redaction`	Delete the stored redaction
`GET`	`/datasets/{dataset_id}/sample`	Return the sample; masked by default, unmasked with `redacted=false`
`GET`	`/datasets/{dataset_id}/sample/redacted`	Return the masked sample; `400` when nothing is stored

Upload a redaction

Send PUT /datasets/{dataset_id}/redaction with one entry per column that holds personal data. Each entry names the column’s dot-separated path in the sample, an optional category, and a masking_strategy.

curl -X PUT "https://api.narrative.io/datasets/1234/redaction" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "columns": [
      {
        "path": "email_address",
        "category": "private_email",
        "masking_strategy": { "type": "keep_email_domain" }
      },
      {
        "path": "payment.card_number",
        "category": "account_number",
        "masking_strategy": { "type": "keep_last_digits", "count": 4 }
      },
      {
        "path": "notes",
        "category": null,
        "masking_strategy": { "type": "mask_everything" }
      }
    ]
  }'

A successful PUT returns 200 and replaces whatever was stored before. Uploading also brings back a redaction that was previously deleted. The stored redaction records who wrote it from your access token, so a written_by field in the request body is ignored.

A single redaction may name at most 20,480 columns. A path that does not resolve in a row leaves that row untouched, so a redaction naming a since-renamed column quietly stops masking it.

Masking strategies

Seven strategies are available. Each is a JSON object tagged with type.

Strategy	Behavior	Example (`John Doe` / `[email protected]`)
`keep_email_domain`	Keeps the domain plus the local part’s first and last two characters	`jo****[email protected]`
`keep_initials`	Replaces each whitespace-separated token with its first letter and three mask characters	`J* D*`
`keep_network_prefix`	Keeps an IPv4 address’s `/24` and masks the rest. IPv6 is masked completely	`192.168.1.***`
`keep_two_decimal_places`	Rounds a coordinate to two decimal places	`40.71`
`keep_year`	Returns the first four-digit run and drops the rest	`1985-03-12` → `1985`
`keep_last_digits`	Keeps the last `count` digits (1 to 4), masks other letters and digits, and leaves separators alone	`4111-1111-1111-1234` with `count: 4` → `**--**-1234`
`mask_everything`	Keeps nothing	`************`

keep_last_digits requires a count between 1 and 4:

{ "type": "keep_last_digits", "count": 4 }

A value the strategy can’t parse (an email with no @, a non-IPv4 address, a non-coordinate, a value with no four-digit run) is masked completely.

Personal data categories

category classifies what kind of personal data the column holds. It does not affect masking — only masking_strategy does. Nine values are accepted:

account_number
other
private_address
private_date
private_email
private_person
private_phone
private_url
secret

category is optional. Send null or leave the key out for a column you don’t want to classify.

Read the redacted sample

Two endpoints return the masked rows. GET /datasets/{dataset_id}/sample applies the stored redaction by default, masking every named column and leaving every other column untouched. Pass redacted=false to get the unmasked sample; a dataset with no stored redaction returns the unmasked sample either way.

curl -X GET "https://api.narrative.io/datasets/1234/sample?size=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /datasets/{dataset_id}/sample/redacted always returns the masked sample and requires both a stored sample and a stored redaction.

curl -X GET "https://api.narrative.io/datasets/1234/sample/redacted?size=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "records": [
    {
      "email_address": "ja****[email protected]",
      "full_name": "J*** D***",
      "payment": { "card_number": "****-****-****-4321" },
      "city": "Calgary"
    }
  ]
}

Masking a number or a boolean returns the text it renders as, so a masked numeric column comes back as a JSON string. Redacted rows do not match the dataset’s declared schema for those columns.

GET /sample/redacted returns 400 when no sample or no redaction is stored for the dataset. GET /sample returns 400 when no sample is stored, whatever the redacted value. Use POST /v2/datasets/{dataset_id}/request-sample to sample the dataset and have Narrative’s privacy model write a redaction in a single call.

View the sample in the app

Wherever a dataset’s sample is shown in the app — its own sample section, the mapping editor, and query results — the rows arrive masked by the stored redaction, the same default GET /datasets/{dataset_id}/sample applies. Turn on Show unredacted values below the table to reload the sample unmasked. The switch starts off each time the sample is opened, and a dataset with no stored redaction shows the same rows either way. Update sample in a dataset’s Actions menu, and Request new sample on an empty sample card, both take the POST /v2/datasets/{dataset_id}/request-sample path: they sample the dataset and have the privacy model write the redaction for that sample in one run.

Requesting a new sample from the app replaces the stored redaction with one the privacy model writes. If you maintain a redaction of your own, upload it again with PUT /datasets/{dataset_id}/redaction afterwards, or refresh the sample with POST /datasets/{dataset_id}/request-sample, which leaves the stored redaction alone.

Delete a redaction

DELETE /datasets/{dataset_id}/redaction clears the stored redaction. GET /datasets/{dataset_id}/redaction then reports it as missing, and GET /datasets/{dataset_id}/sample/redacted stops returning rows until a new redaction is stored. Deleting when there is no redaction succeeds and does nothing. The underlying sample is not affected.

Errors

PUT /datasets/{dataset_id}/redaction returns 400 when a request body is malformed. error_description points at the offending column by its position in columns:

DecodingFailure at .columns[0].masking_strategy: unexpected type 'keep_emial_domain'. expected one of keep_email_domain, keep_initials, keep_last_digits, keep_network_prefix, keep_two_decimal_places, keep_year, mask_everything

DecodingFailure at .columns[0].category: unexpected category 'national_id'. expected one of account_number, other, private_address, private_date, private_email, private_person, private_phone, private_url, secret

DecodingFailure at .columns[0].masking_strategy.count: 999 digits must be at most 4

Any read path that consults the stored redaction (GET /redaction, GET /sample with its default, and GET /sample/redacted) returns 500 if the stored redaction cannot be decoded. This happens, for example, when the stored masking_strategy is one this API no longer recognises. The body is an RFC 7807 problem document with title: "Stored Redaction Unreadable". Quote the log_id when reporting the failure to support.

Sample Data

How samples move from data planes to the control plane

Hashing PII for Upload

Prepare identifiers before uploading them

Overview

Platform

Data Ingestion

Data Planes

Querying with NQL

Data Collaboration

Identity Resolution

Data Activation

Audience Studio

Connectors

Connector APIs

Compliance

Rosetta Stone

Account Settings

Workflows

Webhooks

Data Collaboration MCP Server

Tools

SDKs

Prerequisites

The endpoints

Upload a redaction

Masking strategies

Personal data categories

Read the redacted sample

View the sample in the app

Delete a redaction

Errors

Sample Data

Hashing PII for Upload

​Prerequisites

​The endpoints

​Upload a redaction

​Masking strategies

​Personal data categories

​Read the redacted sample

​View the sample in the app

​Delete a redaction

​Errors

​Related content

Sample Data

Hashing PII for Upload

Prerequisites

The endpoints

Upload a redaction

Masking strategies

Personal data categories

Read the redacted sample

View the sample in the app

Delete a redaction

Errors

Related content