Skip to main content
PUT
/
datasets
/
{dataset_id}
/
retention-policy
Upsert retention policies for a dataset
curl --request PUT \
  --url https://api-dev.narrative.io/datasets/{dataset_id}/retention-policy \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "expire_everything"
}
'
import requests

url = "https://api-dev.narrative.io/datasets/{dataset_id}/retention-policy"

payload = { "type": "expire_everything" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)
const options = {
method: 'PUT',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({type: 'expire_everything'})
};

fetch('https://api-dev.narrative.io/datasets/{dataset_id}/retention-policy', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
CURLOPT_URL => "https://api-dev.narrative.io/datasets/{dataset_id}/retention-policy",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'type' => 'expire_everything'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
package main

import (
"fmt"
"strings"
"net/http"
"io"
)

func main() {

url := "https://api-dev.narrative.io/datasets/{dataset_id}/retention-policy"

payload := strings.NewReader("{\n \"type\": \"expire_everything\"\n}")

req, _ := http.NewRequest("PUT", url, payload)

req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := io.ReadAll(res.Body)

fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.put("https://api-dev.narrative.io/datasets/{dataset_id}/retention-policy")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"type\": \"expire_everything\"\n}")
.asString();
require 'uri'
require 'net/http'

url = URI("https://api-dev.narrative.io/datasets/{dataset_id}/retention-policy")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"type\": \"expire_everything\"\n}"

response = http.request(request)
puts response.read_body
{
  "id": 18923,
  "company_id": 382,
  "created_at": "2021-06-24T00:54:40.029056Z",
  "description": "Mobile identifiers tied to birth information provided as part of app registration.",
  "name": "declared_age",
  "display_name": "Declared Age",
  "schema": {
    "file_config": {
      "type": "flat",
      "delimiter": ",",
      "escape": "\"",
      "header": true,
      "quote": "\""
    },
    "type": "object",
    "properties": {
      "idValue": {
        "display_name": "id value",
        "order": 0,
        "approximate_cardinality": 100000,
        "description": "ID values",
        "type": "string"
      },
      "idType": {
        "display_name": "id type",
        "order": 1,
        "approximate_cardinality": 1,
        "type": "string",
        "enum": [
          "md5_email",
          "sha256_email"
        ]
      },
      "eventTimestamp": {
        "display_name": "event timestamp",
        "order": 2,
        "description": "When the observation was collected",
        "type": "timestamptz",
        "validations": [
          "eventTimestamp < current_timestamp()"
        ]
      },
      "countryCode": {
        "display_name": "country code",
        "order": 3,
        "approximate_cardinality": 6,
        "description": "The country of residence of the individual",
        "type": "string"
      },
      "age": {
        "display_name": "age",
        "order": 4,
        "approximate_cardinality": 90,
        "description": "How old this individual is in years",
        "type": "long"
      },
      "birthInfo": {
        "display_name": "birth info",
        "order": 5,
        "description": "The year this individual was born",
        "type": "double"
      }
    },
    "required": [
      "idValue",
      "idType",
      "eventTimestamp",
      "countryCode",
      "age"
    ],
    "primary": "/age"
  },
  "status": "active",
  "tags": [
    "age",
    "demo",
    "demographic",
    "demographics"
  ],
  "updated_at": "2021-06-24T00:54:40.029056Z",
  "write_mode": "append",
  "subscription_id": "123e4567-e89b-12d3-a456-426614174000",
  "last_snapshot_created_at": "2023-06-09T16:51:34.215Z",
  "stats": {
    "est_total_dataset_stored_files": 10,
    "est_total_dataset_stored_records": 500059,
    "est_total_dataset_stored_bytes": 4206454,
    "active_dataset_stored_files": 10,
    "active_dataset_stored_records": 500059,
    "active_dataset_stored_bytes": 4206454,
    "last_snapshot_added_files": 2,
    "last_snapshot_added_records": 499999,
    "last_snapshot_deleted_records": 0,
    "last_snapshot_added_bytes": 4193500,
    "last_snapshot_deleted_files": 0,
    "last_snapshot_added_delete_files": 0,
    "last_snapshot_removed_delete_files": 0,
    "last_snapshot_removed_bytes": 0
  }
}

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

dataset_id
integer
required

Unique identifier for a dataset.

Body

application/json

Backwards-compatible legacy payloads. Interpreted as snapshot-level retention on Iceberg. Returned response will be unified v1 shape with compat.mode=legacy.

type
enum<string>
Available options:
expire_everything

Response

200 - application/json

OK

id
integer
required

Unique identifier for the dataset.

company_id
integer
required

The ID of the company owning the dataset.

created_at
string
required

ISO-8601 timestamp indicating when the dataset was created

name
string
required

The Dataset's name. Should be unique, contain only alpanum chars and underscores. Max length is 256.

display_name
string
required

The Dataset's name to display at UI.

retention_policy
object
required

Backwards-compatible legacy payloads. Interpreted as snapshot-level retention on Iceberg. Returned response will be unified v1 shape with compat.mode=legacy.

Example:
{ "type": "expire_everything" }
schema
object
required

Schema describing a dataset's input file type and the kind of data the file contains. Note: when the file type is "flat" then the order of the properties describing the must be given in the order they appear in the input file.

status
enum<string>
required

The dataset status.

  • active means that data can be added to the dataset but the schema is locked in place
  • pending means the dataset has been created, but the schema can still be altered and no data can be added to the dataset
Available options:
active,
pending
tags
string[]
required

Tags that describe the dataset.

write_mode
enum<string>
required

How Narrative will treat new data uploaded for the dataset.

  • append means data will be added to the dataset, this is what to choose if you incrementally update your dataset over time.
  • overwrite means that all existing data will be overwritten with new data.
Available options:
append,
overwrite
updated_at
string
required

ISO-8601 timestamp indicating when the dataset was last updated.

compute_pool_config
object

Compute pool configuration for the dataset.

description
string

A description of the data contained with the dataset.

subscription_id
string

Id of a subscription which writes output to the dataset

last_snapshot_created_at
string

ISO-8601 timestamp indicating when the last snapshot was created.

stats
object