Skip to main content
PUT
/
datasets
/
{dataset_id}
Update a dataset
curl --request PUT \
  --url https://api-dev.narrative.io/datasets/{dataset_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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": {
        "approximate_cardinality": 100000,
        "description": "ID values",
        "type": "string"
      },
      "idType": {
        "approximate_cardinality": 1,
        "type": "string",
        "enum": [
          "md5_email",
          "sha256_email"
        ]
      },
      "eventTimestamp": {
        "description": "When the observation was collected",
        "type": "timestamptz",
        "validations": [
          "eventTimestamp < current_timestamp()"
        ]
      },
      "countryCode": {
        "approximate_cardinality": 6,
        "description": "The country of residence of the individual",
        "type": "string"
      },
      "age": {
        "approximate_cardinality": 90,
        "description": "How old this individual is in years",
        "type": "long"
      },
      "birthInfo": {
        "description": "The year this individual was born",
        "type": "double"
      }
    },
    "required": [
      "idValue",
      "idType",
      "eventTimestamp",
      "countryCode",
      "age"
    ],
    "primary": "/age"
  },
  "tags": [
    "age",
    "demo",
    "demographic",
    "demographics"
  ]
}
'
import requests

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

payload = {
    "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": {
                "approximate_cardinality": 100000,
                "description": "ID values",
                "type": "string"
            },
            "idType": {
                "approximate_cardinality": 1,
                "type": "string",
                "enum": ["md5_email", "sha256_email"]
            },
            "eventTimestamp": {
                "description": "When the observation was collected",
                "type": "timestamptz",
                "validations": ["eventTimestamp < current_timestamp()"]
            },
            "countryCode": {
                "approximate_cardinality": 6,
                "description": "The country of residence of the individual",
                "type": "string"
            },
            "age": {
                "approximate_cardinality": 90,
                "description": "How old this individual is in years",
                "type": "long"
            },
            "birthInfo": {
                "description": "The year this individual was born",
                "type": "double"
            }
        },
        "required": ["idValue", "idType", "eventTimestamp", "countryCode", "age"],
        "primary": "/age"
    },
    "tags": ["age", "demo", "demographic", "demographics"]
}
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({
    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: {approximate_cardinality: 100000, description: 'ID values', type: 'string'},
        idType: {
          approximate_cardinality: 1,
          type: 'string',
          enum: ['md5_email', 'sha256_email']
        },
        eventTimestamp: {
          description: 'When the observation was collected',
          type: 'timestamptz',
          validations: ['eventTimestamp < current_timestamp()']
        },
        countryCode: {
          approximate_cardinality: 6,
          description: 'The country of residence of the individual',
          type: 'string'
        },
        age: {
          approximate_cardinality: 90,
          description: 'How old this individual is in years',
          type: 'long'
        },
        birthInfo: {description: 'The year this individual was born', type: 'double'}
      },
      required: ['idValue', 'idType', 'eventTimestamp', 'countryCode', 'age'],
      primary: '/age'
    },
    tags: ['age', 'demo', 'demographic', 'demographics']
  })
};

fetch('https://api-dev.narrative.io/datasets/{dataset_id}', 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}",
  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([
    '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' => [
                                'approximate_cardinality' => 100000,
                                'description' => 'ID values',
                                'type' => 'string'
                ],
                'idType' => [
                                'approximate_cardinality' => 1,
                                'type' => 'string',
                                'enum' => [
                                                                'md5_email',
                                                                'sha256_email'
                                ]
                ],
                'eventTimestamp' => [
                                'description' => 'When the observation was collected',
                                'type' => 'timestamptz',
                                'validations' => [
                                                                'eventTimestamp < current_timestamp()'
                                ]
                ],
                'countryCode' => [
                                'approximate_cardinality' => 6,
                                'description' => 'The country of residence of the individual',
                                'type' => 'string'
                ],
                'age' => [
                                'approximate_cardinality' => 90,
                                'description' => 'How old this individual is in years',
                                'type' => 'long'
                ],
                'birthInfo' => [
                                'description' => 'The year this individual was born',
                                'type' => 'double'
                ]
        ],
        'required' => [
                'idValue',
                'idType',
                'eventTimestamp',
                'countryCode',
                'age'
        ],
        'primary' => '/age'
    ],
    'tags' => [
        'age',
        'demo',
        'demographic',
        'demographics'
    ]
  ]),
  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}"

	payload := strings.NewReader("{\n  \"description\": \"Mobile identifiers tied to birth information provided as part of app registration.\",\n  \"name\": \"declared_age\",\n  \"display_name\": \"Declared Age\",\n  \"schema\": {\n    \"file_config\": {\n      \"type\": \"flat\",\n      \"delimiter\": \",\",\n      \"escape\": \"\\\"\",\n      \"header\": true,\n      \"quote\": \"\\\"\"\n    },\n    \"type\": \"object\",\n    \"properties\": {\n      \"idValue\": {\n        \"approximate_cardinality\": 100000,\n        \"description\": \"ID values\",\n        \"type\": \"string\"\n      },\n      \"idType\": {\n        \"approximate_cardinality\": 1,\n        \"type\": \"string\",\n        \"enum\": [\n          \"md5_email\",\n          \"sha256_email\"\n        ]\n      },\n      \"eventTimestamp\": {\n        \"description\": \"When the observation was collected\",\n        \"type\": \"timestamptz\",\n        \"validations\": [\n          \"eventTimestamp < current_timestamp()\"\n        ]\n      },\n      \"countryCode\": {\n        \"approximate_cardinality\": 6,\n        \"description\": \"The country of residence of the individual\",\n        \"type\": \"string\"\n      },\n      \"age\": {\n        \"approximate_cardinality\": 90,\n        \"description\": \"How old this individual is in years\",\n        \"type\": \"long\"\n      },\n      \"birthInfo\": {\n        \"description\": \"The year this individual was born\",\n        \"type\": \"double\"\n      }\n    },\n    \"required\": [\n      \"idValue\",\n      \"idType\",\n      \"eventTimestamp\",\n      \"countryCode\",\n      \"age\"\n    ],\n    \"primary\": \"/age\"\n  },\n  \"tags\": [\n    \"age\",\n    \"demo\",\n    \"demographic\",\n    \"demographics\"\n  ]\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}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"description\": \"Mobile identifiers tied to birth information provided as part of app registration.\",\n  \"name\": \"declared_age\",\n  \"display_name\": \"Declared Age\",\n  \"schema\": {\n    \"file_config\": {\n      \"type\": \"flat\",\n      \"delimiter\": \",\",\n      \"escape\": \"\\\"\",\n      \"header\": true,\n      \"quote\": \"\\\"\"\n    },\n    \"type\": \"object\",\n    \"properties\": {\n      \"idValue\": {\n        \"approximate_cardinality\": 100000,\n        \"description\": \"ID values\",\n        \"type\": \"string\"\n      },\n      \"idType\": {\n        \"approximate_cardinality\": 1,\n        \"type\": \"string\",\n        \"enum\": [\n          \"md5_email\",\n          \"sha256_email\"\n        ]\n      },\n      \"eventTimestamp\": {\n        \"description\": \"When the observation was collected\",\n        \"type\": \"timestamptz\",\n        \"validations\": [\n          \"eventTimestamp < current_timestamp()\"\n        ]\n      },\n      \"countryCode\": {\n        \"approximate_cardinality\": 6,\n        \"description\": \"The country of residence of the individual\",\n        \"type\": \"string\"\n      },\n      \"age\": {\n        \"approximate_cardinality\": 90,\n        \"description\": \"How old this individual is in years\",\n        \"type\": \"long\"\n      },\n      \"birthInfo\": {\n        \"description\": \"The year this individual was born\",\n        \"type\": \"double\"\n      }\n    },\n    \"required\": [\n      \"idValue\",\n      \"idType\",\n      \"eventTimestamp\",\n      \"countryCode\",\n      \"age\"\n    ],\n    \"primary\": \"/age\"\n  },\n  \"tags\": [\n    \"age\",\n    \"demo\",\n    \"demographic\",\n    \"demographics\"\n  ]\n}")
  .asString();
require 'uri'
require 'net/http'

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

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  \"description\": \"Mobile identifiers tied to birth information provided as part of app registration.\",\n  \"name\": \"declared_age\",\n  \"display_name\": \"Declared Age\",\n  \"schema\": {\n    \"file_config\": {\n      \"type\": \"flat\",\n      \"delimiter\": \",\",\n      \"escape\": \"\\\"\",\n      \"header\": true,\n      \"quote\": \"\\\"\"\n    },\n    \"type\": \"object\",\n    \"properties\": {\n      \"idValue\": {\n        \"approximate_cardinality\": 100000,\n        \"description\": \"ID values\",\n        \"type\": \"string\"\n      },\n      \"idType\": {\n        \"approximate_cardinality\": 1,\n        \"type\": \"string\",\n        \"enum\": [\n          \"md5_email\",\n          \"sha256_email\"\n        ]\n      },\n      \"eventTimestamp\": {\n        \"description\": \"When the observation was collected\",\n        \"type\": \"timestamptz\",\n        \"validations\": [\n          \"eventTimestamp < current_timestamp()\"\n        ]\n      },\n      \"countryCode\": {\n        \"approximate_cardinality\": 6,\n        \"description\": \"The country of residence of the individual\",\n        \"type\": \"string\"\n      },\n      \"age\": {\n        \"approximate_cardinality\": 90,\n        \"description\": \"How old this individual is in years\",\n        \"type\": \"long\"\n      },\n      \"birthInfo\": {\n        \"description\": \"The year this individual was born\",\n        \"type\": \"double\"\n      }\n    },\n    \"required\": [\n      \"idValue\",\n      \"idType\",\n      \"eventTimestamp\",\n      \"countryCode\",\n      \"age\"\n    ],\n    \"primary\": \"/age\"\n  },\n  \"tags\": [\n    \"age\",\n    \"demo\",\n    \"demographic\",\n    \"demographics\"\n  ]\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
  }
}
{
  "error": "Unauthorized",
  "error_description": "You are not authorized to use this endpoint."
}

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
​
name
string

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

​
display_name
string

The Dataset's name to display at UI.

​
description
string

A description of the data contained with the dataset.

​
schema
object

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.

​
tags
string[]

Tags that describe the dataset.

​
write_mode
enum<string>

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

Response

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