API docs by Redocly

Narrative Data Collaboration Platform API (2.4.x)

Download OpenAPI specification:Download

Narrative Support: [email protected] URL: https://www.narrative.io

The Narrative Data Collaboration Platform API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

The current version is a pre-release beta. It may result in unexpected behavior and there may be breaking changes in future releases up to the 1.0 release.

Access Rules

Access rules let data providers control who can purchase their data and the terms of purchase.

The access-rules API allows you to manage access rules for your datasets.

Related guides:

Get access rules

Return all access rules belonging to the authenticated company.

Authorizations:
BearerAuth
query Parameters
dataset_id
integer

Dataset identifier.

Responses

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Create an access rule

Create an access rule.

If a dataset has multiple access rules then access rules are tested against a dataset row in price descending order, i.e. the most expensive rule which matches a dataset row determines which the price the buyer will pay for the row.

Authorizations:
BearerAuth
Request Body schema: application/json
query
string

An NQL SELECT query enumerating columns from a single dataset that will be effected by the access rule

dataset_id
integer

(deprecated) only present for legacy reasons and might be removed in the future. Use 'query' instead.

object (AccessRuleCompanyConstraint)

A constraint describing which companies the access rule should or should not apply to.

constraints
Array of strings (AccessRuleConstraints)

A set of boolean SQL expressions used to determine whether the access rule should be applied to a row from the dataset.

If more than one constraint is specified then all the constraints must evaluate to true for the access rule to be applied.

If constraints is not specified or empty then all rows will match the access rule.

E.g. for a dataset with the following type definition:

{
  "type": "object",
  "properties": {
    "idValue": {
      "type": "string"
    },
    "idType": {
      "type": "string",
      "enum": [
        "idfa",
        "adid"
      ]
    },
    "timestamp": {
      "type": "timestamptz"
    }
  },
  "required": [
    "idValue"
  ]
}

Valid constraints include:

  • Is the ID type IDFA?
idType = 'idfa'
  • Is the ID type non-null?
idType is not null
  • Was the row collected within the last 90 days?
timestamp > date_sub(current_date(), 90)
description
string (AccessRuleDescription)

A human-friendly description of the access rule.

pricing
required
integer (AccessRulePricing)

How much to charge for a row which matches this access rule.

Prices are specified in microcents USD to allow for very granular pricing control.

Some useful conversions:

  • 1 cent = 1000000 microcents
  • 1 dollar = 100000000 microcents

If you wanted to price your data at $1 USD per 1000 rows, then you'd set pricing to 100000.

image
string (AccessRuleImage)

Optional. Image url must be < 1000 characters, start from https://, ends with one of: jpg, apng, jpeg, jfif, pjpeg, webp, pjp, svg, avif, png, gif, bmp, tiff

tags
Array of strings (AccessRuleTags)

Optional. _nio_access_rule will be added even if not presented. Access Rule tag must be non-empty and less than 256 chars.

display_name
string (AccessRuleDisplayName)

Optional. Display Name must be non-empty and less than 1000 chars.

Responses

Request samples

Content type
application/json
{
  • "dataset_id": 123456789,
  • "company_constraint": {
    },
  • "constraints": [
    ],
  • "description": "Charge 1 cent USD per row if the row's ID type is IDFA",
  • "pricing": 1000000
}

Response samples

Content type
application/json
{
  • "id": 4,
  • "dataset_id": 123456789,
  • "company_constraint": {
    },
  • "constraints": [
    ],
  • "created_at": "2021-12-01T12:32:23Z",
  • "description": "Price for IDFAs",
  • "pricing": 99000,
  • "status": "active",
  • "updated_at": "2021-12-12T12:32:23Z"
}

Update an access rule

Update an access rule.

The dataset to which an access rule is assigned cannot be changed.

Authorizations:
BearerAuth
path Parameters
access_rule_id
required
integer

Access rule identifier.

Request Body schema: application/json
object (AccessRuleCompanyConstraint)

A constraint describing which companies the access rule should or should not apply to.

constraints
Array of strings (AccessRuleConstraints)

A set of boolean SQL expressions used to determine whether the access rule should be applied to a row from the dataset.

If more than one constraint is specified then all the constraints must evaluate to true for the access rule to be applied.

If constraints is not specified or empty then all rows will match the access rule.

E.g. for a dataset with the following type definition:

{
  "type": "object",
  "properties": {
    "idValue": {
      "type": "string"
    },
    "idType": {
      "type": "string",
      "enum": [
        "idfa",
        "adid"
      ]
    },
    "timestamp": {
      "type": "timestamptz"
    }
  },
  "required": [
    "idValue"
  ]
}

Valid constraints include:

  • Is the ID type IDFA?
idType = 'idfa'
  • Is the ID type non-null?
idType is not null
  • Was the row collected within the last 90 days?
timestamp > date_sub(current_date(), 90)
description
string (AccessRuleDescription)

A human-friendly description of the access rule.

pricing
required
integer (AccessRulePricing)

How much to charge for a row which matches this access rule.

Prices are specified in microcents USD to allow for very granular pricing control.

Some useful conversions:

  • 1 cent = 1000000 microcents
  • 1 dollar = 100000000 microcents

If you wanted to price your data at $1 USD per 1000 rows, then you'd set pricing to 100000.

Responses

Request samples

Content type
application/json
{
  • "company_constraint": {
    },
  • "description": "Charge 1 cent USD per row if the row's ID type is IDFA",
  • "pricing": 1000000,
  • "constraints": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 4,
  • "dataset_id": 123456789,
  • "company_constraint": {
    },
  • "constraints": [
    ],
  • "created_at": "2021-12-01T12:32:23Z",
  • "description": "Price for IDFAs",
  • "pricing": 99000,
  • "status": "active",
  • "updated_at": "2021-12-12T12:32:23Z"
}

Delete an access rule

Access rule deletion cannot be undone.

Authorizations:
BearerAuth
path Parameters
access_rule_id
required
integer

Access rule identifier.

Responses

Get an Access Rule by id (V2)

Get an access rule.

Authorizations:
BearerAuth
path Parameters
access_rule_id
required
integer

Access rule identifier.

Responses

Response samples

Content type
application/json
Example
{
  • "name": "access_rule_ebc86610_0907_4374_8fc9_be360f0ff8d0",
  • "id": 1,
  • "company_id": 1,
  • "company_name": "company",
  • "company_slug": "company_slug_60a4e678_1d56_48a7_8b8b_4e1d689b11a6",
  • "display_name": "display name",
  • "description": "description",
  • "image": "https://narrative.test/1.png",
  • "status": "active",
  • "tags": [
    ],
  • "nql": "select company_data.\"1\".columnA from company_data.\"1\" WHERE columnA = columnB",
  • "schema": {
    },
  • "collaborators": {
    },
  • "price_cpm_usd": 1000.054,
  • "metadata": {
    },
  • "dataset_ids": [
    ],
  • "type": "owned"
}

Get an Access Rule by name

Get an access rule by name and company slug.

Authorizations:
BearerAuth
path Parameters
company_slug
required
string

Company slug.

access_rule_name
required
string

Access rule name.

Responses

Response samples

Content type
application/json
Example
{
  • "name": "access_rule_ebc86610_0907_4374_8fc9_be360f0ff8d0",
  • "id": 1,
  • "company_id": 1,
  • "company_name": "company",
  • "company_slug": "company_slug_60a4e678_1d56_48a7_8b8b_4e1d689b11a6",
  • "display_name": "display name",
  • "description": "description",
  • "image": "https://narrative.test/1.png",
  • "status": "active",
  • "tags": [
    ],
  • "nql": "select company_data.\"1\".columnA from company_data.\"1\" WHERE columnA = columnB",
  • "schema": {
    },
  • "collaborators": {
    },
  • "price_cpm_usd": 1000.054,
  • "metadata": {
    },
  • "dataset_ids": [
    ],
  • "type": "owned"
}

Get accessible Access Rules

Get all accessible Access Rules.

'owned_only' and 'owned_only' are flags, they don't require values.

'tag', 'dataset_id', and 'company_id' are multi-params.

Query like 'tag=tag1&tag=tag2&company_id=1&company_id=2' is interpreted as "access rules with tags that comprise 'tag1' or 'tag2' AND belonging to companies with id '1' or '2'.

Authorizations:
BearerAuth
query Parameters
owned_only
boolean

If enabled, returns only owned rules.

shared_only
boolean

If enabled, returns only shared (not owned) rules.

tag
string

Check whether tag is presented. If multiple tags specified, looks if any of them is attached to a rule.

company_id
integer

Check whether owned by the company. Can be specified multiple times.

page
integer

Number of page. Stars from the first (1) page.

per_page
integer

Number of records to return.

dataset_id
integer

Check whether the rule is associated with specified dataset. Multiple values are allowed.

Responses

Response samples

Content type
application/json
{
  • "prev_page": null,
  • "current_page": 1,
  • "next_page": null,
  • "total_records": 2,
  • "total_pages": 1,
  • "records": [
    ]
}

Apps

Lists apps

Authorizations:
BearerAuth
query Parameters
category
Array of strings
Items Value: "destination_connector"

a filter for app categories

Responses

Lists profiles

Authorizations:
BearerAuth
query Parameters
app_slug
string

unique app name

Responses

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Put Schema

Submitting (create or update) JSON Schema (2019-09 version) for an app.

Authorizations:
BearerAuth
query Parameters
app_slug
string

unique app name

Request Body schema: application/json
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
  • "stream_id": "173fd1b7-72c4-44c4-9244-55a0a167a352",
  • "version_number": 0,
  • "value": { },
  • "created_at": "2019-08-24T14:15:22Z"
}

Get Schema

Authorizations:
BearerAuth
query Parameters
app_slug
string

unique app name

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Schema

Authorizations:
BearerAuth
path Parameters
version_id
required
string <uuid>

schema version id

query Parameters
app_slug
string

unique app name

Responses

Response samples

Content type
application/json
{
  • "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
  • "stream_id": "173fd1b7-72c4-44c4-9244-55a0a167a352",
  • "version_number": 0,
  • "value": { },
  • "created_at": "2019-08-24T14:15:22Z"
}

Post Data instance

Submitting (create or update) data for a profile.

Authorizations:
BearerAuth
path Parameters
profile_id
required
string <uuid>

the profile id

query Parameters
app_slug
string

unique app name

Request Body schema: application/json
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "data": { },
  • "meta": {
    }
}

Get Data instance

Authorizations:
BearerAuth
path Parameters
profile_id
required
string <uuid>

the profile id

query Parameters
app_slug
string

unique app name

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "schema_version_id": "4b5aa0f4-8eae-49a1-af8e-ef2be32c6e7d",
  • "value": { },
  • "created_at": "2019-08-24T14:15:22Z"
}

Update a slug

Slug can be changed (from NULL) just once.

Authorizations:
BearerAuth
path Parameters
app_id
required
integer <int64>

the app id

Request Body schema: application/json
slug
string

Responses

Request samples

Content type
application/json
{
  • "slug": "string"
}

Response samples

Content type
application/json
{
  • "app_id": 0,
  • "slug": "string"
}

Access Tokens

API Access Token management

List System Access Tokens

List System Access Tokens

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Create a System Access Token

Create a System Access Token

Authorizations:
BearerAuth
Request Body schema: application/json
name
required
string

The name of the token

Array of objects (Permission)

The requested permissions

string or string

Responses

Request samples

Content type
application/json
{
  • "name": "My Token",
  • "permissions": [
    ],
  • "expires_at": "2023-10-31T11:19:13.400498Z"
}

Response samples

Content type
application/json
{
  • "id": "546c65d6-e589-4d3c-b1fe-7e61711cc418",
  • "name": "My Token",
  • "permissions": [
    ],
  • "expires_at": "2023-10-31T11:19:13.400498Z",
  • "access_token": "ldg8uuGibVJNHI9s+dcdIQ=="
}

Get a System Access Token by id

Get a System Access Token by id

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "record": {
    }
}

Update a System Access Token

Update a System Access Token

Authorizations:
BearerAuth
Request Body schema: application/json
name
string

The name of the token

Array of objects (Permission)

The requested permissions

string or string

Responses

Request samples

Content type
application/json
{
  • "name": "My Token",
  • "permissions": [
    ],
  • "expires_at": "2023-10-31T11:19:13.400498Z"
}

Response samples

Content type
application/json
{
  • "id": "546c65d6-e589-4d3c-b1fe-7e61711cc418",
  • "name": "My Token",
  • "permissions": [
    ],
  • "expires_at": "2023-10-31T11:19:13.400498Z"
}

Delete a System Access Token

Delete a System Access Token

Authorizations:
BearerAuth

Responses

Attributes

An attribute models a standardized data point available for sale on the Narrative marketplace.

Narrative automatically turns data points from provider datasets into attributes so that buyers can purchase well-formed, standardized data from any supplier on the marketplace.

Get attributes

Return all attributes.

Responses

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Create an attribute

Create a new attribute.

Authorizations:
BearerAuth
Request Body schema: application/json
One of
type
required
string
Value: "array"

An array with elements of any data type.

validations
Array of strings (Validations)

A raw Spark SQL expression determining whether a value for the given column is valid or not.

If more than one validation is specified then all the validation must evaluate to true for the column value to be considered valid.

If validations is not specified or empty then all rows will match the access rule.

E.g. for an attribute with the following definition:

{
  "name": "unique_id",
  "type": "object",
  "properties": {
    "identifier_value": {
      "type": "string"
    },
    "identifier_type": {
      "type": "string"
    },
    "timestamp": {
      "type": "timestamptz"
    }
  },
  "required": [
    "value"
  ]
}

Valid validations include:

  • Is the ID type lowercased?
"identifier_type": {
  "type": "string",
  "validations": [
    "lower($this.identifier_type) = $this.identifier_type"
  ]
}
  • Was the row collected within the last 90 days?
"timestamp": {
  "type": "timestamptz",
  "validations": [
    "$this.timestamp > date_sub(current_date(), 90)"
  ]
}
name
required
string (AttributeName)

An short identifier for the attribute to be used when it is referenced in validations.

Attribute names must consist of only alphanumeric characters or underscores and be < 255 characters long.

description
string (AttributeDescription)

A description of the type of data the attribute represents, including collection methodology, assumptions, etc.

display_name
required
string (AttributeDisplayName)

A public-facing descriptive name for the attribute.

Responses

Request samples

Content type
application/json
Example
{
  • "type": "object",
  • "validations": [
    ],
  • "name": "price",
  • "description": "The price of an order, product, or a price component. Currency field accepts ISO 4217 currency codes",
  • "display_name": "Price",
  • "properties": {
    },
  • "required": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "type": "object",
  • "validations": [
    ],
  • "id": 123456789,
  • "name": "price",
  • "description": "The price of an order, product, or a price component. Currency field accepts ISO 4217 currency codes",
  • "display_name": "Price",
  • "properties": {
    },
  • "required": [
    ]
}

Get an attribute

path Parameters
required
integer or string

Either an attribute name or an attribute id

Responses

Response samples

Content type
application/json
Example
{
  • "type": "object",
  • "validations": [
    ],
  • "id": 123456789,
  • "name": "price",
  • "description": "The price of an order, product, or a price component. Currency field accepts ISO 4217 currency codes",
  • "display_name": "Price",
  • "properties": {
    },
  • "required": [
    ],
  • "metadata": {
    }
}

Delete an attribute

Permanently removes an attribute from the platform.

Attribute deletion will fail if the given attribute is referenced by another attribute.

Attribute deletions cannot be undone.

Authorizations:
BearerAuth
path Parameters
required
integer or string

Either an attribute name or an attribute id

Responses

Get attribute references.

path Parameters
attribute_id
required
integer

Unique identifier for an attribute.

Responses

Response samples

Content type
application/json
Example
{
  • "type": "object",
  • "validations": [
    ],
  • "id": 123456789,
  • "name": "price",
  • "description": "The price of an order, product, or a price component. Currency field accepts ISO 4217 currency codes",
  • "display_name": "Price",
  • "properties": {
    },
  • "required": [
    ]
}

Auth

Request or refresh an OAuth token

/oauth/token

Requests or refreshes the OAuth Token.

Authorizations:
TokenRequest
Request Body schema: application/x-www-form-urlencoded

Request or refresh token

grant_type
required
string
Enum: "refresh_token" "client_credentials"
client_id
string

A client specific identifier provided by Narrative

refresh_token
string

The token used to refresh the API session. Required if grant_type is refresh_token

Responses

Response samples

Content type
application/json
{
  • "access_token": "xxxxxxxxxxx",
  • "access_token_expires_in": 3600,
  • "refresh_token": "yyyyyyyyyyy",
  • "refresh_token_expires_in": 14400
}

Authentication

User login and registration

Authenticate a user based on a Stytch session token

Authenticate the user based on the Stytch session token, and return the user information, and API Access Token. The Stych session token can be obtained from a Magic Links or OAuth token thanks to the registration status API.

Authorizations:
BearerAuth
Request Body schema: application/json
stytch_session_token
required
string

The Stytch session token

Responses

Request samples

Content type
application/json
{
  • "stytch_session_token": "1rjpyoFiYLucsV-nuoi7dZ_VOkMUkcZLw6rICEYBzAy0"
}

Response samples

Content type
application/json
{
  • "user": {
    },
  • "api_token": {
    },
  • "legacy_token": "legacy-dsm-token"
}

Register a user based on a Stytch session token

Register the user based on the Stytch session token and name/company name, and return the the created user id. The Stych session token can be obtained from a Magic Links or OAuth token thanks to the registration status API.

Authorizations:
BearerAuth
Request Body schema: application/json
stytch_session_token
required
string

The Stytch session token

name
string

The name of the user

company_name
required
string

The name of the company

Responses

Request samples

Content type
application/json
{
  • "stytch_session_token": "1rjpyoFiYLucsV-nuoi7dZ_VOkMUkcZLw6rICEYBzAy0",
  • "name": "First Last",
  • "company_name": "ACME Corp"
}

Response samples

Content type
application/json
{
  • "user_id": 100
}

Report whether the user associatd to a Stytch OAuth or Magic Links token has been fully registered on Narrative side

Report whether the user associatd to a Stytch OAuth or Magic Links token has been fully registered on Narrative side. Provides a Stytch session token that can be used to access the login and register APIs.

Authorizations:
BearerAuth
Request Body schema: application/json
required
MagicLinksToken (object) or OAuthToken (object) (StytchToken)

The Stytch Magic Links or OAuth token

session_duration_minutes
integer

The duration in minutes of the Stytch session to create

Responses

Request samples

Content type
application/json
{
  • "stytch_token": {
    },
  • "session_duration_minutes": 5
}

Response samples

Content type
application/json
{
  • "status": "complete",
  • "email": "[email protected]",
  • "stytch_session_token": "10hLht9FCo9cBp3I69uY5KjYMmy5VqmZjAVEz1CKZjsa",
  • "stytch_session_jwt": "eyJhbGciOiJSUzI1NiIsImtpZCI6Imp3ay10ZXN0LTk1YjU2OGZhLTk1NWUtNGQ2OC04NDljLTM5MDA0MmEwZTlmOCIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsicHJvamVjdC10ZXN0LWQ1Y2E2MjhlLWFmMzctNDhmZC1hZTliLWIzMmUwY2Y5NmEyYyJdLCJleHAiOjE2ODUxMjkwNTAsImh0dHBzOi8vc3R5dGNoLmNvbS9zZXNzaW9uIjp7ImlkIjoic2Vzc2lvbi10ZXN0LTRlNTg4ZDQ3LTJlZjctNDZhNy1iMGQxLTQxOGJhMmZjNTljMiIsInN0YXJ0ZWRfYXQiOiIyMDIzLTA1LTI2VDE5OjE0OjU1WiIsImxhc3RfYWNjZXNzZWRfYXQiOiIyMDIzLTA1LTI2VDE5OjE5OjEwWiIsImV4cGlyZXNfYXQiOiIyMDIzLTA1LTI2VDIwOjE0OjU1WiIsImF0dHJpYnV0ZXMiOnsidXNlcl9hZ2VudCI6IiIsImlwX2FkZHJlc3MiOiIifSwiYXV0aGVudGljYXRpb25fZmFjdG9ycyI6W3sidHlwZSI6Im9hdXRoIiwiZGVsaXZlcnlfbWV0aG9kIjoib2F1dGhfZ2l0aHViIiwibGFzdF9hdXRoZW50aWNhdGVkX2F0IjoiMjAyMy0wNS0yNlQxOToxNDo1NVoiLCJnaXRodWJfb2F1dGhfZmFjdG9yIjp7ImlkIjoib2F1dGgtdXNlci10ZXN0LTdlY2M5YjUxLTU0YzUtNDg2MS04NjI2LTQyM2Q0Y2ZiYjQxMiIsInByb3ZpZGVyX3N1YmplY3QiOiIxNDIzMjkifX1dfSwiaWF0IjoxNjg1MTI4NzUwLCJpc3MiOiJzdHl0Y2guY29tL3Byb2plY3QtdGVzdC1kNWNhNjI4ZS1hZjM3LTQ4ZmQtYWU5Yi1iMzJlMGNmOTZhMmMiLCJuYmYiOjE2ODUxMjg3NTAsInN1YiI6InVzZXItdGVzdC03ZDYzYmMwNS05YzlmLTRmMTktODhhYS1iMmQwODk3ZGNiN2YifQ.OthwVlyy7Eu0g8h9K3tG2KzZBiOi3hykP-BpdTjrR4tZUXwqPyYPs8BmiaPRQOd17zyUNLxjGH4q5sfU6F0z4BXQXd3U8hWdRYRmUNVFPvLhFWva5FNP5ZYRD8XX_cjYTWV0E41Zd_W3YvFK5hCYs7cwYyR0mMw2XRzTYX1CjTfHOtNmPW-uLwhvHqAroLa2vM7PoyFlS0Xs2j0Dje01WI0eqJYgSVTwB5ZMTWttJKqXjFPaLQ-7XkJxHtmpXTxCoO-U38kDba26cyhTQrXBoHV2c8KMtrBWS3L3_kN-gw96FzcJ0C2W8HxhZJrI_GIZ4OLxFy3jxXvjDcsjMX940w"
}

Billings

Get dataset storage billing

Get dataset storage billings paginated.

Authorizations:
BearerAuth
query Parameters
per_page
integer

Number of records to return.

offset
integer

Number of records to skip (it's usually page_number * per_page).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get dataset storage billing for company

Get dataset storage billings for a company id paginated. Company id is extracted from token.

Authorizations:
BearerAuth
query Parameters
per_page
integer

Number of records to return.

offset
integer

Number of records to skip (it's usually page_number * per_page).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Companies

Lists Company Domains

/companies/{company_id}/domains

Returns all domains registered by a specific company

Authorizations:
BearerAuth
path Parameters
company_id
required
integer <int64>
Example: 345

The id of an existing company

Responses

Response samples

Content type
application/json
{
  • "domains": [
    ]
}

Get a presigned URL to upload company logo

Sending a file to Narrative is a two step process. This endpoint allows you to request an upload_url which can be used in a PUT request to upload the file. For example, once you have received an upload_url you could use it as follows:

curl -v --upload-file logo.png {upload_url}

The generated upload_url is only valid for 30 minutes after issuance.

Response also contains permanent_url, expiry, and content_type. permanent_url should be used as long-term reference. content_type should be used as Content-Type header since it is part of URL signature.

Request Body schema: application/json
image_name
string

Responses

Request samples

Content type
application/json
{
  • "image_name": "logo.png"
}

Company Marketing Information

Get all data-streams provider companies

Returns all the companies providing data-stream market offers.

Responses

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Returns the company and user associated with the token

Returns the company and user associated with the token.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "id": 7,
  • "user_id": 100,
  • "credit_limit_usd": 1000,
  • "check_datashops_credit_limit": false
}

Get marketing details on a company

Returns the marketing detailed information on a company.

path Parameters
company_id
required
integer <int64>
Example: 345

The id of an existing company

Responses

Response samples

Content type
application/json
{
  • "id": 28,
  • "name": "ACM",
  • "short_description": "American Company that Manufactures Everything",
  • "long_description": "The Acme Corporation is an ironic name for the fictional corporation, appearing in the Road Runner/Wile E. Coyote animated shorts, where it was used as a running gag.",
  • "company_type": "Manufactures Everything",
  • "image_url": "https://d18qs7yq39787j.cloudfront.net/uploads/company/3862/acme_logo.jpg",
  • "location": "USA",
  • "size": "200 - 500 Employees",
  • "website": "N/A",
  • "contact": "[email protected]",
  • "created_at": "2017-04-23T11:59:33"
}

Connections

Returns a connection

Authorizations:
App_Token
path Parameters
connection_id
required
string <uuid>

Unique identifier for a connection.

Responses

Response samples

Content type
application/json
{
  • "id": "21691f26-f308-4e98-896c-579db27da04b",
  • "dataset_id": 42,
  • "profile_id": "d555f07f-f140-40d2-91af-e6aa54f7488b",
  • "quick_settings": {
    },
  • "status": "active"
}

Archive a connection

Authorizations:
App_Token
path Parameters
connection_id
required
string <uuid>

Unique identifier for a connection.

Responses

Response samples

Content type
application/json
{
  • "id": "21691f26-f308-4e98-896c-579db27da04b",
  • "dataset_id": 42,
  • "profile_id": "d555f07f-f140-40d2-91af-e6aa54f7488b",
  • "quick_settings": {
    },
  • "status": "active"
}

Searches for connections from a given dataset id

Authorizations:
App_Token
query Parameters
dataset_id
required
number

Unique identifier for a dataset.

Responses

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Creates a connection

Authorizations:
App_Token
Request Body schema: application/json
dataset_id
number
profile_id
string <uuid> (UUID)
quick_settings
object

Responses

Request samples

Content type
application/json
{
  • "dataset_id": 42,
  • "profile_id": "d555f07f-f140-40d2-91af-e6aa54f7488b",
  • "quick_settings": {
    }
}

Response samples

Content type
application/json
{
  • "id": "21691f26-f308-4e98-896c-579db27da04b",
  • "dataset_id": 42,
  • "profile_id": "d555f07f-f140-40d2-91af-e6aa54f7488b",
  • "quick_settings": {
    },
  • "status": "active"
}

Data Shops

Create a data-shop.

Create a new data-shop.

Authorizations:
BearerAuth
Request Body schema: application/json
hostname
required
string <trimmed-non-empty> (Hostname) non-empty

A shops hostname.

fe_manifest
object

Any valid json object is accepted. This allows FE/UI to decide the shape of this.

Responses

Request samples

Content type
application/json
{
  • "hostname": "string",
  • "fe_manifest": { }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "hostname": "string",
  • "compan_id": 345,
  • "manifest": { },
  • "created_by": 0,
  • "created_at": "2021-06-24T00:54:40.029056Z",
  • "updated_by": 0,
  • "updated_at": "2021-06-24T00:54:40.029056Z"
}

Get a data-shop by its id.

Gets the data-shop given its uuid.

path Parameters
data_shop_id
required
string <uuid>

Unique identifier for a data-shop.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "hostname": "string",
  • "compan_id": 345,
  • "manifest": { },
  • "created_by": 0,
  • "created_at": "2021-06-24T00:54:40.029056Z",
  • "updated_by": 0,
  • "updated_at": "2021-06-24T00:54:40.029056Z"
}

Update a data-shop.

Update a new data-shop.

Note: Not passing a fe_manifest will remove the fe_manifest from the data-shop manifest.

Only a user belonging to the company can update a data-shop.

Authorizations:
BearerAuth
path Parameters
data_shop_id
required
string <uuid>

Unique identifier for a data-shop.

Request Body schema: application/json
hostname
required
string <trimmed-non-empty> (Hostname) non-empty

A shops hostname.

fe_manifest
object

Any valid json object is accepted. This allows FE/UI to decide the shape of this.

Responses

Request samples

Content type
application/json
{
  • "hostname": "string",
  • "fe_manifest": { }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "hostname": "string",
  • "compan_id": 345,
  • "manifest": { },
  • "created_by": 0,
  • "created_at": "2021-06-24T00:54:40.029056Z",
  • "updated_by": 0,
  • "updated_at": "2021-06-24T00:54:40.029056Z"
}

Get a data-shop by its host name.

Gets the data-shop given its host name.

path Parameters
host_name
required
string

hostname like 'datashop.narrative.io'

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "hostname": "string",
  • "compan_id": 345,
  • "manifest": { },
  • "created_by": 0,
  • "created_at": "2021-06-24T00:54:40.029056Z",
  • "updated_by": 0,
  • "updated_at": "2021-06-24T00:54:40.029056Z"
}

Fetch many data-shops

Fetch many data-shops, given their ids.

Allows only upto 200 data-shops to be fetched in a call. If no ids are requested, empty array result is returned.

Authorizations:
BearerAuth
Request Body schema: application/json
ids
required
Array of strings <uuid> (UUID) <= 200 characters

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "hostname": "string",
  • "compan_id": 345,
  • "manifest": { },
  • "created_by": 0,
  • "created_at": "2021-06-24T00:54:40.029056Z",
  • "updated_by": 0,
  • "updated_at": "2021-06-24T00:54:40.029056Z"
}

Get all data-shops for a company.

Gets all data-shops belonging to a company or empty if non exist.

Authorizations:
BearerAuth
path Parameters
company_id
required
integer <int64>
Example: 345

The id of an existing company

Responses

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Data Streams

The data-stream API endpoints allows one to create and update data-streams. Additionally the endpoints allow finding data-streams using free text search. A few of the endpoints are behind authorization.

Update endpoint allows a client to post an edited data-stream document as is, without having to change its shape. The API ensures that only certain fields are allowed to be modified. Attempts to modify fields not up for client modifications are ignored.

Related guides:

Create a data-stream.

Create a new data-stream.

Any datasets involved in the data-stream should exist and be active. Any fields referred

Authorizations:
BearerAuth
Request Body schema: application/json
name
required
string <trimmed-non-empty> (Name) non-empty

A name.

slug
required
string (Slug) non-empty ^[a-zA-Z0-9-_.:]+$

The DataStream's slug. Used for SEO/URLs.

object (Content)
tags
Array of strings <trimmed-non-empty> (Tag) [ items <trimmed-non-empty > non-empty ]
category
string <trimmed-non-empty> (Category) non-empty

The DataStream's category. Useful for searches and cataloging.

Array of objects (Offer)
object (DataRules)

Data rules capture the rules around how the data is handled within a data stream. The starting point might be an already predefined and active dataset(s) or the global data attributes on the platform.

Data rules might apply further filtering on the data being ingested and exported through the stream.

object (AuthRules)

Responses

Request samples

Content type
application/json
{
  • "name": "Greg Test Datastream",
  • "slug": "greg-test-1",
  • "content": {
    },
  • "tags": [
    ],
  • "category": "Test",
  • "offers": [
    ],
  • "data_rules": {
    },
  • "auth_rules": null
}

Response samples

Content type
application/json
{
  • "id": "f94e8803-fc03-4c3e-a3fc-c3ffe3993788",
  • "company_id": 100,
  • "name": "best data stream name",
  • "slug": "this-is-a-slug",
  • "content": {
    },
  • "tags": [
    ],
  • "category": "categoryA",
  • "offers": [
    ],
  • "data_rules": {
    },
  • "auth_rules": {
    },
  • "created_by": 5000,
  • "created_at": "2021-06-29T10:58:36.726Z",
  • "updated_at": "2021-06-29T10:58:36.726Z",
  • "datasets": null
}

Get a data-stream by its id.

Gets the data-stream given its uuid.

path Parameters
data_stream_id
required
string <uuid>

Unique identifier for a data-stream.

Responses

Response samples

Content type
application/json
{
  • "id": "f94e8803-fc03-4c3e-a3fc-c3ffe3993788",
  • "company_id": 100,
  • "name": "best data stream name",
  • "slug": "this-is-a-slug",
  • "content": {
    },
  • "tags": [
    ],
  • "category": "categoryA",
  • "offers": [
    ],
  • "data_rules": {
    },
  • "auth_rules": {
    },
  • "created_by": 5000,
  • "created_at": "2021-06-29T10:58:36.726Z",
  • "updated_at": "2021-06-29T10:58:36.726Z",
  • "datasets": null
}

Update a data-stream.

Update a new data-stream.

The main idea: get a data-stream document/resource, after creation or accessing by id, then update the document and PUT it as it is.

Of course certain things aren't updateable and are ignored, for instance identifiers already established (like DS id) and metadata like creation/update dates and who created/updated the entity.

Things that can be updated

  • name
  • slug
  • content
  • tags
  • category
  • offers
  • data_rules
  • auth_rules

Note: nested structures like content etc. are changed as complete structures, hence care needs to be taken to include unchanged data at as the same time as the data being changed so as not to over-write the rest of it.

Any validations applicable on creation time also apply on updates.

Only a user belonging to the company can update a data-stream.

Authorizations:
BearerAuth
path Parameters
data_stream_id
required
string <uuid>

Unique identifier for a data-stream.

Request Body schema: application/json
id
string <uuid> (UUID)
company_id
integer <int64> (CompanyId)

The id of an existing company

name
string <trimmed-non-empty> (Name) non-empty

A name.

slug
string (Slug) non-empty ^[a-zA-Z0-9-_.:]+$

The DataStream's slug. Used for SEO/URLs.

object (Content)
tags
Array of strings <trimmed-non-empty> (Tag) [ items <trimmed-non-empty > non-empty ]
category
string <trimmed-non-empty> (Category) non-empty

The DataStream's category. Useful for searches and cataloging.

Array of objects (Offer)
object (DataRules)

Data rules capture the rules around how the data is handled within a data stream. The starting point might be an already predefined and active dataset(s) or the global data attributes on the platform.

Data rules might apply further filtering on the data being ingested and exported through the stream.

object (AuthRules)
created_by
integer <int64>

Unique id from a user who created it.

created_at
string (Instant)

ISO-8601 instant.

updated_at
string (Instant)

ISO-8601 instant.

Responses

Request samples

Content type
application/json
{
  • "id": "f94e8803-fc03-4c3e-a3fc-c3ffe3993788",
  • "company_id": 100,
  • "name": "best data stream name",
  • "slug": "this-is-a-slug",
  • "content": {
    },
  • "tags": [
    ],
  • "category": "categoryA",
  • "offers": [
    ],
  • "data_rules": {
    },
  • "auth_rules": {
    },
  • "created_by": 5000,
  • "created_at": "2021-06-29T10:58:36.726Z",
  • "updated_at": "2021-06-29T10:58:36.726Z",
  • "datasets": null
}

Response samples

Content type
application/json
{
  • "id": "f94e8803-fc03-4c3e-a3fc-c3ffe3993788",
  • "company_id": 100,
  • "name": "best data stream name",
  • "slug": "this-is-a-slug",
  • "content": {
    },
  • "tags": [
    ],
  • "category": "categoryA",
  • "offers": [
    ],
  • "data_rules": {
    },
  • "auth_rules": {
    },
  • "created_by": 5000,
  • "created_at": "2021-06-29T10:58:36.726Z",
  • "updated_at": "2021-06-29T10:58:36.726Z",
  • "datasets": null
}

Fetch many data-streams

Fetch many data-streams, given their ids.

Allows only upto 50 data-streams to be fetched in a call. If no ids are requested, empty array result is returned.

Note: If n ids are requested this might return any m (0 <= m <= n) number of data-streams depending on how many actually do exist. It is the clients duty to find this discrepancy.

Authorizations:
BearerAuth
Request Body schema: application/json
ids
required
Array of strings <uuid> (UUID) <= 50 characters

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Get all data-streams for a company.

Gets all data-streams belonging to a company or empty if non exist.

Authorizations:
BearerAuth
path Parameters
company_id
required
integer <int64>
Example: 345

The id of an existing company

query Parameters
per_page
integer

Number of records to return.

offset
integer

Number of records to skip (it's usually page_number * per_page).

Responses

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Get all data-streams for a company given a search expression.

Gets all data-streams belonging to a company and the given search expression.

Search expressions follow the postgres 'websearch_to_tsquery' specification:

  1. logical operators : tshirt and apparel or accessories -leather
  2. phrases : "find this" -"but not this"
  3. multiple words : goods services (this is the same as goods and services)

Reference: https://www.postgresql.org/docs/11/textsearch-controls.html#TEXTSEARCH-PARSING-QUERIES search for 'websearch_to_tsquery'

Authorizations:
BearerAuth
path Parameters
company_id
required
integer <int64>
Example: 345

The id of an existing company

query Parameters
q
required
string
Example: q=apparel or fabric or accessories -leather

search query expression

per_page
integer

Number of records to return.

offset
integer

Number of records to skip (it's usually page_number * per_page).

Responses

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Gets the data-stream for a given company and slug.

Gets the data-stream for a given company and slug

path Parameters
company_id
required
integer <int64>
Example: 345

The id of an existing company

slug
required
string^[a-zA-Z0-9-_.:]+$

The DataStream's slug. Used for SEO/URLs.

query Parameters
per_page
integer

Number of records to return.

offset
integer

Number of records to skip (it's usually page_number * per_page).

Responses

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Get schema

Retrieve schema for deliveries from this data stream.

Authorizations:
BearerAuth
path Parameters
company_id
required
integer <int64>
Example: 345

The id of an existing company

slug
required
string^[a-zA-Z0-9-_.:]+$

The DataStream's slug. Used for SEO/URLs.

Responses

Response samples

Content type
application/json
{
  • "value": {
    },
  • "iso_4217_currency": {
    },
  • "tags": {
    }
}

Get all data-streams for the given company and its data-shop hostname.

Gets all data-streams belonging to a company, filtered for the hostname.

path Parameters
company_id
required
integer <int64>
Example: 345

The id of an existing company

host_name
required
string

hostname like 'datashop.narrative.io'

query Parameters
per_page
integer

Number of records to return.

offset
integer

Number of records to skip (it's usually page_number * per_page).

Responses

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Find data-streams for the given company and its data-shop hostname and the given search expression.

Gets all data-streams belonging to a company, filtered for the hostname and the given search expression.

Search expressions follow the postgres 'websearch_to_tsquery' specification:

  1. logical operators : tshirt and apparel or accessories -leather
  2. phrases : "find this" -"but not this"
  3. multiple words : goods services (this is the same as goods and services)

Reference: https://www.postgresql.org/docs/11/textsearch-controls.html#TEXTSEARCH-PARSING-QUERIES search for 'websearch_to_tsquery'

path Parameters
company_id
required
integer <int64>
Example: 345

The id of an existing company

host_name
required
string

hostname like 'datashop.narrative.io'

query Parameters
q
required
string
Example: q=apparel or fabric or accessories -leather

search query expression

per_page
integer

Number of records to return.

offset
integer

Number of records to skip (it's usually page_number * per_page).

Responses

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Get all data-streams for a company given a sales channel

Gets all data-streams belonging to a company, given a sales channel.

Sales channels:

  1. data-streams-market
  2. data-shop
path Parameters
company_id
required
integer <int64>
Example: 345

The id of an existing company

sales_channel
required
string
Enum: "data_streams_market" "data_shop"
query Parameters
o
string
Enum: "price-low" "price-high"
Example: o=price-high

Order by offers price low/high

per_page
integer

Number of records to return.

offset
integer

Number of records to skip (it's usually page_number * per_page).

Responses

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Find data-streams for the given company and a sales-channel and the given search expression.

Gets all data-streams belonging to a company, filtered for the sales-channel and the given search expression.

Search expressions follow the postgres 'websearch_to_tsquery' specification:

  1. logical operators : tshirt and apparel or accessories -leather
  2. phrases : "find this" -"but not this"
  3. multiple words : goods services (this is the same as goods and services)

Reference: https://www.postgresql.org/docs/11/textsearch-controls.html#TEXTSEARCH-PARSING-QUERIES search for 'websearch_to_tsquery'

path Parameters
company_id
required
integer <int64>
Example: 345

The id of an existing company

sales_channel
required
string
Enum: "data_streams_market" "data_shop"
query Parameters
q
required
string
Example: q=apparel or fabric or accessories -leather

search query expression

per_page
integer

Number of records to return.

offset
integer

Number of records to skip (it's usually page_number * per_page).

Responses

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Find data-streams available on the data-streams-market.

Gets all data-streams available on the data-streams-market matching the given search expression.

Search expressions follow the postgres 'websearch_to_tsquery' specification:

  1. logical operators : tshirt and apparel or accessories -leather
  2. phrases : "find this" -"but not this"
  3. multiple words : goods services (this is the same as goods and services)

Reference: https://www.postgresql.org/docs/11/textsearch-controls.html#TEXTSEARCH-PARSING-QUERIES search for 'websearch_to_tsquery'

query Parameters
q
required
string
Example: q=apparel or fabric or accessories -leather

search query expression

per_page
integer

Number of records to return.

offset
integer

Number of records to skip (it's usually page_number * per_page).

Responses

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Contracts

Get contracts

Get contracts with details paginated.

Authorizations:
BearerAuth
query Parameters
per_page
integer

Number of records to return.

offset
integer

Number of records to skip (it's usually page_number * per_page).

Responses

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Create contract

Create a new contract with rates

Authorizations:
BearerAuth
Request Body schema: application/json
company_id
required
number

Company Id of a contract

object (PaymentMethod)

Payment Method

Array of objects (ContractRateRequest)

Optional rates associated to a contract

start
string <date-time>

Start date of a contract. If not specified it will be set to now

end
string <date-time>

Optional end date of a contract

internal_notes
string

Internal notes related to a contract

revision_notes
string

Internal notes related to specific contract revision

Responses

Request samples

Content type
application/json
{
  • "company_id": 0,
  • "payment_method": {
    },
  • "rates": [
    ],
  • "start": "2019-08-24T14:15:22Z",
  • "end": "2019-08-24T14:15:22Z",
  • "internal_notes": "string",
  • "revision_notes": "string"
}

Response samples

Content type
application/json
{
  • "createdContract": {
    },
  • "createdRates": [
    ]
}

Update Contract

Update active contract for a company

Authorizations:
BearerAuth
path Parameters
company_id
required
number
Example: 123

Unique identifier for a company.

Request Body schema: application/json
start
string <date-time>

Start date of a contract. If not specified it will be set to now

end
string <date-time>

Optional end date of a contract

object (PaymentMethod)

Payment Method

Array of objects (ContractRateRequest)

Optional rates associated to a contract

internal_notes
string
revision_notes
string

Responses

Request samples

Content type
application/json
{
  • "start": "2019-08-24T14:15:22Z",
  • "end": "2019-08-24T14:15:22Z",
  • "payment_method": {
    },
  • "rates": [
    ],
  • "internal_notes": "string",
  • "revision_notes": "string"
}

Response samples

Content type
application/json
{
  • "createdContract": {
    },
  • "createdRates": [
    ]
}

Get contract

Return single contract with details by id and revision.

Authorizations:
BearerAuth
path Parameters
revision
required
number
Example: 1

Contract revision

contract_id
required
string <uuid>
Example: ea9dddd2-e3ee-40b5-b03e-c3cd37c8a6f0

Unique identifier for a contract.

Responses

Response samples

Content type
application/json
{
  • "contract": {
    },
  • "rates": [
    ]
}

Get active contract

Return active contract with details for a company id.

Authorizations:
BearerAuth
path Parameters
company_id
required
number
Example: 123

Unique identifier for a company.

Responses

Response samples

Content type
application/json
{
  • "contract": {
    },
  • "rates": [
    ]
}

Get rates for active contract

Return all rates for a active contract for company_id

Authorizations:
BearerAuth
path Parameters
company_id
required
number
Example: 123

Unique identifier for a company.

Responses

Response samples

Content type
application/json
{
  • "records": {
    }
}

Get contracts for company

Return all contract with details for a company id. Company id is extracted from token.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Get active contract for company

Return active contract with details for a company id. Company id is extracted from token.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "contract": {
    },
  • "rates": [
    ]
}

Datasets

Any kind of data, in any schema, can be pushed into the Narrative Data Collaboration Platform as a dataset exactly as it is stored in your own system.

The datasets API allows you to manage your datasets.

Get datasets

Return all datasets belonging to the authenticated company.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Create a dataset

Create a new dataset.

Newly created datasets are in the pending status and require activation.

Authorizations:
BearerAuth
Request Body schema: application/json
name
required
string (DatasetName)

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

description
string (DatasetDescription)

A description of the data contained with the dataset.

required
object (DatasetSchema)

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
Array of strings (DatasetTags)

Tags that describe the dataset.

write_mode
required
string (DatasetWriteMode)
Enum: "append" "overwrite"

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.
derive_metrics_config
boolean (DeriveMetricsConfig)

A flag to enable derivation of the config.

Responses

Request samples

Content type
application/json
{
  • "description": "Mobile identifiers tied to birth information provided as part of app registration.",
  • "name": "Declared_Age",
  • "schema": {
    },
  • "tags": [
    ],
  • "derive_metrics_config": true
}

Response samples

Content type
application/json
{
  • "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": {
    },
  • "status": "active",
  • "tags": [
    ],
  • "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": {
    }
}

Update a dataset

Update existing dataset.

Authorizations:
BearerAuth
Request Body schema: application/json
name
required
string (DatasetName)

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

description
string (DatasetDescription)

A description of the data contained with the dataset.

required
object (DatasetSchema)

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
Array of strings (DatasetTags)

Tags that describe the dataset.

write_mode
required
string (DatasetWriteMode)
Enum: "append" "overwrite"

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.
derive_metrics_config
boolean (DeriveMetricsConfig)

A flag to enable derivation of the config.

Responses

Request samples

Content type
application/json
{
  • "description": "Mobile identifiers tied to birth information provided as part of app registration.",
  • "name": "Declared_Age",
  • "schema": {
    },
  • "tags": [
    ],
  • "derive_metrics_config": true
}

Response samples

Content type
application/json
{
  • "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": {
    },
  • "status": "active",
  • "tags": [
    ],
  • "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": {
    }
}

Get a dataset

Authorizations:
BearerAuth
path Parameters
dataset_id
required
integer

Unique identifier for a dataset.

Responses

Response samples

Content type
application/json
{
  • "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": {
    },
  • "status": "active",
  • "tags": [
    ],
  • "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": {
    }
}

Delete a dataset

Permanently removes a dataset from the platform.

Dataset deletion cannot be undone.

Authorizations:
BearerAuth
path Parameters
dataset_id
required
integer

Unique identifier for a dataset.

header Parameters
X-Narrative-Retention-Days
string

A number of days between 1 and 30. Defaults to 30.

Responses

Response samples

Content type
application/json
{
  • "error": "Unauthorized",
  • "error_description": "You are not authorized to use this endpoint."
}

Update a dataset

Update a pending or active dataset.

All fields can be updated on a pending dataset. Schema property metadata (sensitive, required, unsellable) and enumeration (append-only), description, display_name can be updated on an active dataset.

Archived datasets cannot be updated.

Authorizations:
BearerAuth
path Parameters
dataset_id
required
integer

Unique identifier for a dataset.

Request Body schema: application/json
name
string (DatasetName)

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

display_name
string (DatasetDisplayName)

The Dataset's name to display at UI.

description
string (DatasetDescription)

A description of the data contained with the dataset.

object (DatasetSchema)

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
Array of strings (DatasetTags)

Tags that describe the dataset.

write_mode
string (DatasetWriteMode)
Enum: "append" "overwrite"

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.

Responses

Request samples

Content type
application/json
{
  • "description": "Mobile identifiers tied to birth information provided as part of app registration.",
  • "name": "declared_age",
  • "display_name": "Declared Age",
  • "schema": {
    },
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "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": {
    },
  • "status": "active",
  • "tags": [
    ],
  • "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": {
    }
}

Activate a dataset

Activates a dataset.

This locks in the schema and allows Narrative to begin ingesting data.

Authorizations:
BearerAuth
path Parameters
dataset_id
required
integer

Unique identifier for a dataset.

Responses

Activate a dataset Deprecated

Activates a dataset.

This locks in the schema and allows Narrative to begin ingesting data.

Authorizations:
BearerAuth
path Parameters
dataset_id
required
integer

Unique identifier for a dataset.

Responses

Sample a dataset

Get a sample of rows from a dataset as JSON.

Authorizations:
BearerAuth
path Parameters
dataset_id
required
integer

Unique identifier for a dataset.

query Parameters
size
integer ( 0 .. 1000 ]

The number of rows to sample from the dataset.

Responses

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Get admin info for a dataset

Get a dataset including information about the backing Iceberg table.

Authorizations:
BearerAuth
path Parameters
dataset_id
required
integer

Unique identifier for a dataset.

Responses

Response samples

Content type
application/json
{
  • "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": {
    },
  • "status": "active",
  • "tags": [
    ],
  • "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": {
    },
  • "table": { }
}

Sample a dataset (Admin)

Get a sample of rows from a dataset as JSON.

Authorizations:
BearerAuth
path Parameters
dataset_id
required
integer

Unique identifier for a dataset.

query Parameters
size
integer ( 0 .. 1000 ]

The number of rows to sample from the dataset.

Responses

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Update a dataset's partition spec

Update the partition specification of the Iceberg table backing the dataset.

See:

Authorizations:
BearerAuth
path Parameters
dataset_id
required
integer

Unique identifier for a dataset.

Request Body schema: application/json
required
Array of PartitionSpecAddField (object) or PartitionSpecRemoveField (object) (PartitionSpecUpdate)

Responses

Request samples

Content type
application/json
{
  • "updates": [
    ]
}

Response samples

Content type
application/json
{
  • "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": {
    },
  • "status": "active",
  • "tags": [
    ],
  • "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": {
    },
  • "table": { }
}

Preview snapshot expirations

Preview snapshot expirations given a retention policy.

Authorizations:
BearerAuth
path Parameters
dataset_id
required
integer

Unique identifier for a dataset.

Request Body schema: application/json
One of
type
string
Value: "expire_everything"

Responses

Request samples

Content type
application/json
Example
{
  • "type": "expire_everything"
}

Response samples

Content type
application/json
{
  • "snapshots_to_expire": [
    ]
}

Update snapshot retention policy

Updates snapshot retention policy

Authorizations:
BearerAuth
path Parameters
dataset_id
required
integer

Unique identifier for a dataset.

Request Body schema: application/json
One of
type
string
Value: "expire_everything"

Responses

Request samples

Content type
application/json
Example
{
  • "type": "expire_everything"
}

Response samples

Content type
application/json
{
  • "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": {
    },
  • "status": "active",
  • "tags": [
    ],
  • "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": {
    }
}

Sampled Mappings

Returns sampled dataset after attribute mapping for a given mapping_id

This endpoint should be used when mapping exist.

A response is a list of JSON objects, where every object will have an input field, that represents the original key/value pairs from the dataset, and the output filed that will contain mapped fields where the key will be attribute name, and value will be JSON object of key/value pairs.

Authorizations:
BearerAuth
path Parameters
dataset_id
required
integer

Unique identifier for a dataset.

query Parameters
size
integer ( 0 .. 1000 ]

The number of rows to sample from the dataset.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Get dataset statistics

Return summary statistics for all ingestion snapshots for a given dataset. For datasets with "incremental" updates, each snapshot defines a new incremental upload of data. For datasets with "overwrite" updates, each snapshot overwrites the previous data. all_records query parameter is here because of backward compatibility. By default API is paginated, so if you don't provide both per_page and offset parameters, you will get only the latest summary.

Authorizations:
BearerAuth
path Parameters
dataset_id
required
integer

Unique identifier for a dataset.

query Parameters
all_records
boolean

If true will return 100 records. If false, only returns the most recent record. Pagination api with per_page and offset parameters should be used instead of this one.

per_page
integer

Number of records to return.

offset
integer

Number of records to skip (it's usually page_number * per_page).

Responses

Response samples

Content type
application/json
{
  • "dataset_id": 1,
  • "records": [
    ]
}

Get detailed statistics

Get statistics for each column.

Authorizations:
BearerAuth
path Parameters
dataset_id
required
integer

Unique identifier for a dataset.

query Parameters
histogram_bin_limit
integer > 0

The maximum number of bins to return for the histograms.

Responses

Response samples

Content type
application/json
{
  • "advanced_statistics_metadata": {
    },
  • "columns_summary": [
    ]
}

Create or Update detailed statistics

Create or Update detailed statistics. Detailed statistics are collected for datasets belonging to the Narrative Data Plane, but uploading these stats is necessary for non-Narrative data planes, since Narrative does not have access to the data to compute these statistics.

Authorizations:
BearerAuth
Request Body schema: application/json
Array of objects

Responses

Request samples

Content type
application/json
{
  • "records": [
    ]
}

Response samples

Content type
application/json
{
  • "error": "Unauthorized",
  • "error_description": "You are not authorized to use this endpoint."
}

Submit recalculation

Run recalculation for the dataset.

Authorizations:
BearerAuth
path Parameters
dataset_id
required
integer

Unique identifier for a dataset.

Request Body schema: application/json
from_snapshot
string

Start of the recalculation range

Responses

Request samples

Content type
application/json
{
  • "from_snapshot": "string"
}

Response samples

Content type
application/json
{
  • "recalculation_id": "a81e1460-fbdc-4204-bd76-a9e496bf760d",
  • "snapshots": [
    ],
  • "from_snapshot_timestamp": "2023-06-28T19:47:36.604706Z",
  • "until_snapshot_timestamp": "2023-06-28T19:47:36.604709Z"
}

Ingest a file

After uploading a file to Narrative via the upload API, you can then have the file can then be ingested into a dataset.

Related guides:

Authorizations:
BearerAuth
path Parameters
dataset_id
required
integer

Unique identifier for a dataset.

Request Body schema: application/json
source_file
required
string

The file to be ingested.

This must be equal to the upload_path passed to the upload API when the file was submitted to Narrative.

Responses

Request samples

Content type
application/json
{
  • "source_file": "/2021-12-01/example.csv"
}

Files added

Lists files added by a snapshot

Authorizations:
BearerAuth
path Parameters
dataset_id
required
integer

Unique identifier for a dataset.

snapshot_id
required
integer

Unique identifier for a snapshot.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Find snapshots

Lists snapshots and associated files

Authorizations:
BearerAuth
path Parameters
dataset_id
required
integer

Unique identifier for a dataset.

query Parameters
per_page
integer

Number of records to return.

offset
integer

Number of records to skip (it's usually page_number * per_page).

timestamp.gte
string
Example: timestamp.gte=2021-06-24T00:54:40

ISO-8601 timestamp that will be inclusively used as minimal timestamp of a snapshot.

timestamp.lt
string
Example: timestamp.lt=2021-06-24T00:54:40

ISO-8601 timestamp that will be exclusively used as maximal timestamp of a snapshot.

timestamp.lte
string
Example: timestamp.lte=2021-06-24T00:54:40

ISO-8601 timestamp that will be inclusively used as maximal timestamp of a snapshot.

from_snapshot_id
number
Example: from_snapshot_id=12345989746723134

Snapshot Id that will be inclusively used as the beginning of snapshot search range. That snapshot should exist.

until_snapshot_id
number
Example: until_snapshot_id=12345989746723134

Snapshot Id that will be exclusively used as the end of snapshot search range. That snapshot should exist.

to_snapshot_id
number
Example: to_snapshot_id=12345989746723134

Snapshot Id that will be inclusively used as the end of snapshot search range. That snapshot should exist.

Responses

Response samples

Content type
application/json
{
  • "snapshots": [
    ],
  • "has_next": true,
  • "next_snapshot": 0
}

Metrics

Lists metrics for a dataset

Authorizations:
BearerAuth
path Parameters
dataset_id
required
integer

Unique identifier for a dataset.

Responses

Response samples

Content type
application/json
{
  • "value": [
    ]
}

Metrics

Metrics for a snapshot

Authorizations:
BearerAuth
path Parameters
dataset_id
required
integer

Unique identifier for a dataset.

snapshot_id
required
integer

Unique identifier for a snapshot.

Responses

Response samples

Content type
application/json
{
  • "value": [
    ]
}

Put Metrics Configuration

Put new version of configuration.

Authorizations:
BearerAuth
path Parameters
dataset_id
required
integer

Unique identifier for a dataset.

Request Body schema: application/json
object (Columns)
object (Columns)
object (Columns)
object (Columns)
object (Columns)
object (Columns)
object (Columns)

Responses

Request samples

Content type
application/json
{
  • "value_histogram": {
    },
  • "completeness": {
    },
  • "approx_count_distinct": {
    },
  • "count_distinct": {
    },
  • "observed_types_histogram": {
    },
  • "mean": {
    },
  • "deviation": {
    }
}

Response samples

Content type
application/json
{
  • "stream_id": "173fd1b7-72c4-44c4-9244-55a0a167a352",
  • "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c"
}

Disable configuration

Disable configuration, metrics won't be calculated

Authorizations:
BearerAuth
path Parameters
dataset_id
required
integer

Unique identifier for a dataset.

Responses

Response samples

Content type
application/json
{
  • "stream_id": "173fd1b7-72c4-44c4-9244-55a0a167a352"
}

Get Metrics Configuration

Put new version of configuration.

Authorizations:
BearerAuth
path Parameters
dataset_id
required
integer

Unique identifier for a dataset.

Responses

Response samples

Content type
application/json
{
  • "value_histogram": {
    },
  • "completeness": {
    },
  • "approx_count_distinct": {
    },
  • "count_distinct": {
    },
  • "observed_types_histogram": {
    },
  • "mean": {
    },
  • "deviation": {
    },
  • "version": 0,
  • "disabled": true
}

Derive the configuration

Creates new request for request derivation

Authorizations:
BearerAuth
path Parameters
dataset_id
required
integer

Unique identifier for a dataset.

Responses

Enable configuration

Enable configuration if it exists

Authorizations:
BearerAuth
path Parameters
dataset_id
required
integer

Unique identifier for a dataset.

Responses

Response samples

Content type
application/json
{
  • "stream_id": "173fd1b7-72c4-44c4-9244-55a0a167a352"
}

Find files

Lists snapshots and associated files

Authorizations:
BearerAuth
path Parameters
dataset_id
required
integer

Unique identifier for a dataset.

query Parameters
per_page
integer

Number of records to return.

offset
integer

Number of records to skip (it's usually page_number * per_page).

timestamp.gte
string
Example: timestamp.gte=2021-06-24T00:54:40

ISO-8601 timestamp that will be inclusively used as minimal timestamp of a snapshot.

from_snapshot_id
number
Example: from_snapshot_id=12345989746723134

Snapshot Id that will be inclusively used as the beginning of snapshot search range. That snapshot should exist.

Responses

Response samples

Content type
application/json
{
  • "files_per_snapshot": [
    ],
  • "has_next": true,
  • "next_snapshot": 0
}

Issue file download url

Retrieve the download URL for a file

Authorizations:
BearerAuth
path Parameters
dataset_id
required
integer

Unique identifier for a dataset.

snapshot_id
required
integer

Unique identifier for a snapshot.

file_id
required
string

Unique identifier for a file.

Responses

Update the materialized view refresh configuration

Creates new request for request derivation

Authorizations:
BearerAuth
path Parameters
dataset_id
required
integer

Unique identifier for a dataset.

Request Body schema: application/json
cron
string

cron expression "for example: @hourly, 0 12 * * 1-5"

cronZoneId
string

zone id where the cron should take place "for example: EST, GMT+2"

object (Budget)

The maximum amount that can be spent as part of a subscription in a given time period. Once the budget has been exhausted in a given time period no more data is transacted until the start of the next one.

E.g. with a budget of $100 USD and a period of calendar_monthly you're guaranteed that you will not be charged more than $100 for your subscription in a given month.

statsEnabled
boolean

if we need to enable advanced statistics calculation

status
string
Enum: "active" "pending" "archived"

active will be ran on cron schedule, pending and archived won't be run

Responses

Request samples

Content type
application/json
{
  • "cron": "@hourly",
  • "cronZoneId": "EST",
  • "statsEnabled": false,
  • "status": "active"
}

Destinations

Destinations associate a subscription to a profile. Optionally, ad-hoc quick settings can be configured to a destination. Those quick settings have to match the format defined on the app manifest.

Creates a destination

Authorizations:
BearerAuth
Request Body schema: application/json
subscription_id
string <uuid> (UUID)
profile_id
string <uuid> (UUID)
quick_settings
object

Responses

Request samples

Content type
application/json
{
  • "subscription_id": "21691f26-f308-4e98-896c-579db27da04b",
  • "profile_id": "d13867f7-a6c0-4f83-b129-f6c6f2de7c15",
  • "quick_settings": {
    }
}

Response samples

Content type
application/json
{
  • "id": "8aaa069b-cc15-486f-9cdc-c56c3d831508",
  • "subscription_id": "21691f26-f308-4e98-896c-579db27da04b",
  • "profile_id": "d13867f7-a6c0-4f83-b129-f6c6f2de7c15",
  • "quick_settings": {
    }
}

Get a destination by id

Authorizations:
BearerAuth
path Parameters
destination_id
required
string <uuid>

Unique identifier for a destination.

Responses

Response samples

Content type
application/json
{
  • "id": "8aaa069b-cc15-486f-9cdc-c56c3d831508",
  • "subscription_id": "21691f26-f308-4e98-896c-579db27da04b",
  • "profile_id": "d13867f7-a6c0-4f83-b129-f6c6f2de7c15",
  • "quick_settings": {
    }
}

Updates the values of the quick settings

Authorizations:
BearerAuth
path Parameters
destination_id
required
string <uuid>

Unique identifier for a destination.

Request Body schema: application/json
object (QuickSettings)

Responses

Request samples

Content type
application/json
{
  • "bucket_suffix": "/my-subscription",
  • "number_of_files": "5"
}

Response samples

Content type
application/json
{
  • "id": "8aaa069b-cc15-486f-9cdc-c56c3d831508",
  • "subscription_id": "21691f26-f308-4e98-896c-579db27da04b",
  • "profile_id": "d13867f7-a6c0-4f83-b129-f6c6f2de7c15",
  • "quick_settings": {
    }
}

Removes the destination from a subscription

Authorizations:
BearerAuth
path Parameters
destination_id
required
string <uuid>

Unique identifier for a destination.

Responses

Search destinations for a subscription

Authorizations:
BearerAuth
path Parameters
subscription_id
required
string <uuid>

Unique identifier for a subscription.

Responses

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Search destinations for a profile

Authorizations:
BearerAuth
path Parameters
profile_id
required
string <uuid>

Unique identifier for an app profile.

Responses

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Installations

Lists all installations

Tests whether the whole stack is setup.

Authorizations:
BearerAuth
query Parameters
app_category
Array of strings
Items Value: "destination_connector"

A filter for app categories.

Responses

Jobs

Jobs represent an operation done on a given data plane. All jobs today are tied to a query that represents a forecast or a materialized view.

The jobs API provides an interface for interacting with the jobs table, which stores various operations involving reading or writing data. This API allows users to retrieve detailed information about specific jobs, including cost forecasts, data forecasts, NQL forecasts and materialized views.

Get jobs

Returns a list of jobs associated with the specified company, including job ID, job type, timestamp information, and results.

It returns a maximum of 500 jobs at a time to manage response size.

Authorizations:
BearerAuth
query Parameters
per_page
integer

Number of records to return.

offset
integer

Number of records to skip (page_number * per_page).

dataset_id
integer

Filter jobs where the input has a dataset_id (such as materalized-view)

Responses

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Get a job

This endpoint retrieves all details associated with a specific job ID from the jobs table.

Authorizations:
BearerAuth
path Parameters
job_id
required
string

Unique identifier for a job.

Responses

Response samples

Content type
application/json
{
  • "job_id": "2a5b9ad7-dc8f-47bb-8e62-843a38f8054c",
  • "request_source": {
    },
  • "state": "completed",
  • "type": "materialize-view",
  • "input": {
    },
  • "executor": "job-executor-98e1f48e-bf54-4f11-bbd1-73c445120266",
  • "idempotency_key": "10736:29329c64e7b8a4eda86aaabe04872b832ab456b5543d0c259c812525391f158c:669a5f8e4f373c2f907700decde47511aac6470f5698e2b856fb07f09160e5f2",
  • "result": {
    },
  • "created_at": "2023-10-31T11:19:13.400498",
  • "updated_at": "2023-10-31T11:25:08.327209",
  • "ended_at": "2023-10-31T11:25:08.327194"
}

Mappings

A mapping is a transformation from a dataset to an attribute. Defining a mapping between a dataset and an attribute makes the dataset eligible to participate in subscriptions where a buyer is purchasing the target attribute.

Get mappings

Return all mappings, both private and global.

Authorizations:
BearerAuth
query Parameters
attribute_id
Array of integers

Attribute identifier. Can be specified multiple times to retrieve mappings for multiple attributes.

dataset_id
Array of integers

Dataset identifier. Can be specified multiple times to retrieve mappings for multiple datasets.

Responses

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Create a global mapping

Create a new global mapping.

Only admins can use this endpoint.

Authorizations:
BearerAuth
Request Body schema: application/json
attribute_id
integer

The target attribute's ID.

dataset_id
integer

The source dataset's ID.

ObjectMapping (object) or ValueMapping (object) (MappingDefinition)

Responses

Request samples

Content type
application/json
{
  • "attribute_id": 123,
  • "dataset_id": 456,
  • "mapping": {
    }
}

Response samples

Content type
application/json
{
  • "id": "ea9dddd2-e3ee-40b5-b03e-c3cd37c8a7f0",
  • "attribute_id": 1,
  • "created_at": "2021-12-10T00:00:00Z",
  • "dataset_id": 3,
  • "mapping": {
    },
  • "status": "active",
  • "updated_at": "2021-12-10T00:00:01Z",
  • "created_by": 1,
  • "updated_by": 1,
  • "company_id": 100,
  • "scope": "global",
  • "source": "admin",
  • "derived_from": "ea9dddd2-e3ee-40b5-b03e-c3cd37c8a6f0"
}

Get system mappings

Return all system mappings.

Only admins can call this endpoint.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Create a system mapping

Create a system mapping.

Only admins can call this endpoint.

Authorizations:
BearerAuth
Request Body schema: application/json
attribute_id
integer

The target attribute's ID.

dataset_id
integer

The source dataset's ID.

ObjectMapping (object) or ValueMapping (object) (MappingDefinition)

Responses

Request samples

Content type
application/json
{
  • "attribute_id": 123,
  • "dataset_id": 456,
  • "mapping": {
    }
}

Response samples

Content type
application/json
{
  • "id": "ea9dddd2-e3ee-40b5-b03e-c3cd37c8a7f0",
  • "attribute_id": 1,
  • "created_at": "2021-12-10T00:00:00Z",
  • "dataset_id": 3,
  • "mapping": {
    },
  • "status": "active",
  • "updated_at": "2021-12-10T00:00:01Z",
  • "created_by": 1,
  • "updated_by": 1,
  • "company_id": 100,
  • "scope": "global",
  • "source": "admin",
  • "derived_from": "ea9dddd2-e3ee-40b5-b03e-c3cd37c8a6f0"
}

Get mapping

Return a specific mapping based on its id.

Authorizations:
BearerAuth
path Parameters
mapping_id
required
string <uuid>
Example: ea9dddd2-e3ee-40b5-b03e-c3cd37c8a6f0

Unique identifier for a mapping.

Responses

Response samples

Content type
application/json
{
  • "id": "ea9dddd2-e3ee-40b5-b03e-c3cd37c8a7f0",
  • "attribute_id": 1,
  • "created_at": "2021-12-10T00:00:00Z",
  • "dataset_id": 3,
  • "mapping": {
    },
  • "status": "active",
  • "updated_at": "2021-12-10T00:00:01Z",
  • "created_by": 1,
  • "updated_by": 1,
  • "company_id": 100,
  • "scope": "global",
  • "source": "admin",
  • "derived_from": "ea9dddd2-e3ee-40b5-b03e-c3cd37c8a6f0"
}

Update a mapping

Update the definition of a mapping between an attribute and a dataset.

Note: the attribute and dataset with which a mapping is associated cannot be updated.

Authorizations:
BearerAuth
path Parameters
mapping_id
required
string <uuid>
Example: ea9dddd2-e3ee-40b5-b03e-c3cd37c8a6f0

Unique identifier for a mapping.

Request Body schema: application/json
ObjectMapping (object) or ValueMapping (object) (MappingDefinition)

Responses

Request samples

Content type
application/json
{
  • "mapping": {
    }
}

Response samples

Content type
application/json
{
  • "id": "ea9dddd2-e3ee-40b5-b03e-c3cd37c8a7f0",
  • "attribute_id": 1,
  • "created_at": "2021-12-10T00:00:00Z",
  • "dataset_id": 3,
  • "mapping": {
    },
  • "status": "active",
  • "updated_at": "2021-12-10T00:00:01Z",
  • "created_by": 1,
  • "updated_by": 1,
  • "company_id": 100,
  • "scope": "global",
  • "source": "admin",
  • "derived_from": "ea9dddd2-e3ee-40b5-b03e-c3cd37c8a6f0"
}

Delete a mapping

Mapping deletion cannot be undone.

If the mapping is still being used then this request fails.

Both owners (users belonging to the company the mapping belongs to) and admins can delete a mapping.

Authorizations:
BearerAuth
path Parameters
mapping_id
required
string <uuid>
Example: ea9dddd2-e3ee-40b5-b03e-c3cd37c8a6f0

Unique identifier for a mapping.

Responses

Accept a mapping

Accept a system proposed mapping, i.e. move it from the status of pending to active.

The mapping has to be system proposed and not archived.

Both owners (users belonging to the company the mapping belongs to) and admins can promote a mapping.

Authorizations:
BearerAuth
path Parameters
mapping_id
required
string <uuid>
Example: ea9dddd2-e3ee-40b5-b03e-c3cd37c8a6f0

Unique identifier for a mapping.

Responses

Response samples

Content type
application/json
{
  • "id": "ea9dddd2-e3ee-40b5-b03e-c3cd37c8a7f0",
  • "attribute_id": 1,
  • "created_at": "2021-12-10T00:00:00Z",
  • "dataset_id": 3,
  • "mapping": {
    },
  • "status": "active",
  • "updated_at": "2021-12-10T00:00:01Z",
  • "created_by": 1,
  • "updated_by": 1,
  • "company_id": 100,
  • "scope": "global",
  • "source": "admin",
  • "derived_from": "ea9dddd2-e3ee-40b5-b03e-c3cd37c8a6f0"
}

Promote a mapping

Promote a private mapping, i.e. create a new mapping taht is available globally.

A new mapping is created that is a copy of the source mapping, with its scope set to global. This new mapping has its derived_from property set to the id of its source mapping.

The original mapping is left untouched.

The mapping has to be private and not archived.

Only admins can promote a mapping.

Authorizations:
BearerAuth
path Parameters
mapping_id
required
string <uuid>
Example: ea9dddd2-e3ee-40b5-b03e-c3cd37c8a6f0

Unique identifier for a mapping.

Responses

Response samples

Content type
application/json
{
  • "id": "ea9dddd2-e3ee-40b5-b03e-c3cd37c8a7f0",
  • "attribute_id": 1,
  • "created_at": "2021-12-10T00:00:00Z",
  • "dataset_id": 3,
  • "mapping": {
    },
  • "status": "active",
  • "updated_at": "2021-12-10T00:00:01Z",
  • "created_by": 1,
  • "updated_by": 1,
  • "company_id": 100,
  • "scope": "global",
  • "source": "admin",
  • "derived_from": "ea9dddd2-e3ee-40b5-b03e-c3cd37c8a6f0"
}

Get mappings for a company

Return all private mappings related to a specific company based on its id

Authorizations:
BearerAuth
path Parameters
company_id
required
integer

Unique identifier for a company

Responses

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Create a private mapping

Create a private mapping.

Authorizations:
BearerAuth
path Parameters
company_id
required
integer

Unique identifier for a company

Request Body schema: application/json
attribute_id
integer

The target attribute's ID.

dataset_id
integer

The source dataset's ID.

ObjectMapping (object) or ValueMapping (object) (MappingDefinition)

Responses

Request samples

Content type
application/json
{
  • "attribute_id": 123,
  • "dataset_id": 456,
  • "mapping": {
    }
}

Response samples

Content type
application/json
{
  • "id": "ea9dddd2-e3ee-40b5-b03e-c3cd37c8a7f0",
  • "attribute_id": 1,
  • "created_at": "2021-12-10T00:00:00Z",
  • "dataset_id": 3,
  • "mapping": {
    },
  • "status": "active",
  • "updated_at": "2021-12-10T00:00:01Z",
  • "created_by": 1,
  • "updated_by": 1,
  • "company_id": 100,
  • "scope": "global",
  • "source": "admin",
  • "derived_from": "ea9dddd2-e3ee-40b5-b03e-c3cd37c8a6f0"
}

Get mapping preview

Returns sampled dataset after attribute mapping for a given mapping_id

This endpoint should be used when mapping exist.

A response is a list of JSON objects, where every object will have an input field, that represents the original key/value pairs from the dataset, and the output filed that will contain mapped fields where the key will be attribute name, and value will be JSON object of key/value pairs.

Authorizations:
BearerAuth
path Parameters
mapping_id
required
string <uuid>
Example: ea9dddd2-e3ee-40b5-b03e-c3cd37c8a6f0

Unique identifier for a mapping.

query Parameters
size
integer ( 0 .. 1000 ]

The number of rows to sample from the dataset.

Responses

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Test Mapping

Returns sampled dataset after attribute mapping for a given mapping.

This endpoint should be used when mapping does not exist.

A response is a list of JSON objects, where every object will have an input field, that represents the original key/value pairs from the dataset, and the output filed that will contain mapped fields where the key will be attribute name, and value will be JSON object of key/value pairs.

Authorizations:
BearerAuth
query Parameters
size
integer ( 0 .. 1000 ]

The number of rows to sample from the dataset.

Request Body schema: application/json
attribute_id
integer

The target attribute's ID.

dataset_id
integer

The source dataset's ID.

ObjectMapping (object) or ValueMapping (object) (MappingDefinition)

Responses

Request samples

Content type
application/json
{
  • "attribute_id": 123,
  • "dataset_id": 456,
  • "mapping": {
    }
}

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Payment Methods

Returns payment methods for company

/payment-methods

Returns payment methods for company

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "companyId": 0,
  • "paymentMethodId": "string",
  • "cardBrand": "string",
  • "cardLast4": "string"
}

Deletes a payment method

/payment-methods/{payment_method_id}

Deletes a payment method

Authorizations:
BearerAuth
path Parameters
payment_method_id
required
string

Payment method id

Responses

Creates a new setup intent

/payment-methods/credit-card/setup-intent

Creates a new setup intent

Authorizations:
BearerAuth

Responses

Sets a valid SetupIntent as the primary payment method

/payment-methods/credit-card/setup-intent/{setup_intent_id}

Sets a valid SetupIntent as the primary payment method

Authorizations:
BearerAuth
path Parameters
setup_intent_id
required
string

Setup Intent ID

Responses

Products

Get products

Get products paginated

Authorizations:
BearerAuth
query Parameters
per_page
integer

Number of records to return.

offset
integer

Number of records to skip (it's usually page_number * per_page).

Responses

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Create a product

Create a new product.

Authorizations:
BearerAuth
Request Body schema: application/json
sku
required
string

SKU for product

required
object (SkuType)

Sku Type (json object, category filed is mandatory)

payable_company_id
required
number

Payable company id

name
required
string

Product name

description
string

Optional description of a product

object (CloudPlatform)

Cloud Platform (json object)

unit
required
string
required
object (Rate)

Product rate

status
required
string (ProductStatus)
Enum: "active" "archived"

Responses

Request samples

Content type
application/json
{
  • "sku": "general-storage",
  • "sku_type": {
    },
  • "payable_company_id": 1,
  • "name": "name",
  • "cloud_platform": {
    },
  • "unit": "bytes",
  • "default_rate": {
    },
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "id": "cd98bbb6-1086-4aea-9b5f-8ba39671a659",
  • "sku": "general-storage",
  • "sku_type": {
    },
  • "payable_company_id": 1,
  • "name": "name",
  • "cloud_platform": {
    },
  • "unit": "bytes",
  • "default_rate": {
    },
  • "status": "active",
  • "created_at": "2023-02-13T12:55:24.104Z",
  • "created_by_user_id": 1,
  • "updated_at": "2023-02-13T12:55:24.104Z",
  • "updated_by_user_id": 1
}

Get product

Return single product

Authorizations:
BearerAuth
path Parameters
sku
required
string
Example: general-purpose-processing-aws-us-east-1

Unique identifier for a product.

Responses

Response samples

Content type
application/json
{
  • "id": "cd98bbb6-1086-4aea-9b5f-8ba39671a659",
  • "sku": "general-storage",
  • "sku_type": {
    },
  • "payable_company_id": 1,
  • "name": "name",
  • "cloud_platform": {
    },
  • "unit": "bytes",
  • "default_rate": {
    },
  • "status": "active",
  • "created_at": "2023-02-13T12:55:24.104Z",
  • "created_by_user_id": 1,
  • "updated_at": "2023-02-13T12:55:24.104Z",
  • "updated_by_user_id": 1
}

Update product

Update product by sku.

Authorizations:
BearerAuth
path Parameters
sku
required
string
Example: general-purpose-processing-aws-us-east-1

Unique identifier for a product.

Request Body schema: application/json
name
string

Product name

description
string

Optional description of a product

object (CloudPlatform)

Cloud Platform (json object)

object (Rate)

Product rate

status
string (ProductStatus)
Enum: "active" "archived"
unit
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "cloud_platform": {
    },
  • "default_rate": {
    },
  • "status": "active",
  • "unit": "string"
}

Response samples

Content type
application/json
{
  • "id": "cd98bbb6-1086-4aea-9b5f-8ba39671a659",
  • "sku": "general-storage",
  • "sku_type": {
    },
  • "payable_company_id": 1,
  • "name": "name",
  • "cloud_platform": {
    },
  • "unit": "bytes",
  • "default_rate": {
    },
  • "status": "active",
  • "created_at": "2023-02-13T12:55:24.104Z",
  • "created_by_user_id": 1,
  • "updated_at": "2023-02-13T12:55:24.104Z",
  • "updated_by_user_id": 1
}

Attach permission to product

Attaches given permission to a given product

Authorizations:
BearerAuth
Request Body schema: application/json
product_id
required
string <uuid> (Product_UUID)

UUID

permission_id
required
string <uuid> (Product_UUID)

UUID

Responses

Request samples

Content type
application/json
{
  • "product_id": "0d012afa-f885-4e65-aeca-37e27701e2d1",
  • "permission_id": "2793a5a1-5444-40bb-8094-97de834ce9e4"
}

Response samples

Content type
application/json
{
  • "error": "Unauthorized",
  • "error_description": "You are not authorized to use this endpoint."
}

Profiles

App profiles are associated with an installation. They represent a reference to a configuration that the app can use to save confidential information outside of Narrative's control. Profiles are currently used to configure settings for connector apps.

Returns app profiles

Authorizations:
BearerAuth
path Parameters
installation_id
required
string <uuid>

The installation ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Creates an app profile

The profile will be assigned a unique identifier upon creation. New profiles are "disabled" and should be activated after creation.

Authorizations:
BearerAuth
path Parameters
installation_id
required
string <uuid>

The installation ID

Request Body schema: application/json
name
string
description
string

Responses

Request samples

Content type
application/json
{
  • "name": "My profile name",
  • "description": "My profile description"
}

Response samples

Content type
application/json
{
  • "id": "7bc22af4-fb6e-431e-92bc-e366e4f960ff",
  • "name": "My profile name",
  • "description": "My profile description",
  • "status": "disabled"
}

Returns profile with {profile_id}

Authorizations:
BearerAuth
path Parameters
app_profile_id
required
string <uuid>

The profile ID

installation_id
required
string <uuid>

The installation ID

Responses

Response samples

Content type
application/json
{
  • "id": "7bc22af4-fb6e-431e-92bc-e366e4f960ff",
  • "name": "My profile name",
  • "description": "My profile description",
  • "status": "disabled"
}

Updates an existing app profile

Authorizations:
BearerAuth
path Parameters
app_profile_id
required
string <uuid>

The profile ID

installation_id
required
string <uuid>

The installation ID

Request Body schema: application/json

Profile creation payload

name
string
description
string

Responses

Request samples

Content type
application/json
{
  • "description": "My profile description"
}

Response samples

Content type
application/json
{
  • "id": "7bc22af4-fb6e-431e-92bc-e366e4f960ff",
  • "name": "My profile name",
  • "description": "My profile description",
  • "status": "disabled"
}

Enables a profile

Only profiles that are enabled will be considered when delivering subscriptions.

Authorizations:
BearerAuth
path Parameters
app_profile_id
required
string <uuid>

The profile ID

installation_id
required
string <uuid>

The installation ID

Responses

Response samples

Content type
application/json
{
  • "id": "7bc22af4-fb6e-431e-92bc-e366e4f960ff",
  • "name": "My profile name",
  • "description": "My profile description",
  • "status": "disabled"
}

Disables a profile

Only profiles that are enabled will be considered when delivering subscriptions.

Authorizations:
BearerAuth
path Parameters
app_profile_id
required
string <uuid>

The profile ID

installation_id
required
string <uuid>

The installation ID

Responses

Response samples

Content type
application/json
{
  • "id": "7bc22af4-fb6e-431e-92bc-e366e4f960ff",
  • "name": "My profile name",
  • "description": "My profile description",
  • "status": "disabled"
}

Archives a profile

Archiving prevents using the profile again in the future.

Authorizations:
BearerAuth
path Parameters
app_profile_id
required
string <uuid>

The profile ID

installation_id
required
string <uuid>

The installation ID

Responses

Response samples

Content type
application/json
{
  • "id": "7bc22af4-fb6e-431e-92bc-e366e4f960ff",
  • "name": "My profile name",
  • "description": "My profile description",
  • "status": "disabled"
}

Resources

Narrative gives you access to managed resources, like your own AWS S3 bucket, so that you can effortlessly buy and sell data on the platform.

The resources API allows you to manage your resources.

Get buckets

Return the AWS S3 buckets assigned to the authenticated company.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Create bucket

Create an AWS S3 bucket inside Narrative's AWS account assigned to the authenticated company.

The created bucket is uniquely accessible by the authenticated company and can be used to facilitate the automation of tasks like ingestion of data into a dataset.

Pay attention, that bucket-owner-full-control ACL is strictly required for "bucket_policy" type of access.

Authorizations:
BearerAuth
Request Body schema: application/json
account_id
required
string

Your 12 digit AWS account ID. That ID will be used:

  • to enable root-based access in case of "bucket_policy" access type;
  • to create (or use existing) IAM Role that will be available for specified user.
resource_id
required
string

A short identifier that will be a part of your bucket's name.

A typical choice would be your company's name, lowercased and spaces replaced with -.

Resource IDs must:

  • consist of only lowercase alphanumeric characters or -
  • be at least 2 and less than 43 characters long
object

Responses

Request samples

Content type
application/json
{
  • "account_id": 12345678901,
  • "resource_id": "yourcompany",
  • "access": {
    }
}

Response samples

Content type
application/json
{
  • "id": "45b40bf5-02fc-4f18-bfcd-50ac58dabfa1",
  • "company_id": 1,
  • "auth": {
    },
  • "name": "nio-yourcompany-821627dd2931",
  • "created_at": "2021-08-31T20:22:02Z",
  • "updated_at": "2021-08-31T20:22:02Z"
}

Update access type

Update access type to the bucket. Pay attention, that bucket-owner-full-control ACL is strictly required for "bucket_policy" type of access. Also, bucket should be whitelisted for mutation. All buckets created by creation endpoint are mutable by default. Buckets created before 2023 could be immutable in case of customized policies. You can call 'Get buckets' endpoint to check is_access_mutable property in response.

Authorizations:
BearerAuth
Request Body schema: application/json
bucket_name
string

Full name of the bucket that should be affected.

BucketPolicyAccessTypeRequest (object) or RoleAccessTypeRequest (object)

Responses

Request samples

Content type
application/json
{
  • "bucket_name": "nio-yourcompany-iwhhrql8sgvp",
  • "new_access": {
    }
}

Response samples

Content type
application/json
{
  • "id": "45b40bf5-02fc-4f18-bfcd-50ac58dabfa1",
  • "company_id": 1,
  • "auth": {
    },
  • "name": "nio-yourcompany-821627dd2931",
  • "created_at": "2021-08-31T20:22:02Z",
  • "updated_at": "2021-08-31T20:22:02Z"
}

Schema Inference

The schema-inference API analyzes submitted files to automatically infer and return their structure as a dataset schema.

Infer the dataset schema of a file passed by multipart file.

Request Body schema: multipart/form-data
file
string <binary>

Responses

Response samples

Content type
application/json
{
  • "schema": {
    }
}

Schema Presets

The schema-presets API allows you to list the available schema presets, get detailed information about a specific one and manage its life cycle.

You can create a schema preset from scratch or create one based on an existing one, administrators can create platform wide available (public) schema preset.

Returns all publicly available schema presets.

List the schema presets that are publicly available.

Responses

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Returns all available schema presets.

List the schema presets that are publicly available and the ones owned by the authenticated account.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Create a private schema preset.

Create a private schema preset owned by the authenticated account. Only members of the same organization are able to see this schema preset.

Authorizations:
BearerAuth
Request Body schema: application/json
name
required
string

Name of the schema preset

description
string

Long description for the schema preset

based_on_preset_id
integer <int64> (SchemaPresetId)

Unique identifier of an existing schema preset.

icon
string

URL of an icon shown with the schema preset in the UI to help recognize/personalize it.

display_color
string

Background color to be shown in the UI to personalize the schema preset, in hex color code format.

banner_image
string

URL of the banner image shown in the UI to personalize the schema preset.

tags
required
Array of strings

An array (can be empty) of strings representing metadata about the schema preset

required
object (schemapreset_Details)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "based_on_preset_id": 7,
  • "icon": "string",
  • "display_color": "string",
  • "banner_image": "string",
  • "tags": [
    ],
  • "details": {
    }
}

Response samples

Content type
application/json
{
  • "id": 7,
  • "company_id": 0,
  • "created_at": "string",
  • "archived_at": "string",
  • "name": "string",
  • "description": "string",
  • "scope": "public",
  • "based_on_preset_id": 7,
  • "status": "active",
  • "icon": "string",
  • "display_color": "string",
  • "banner_image": "string",
  • "tags": [
    ],
  • "details": {
    }
}

Detail information on a schema preset by its id.

Returns detailed information on a specific schema preset given its id.

Authorizations:
BearerAuth
path Parameters
schema_preset_id
required
integer <int64>

Unique identifier of an existing schema preset.

Responses

Response samples

Content type
application/json
{
  • "id": 7,
  • "company_id": 0,
  • "created_at": "string",
  • "archived_at": "string",
  • "name": "string",
  • "description": "string",
  • "scope": "public",
  • "based_on_preset_id": 7,
  • "status": "active",
  • "icon": "string",
  • "display_color": "string",
  • "banner_image": "string",
  • "tags": [
    ],
  • "details": {
    }
}

Delete a schema preset by its id.

Archive (soft delete) a specific schema preset given its id. The schema preset will not be visible from that point forward.

Authorizations:
BearerAuth
path Parameters
schema_preset_id
required
integer <int64>

Unique identifier of an existing schema preset.

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "error_description": "string"
}

Create a public schema preset.

Create a public schema preset available platform wide. This endpoint is only available to administrators.

Authorizations:
BearerAuth
Request Body schema: application/json
name
required
string

Name of the schema preset

description
string

Long description for the schema preset

based_on_preset_id
integer <int64> (SchemaPresetId)

Unique identifier of an existing schema preset.

icon
string

URL of an icon shown with the schema preset in the UI to help recognize/personalize it.

display_color
string

Background color to be shown in the UI to personalize the schema preset, in hex color code format.

banner_image
string

URL of the banner image shown in the UI to personalize the schema preset.

tags
required
Array of strings

An array (can be empty) of strings representing metadata about the schema preset

required
object (schemapreset_Details)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "based_on_preset_id": 7,
  • "icon": "string",
  • "display_color": "string",
  • "banner_image": "string",
  • "tags": [
    ],
  • "details": {
    }
}

Response samples

Content type
application/json
{
  • "id": 7,
  • "company_id": 0,
  • "created_at": "string",
  • "archived_at": "string",
  • "name": "string",
  • "description": "string",
  • "scope": "public",
  • "based_on_preset_id": 7,
  • "status": "active",
  • "icon": "string",
  • "display_color": "string",
  • "banner_image": "string",
  • "tags": [
    ],
  • "details": {
    }
}

Subscriptions

In the Narrative Data Collaboration Platform a subscription represents a set of rules dictating the commercial terms related to the licensing of data.

The subscriptions API allows you to set and get information about subscription objects owned by the authenticated account.

Get subscriptions

Return all subscriptions belonging to the authenticated company.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Create a subscription

Subscriptions created using this endpoint are left in the pending state and require activation.

Authorizations:
BearerAuth
Request Body schema: application/json
required
object (Budget)

The maximum amount that can be spent as part of a subscription in a given time period. Once the budget has been exhausted in a given time period no more data is transacted until the start of the next one.

E.g. with a budget of $100 USD and a period of calendar_monthly you're guaranteed that you will not be charged more than $100 for your subscription in a given month.

description
string (Description)

A human-friendly description of the subscription.

required
DataStreamPurchaseDetails (object) or MarketplaceDetails (object) (SubscriptionCreateRequestDetails)
name
required
string (Subscription_Name)

A human-friendly name for the subscription.

cadence
string (Cadence)
Enum: "once" "hourly" "daily" "weekly" "monthly"

The cadence at which the subscription will be executed.

  • once: the subscription will run only once.
  • hourly: the subscription run every hour.
  • daily: the subscription run once per day.
  • weekly: the subscription run once per week.
  • monthly: the subscription run once per month.

Responses

Request samples

Content type
application/json
{
  • "budget": {
    },
  • "description": "the subscription description",
  • "details": {
    },
  • "name": "subscription name",
  • "cadence": "daily"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "budget": {
    },
  • "cancelled_at": "string",
  • "company_id": 0,
  • "created_at": "string",
  • "description": "string",
  • "details": {
    },
  • "name": "string",
  • "output": {
    },
  • "cadence": "once",
  • "status": "active",
  • "updated_at": "string"
}

Get cost forecasts

Return all cost forecasts belonging to the authenticated company.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Create a cost forecast

Create an estimate of the "cost" of servicing a set of subscription constraints.

Cost has two components:

  • The number of rows which must be read in order to find data which matches the subscription constraints.
  • An estimate of the "size" of those rows in bytes.

Note: the number of rows reported in the cost is not an estimate of the number of rows which will be purchased as part of a subscription using the given constraints.

Authorizations:
BearerAuth
Request Body schema: application/json
One of
type
required
string
Value: "data_stream"

Details for the purchase of a data stream.

Hostname (string) or UUID (string) (HostnameOrDataShopId)
data_stream_id
required
string <uuid>

Unique identifier for the data stream being purchased.

offer_id
required
string <uuid>

The provider offer being accepted as part of the purchase.

Responses

Request samples

Content type
application/json
Example
{
  • "type": "data_stream",
  • "data_shop_id": "string",
  • "data_stream_id": "7a4b81a1-fe0b-453f-8554-63b6549f81ba",
  • "offer_id": "d5a7a5b7-a4a3-49e7-9c69-b44d2cbe15cf",
  • "details": {
    }
}

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Get a cost forecast

Get a cost forecast by id.

Authorizations:
BearerAuth
path Parameters
cost_forecast_id
required
string <uuid>

Unique identifier for a cost forecast.

Responses

Response samples

Content type
application/json
{
  • "id": "9cdd4b69-82cb-4454-aedf-197bc3930b44",
  • "company_id": 1,
  • "cost": {
    },
  • "created_at": "2021-11-26T20:20:13.909581Z",
  • "details": {
    },
  • "request_source": {
    },
  • "subscription_id": null
}

Get matches

Retrieve datasets matching a set of subscription constraints.

Authorizations:
BearerAuth
Request Body schema: application/json
One of
type
required
string
Value: "data_stream"

Details for the purchase of a data stream.

Hostname (string) or UUID (string) (HostnameOrDataShopId)
data_stream_id
required
string <uuid>

Unique identifier for the data stream being purchased.

offer_id
required
string <uuid>

The provider offer being accepted as part of the purchase.

Responses

Request samples

Content type
application/json
Example
{
  • "type": "data_stream",
  • "data_shop_id": "string",
  • "data_stream_id": "7a4b81a1-fe0b-453f-8554-63b6549f81ba",
  • "offer_id": "d5a7a5b7-a4a3-49e7-9c69-b44d2cbe15cf",
  • "details": {
    }
}

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Get a subscription

Get a subscription by id.

Authorizations:
BearerAuth
path Parameters
subscription_id
required
string <uuid>

Unique identifier for a subscription.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "budget": {
    },
  • "cancelled_at": "string",
  • "company_id": 0,
  • "created_at": "string",
  • "description": "string",
  • "details": {
    },
  • "name": "string",
  • "output": {
    },
  • "cadence": "once",
  • "status": "active",
  • "updated_at": "string"
}

Update a subscription

Update a subscription

NOTE: If the cadence of the subscription is modified, the frequency filter will automatically be adjusted to match the new cadence.

Authorizations:
BearerAuth
path Parameters
subscription_id
required
string <uuid>

Unique identifier for a subscription.

Request Body schema: application/json
required
object (Budget)

The maximum amount that can be spent as part of a subscription in a given time period. Once the budget has been exhausted in a given time period no more data is transacted until the start of the next one.

E.g. with a budget of $100 USD and a period of calendar_monthly you're guaranteed that you will not be charged more than $100 for your subscription in a given month.

description
string (Description)

A human-friendly description of the subscription.

required
object (MarketplaceDetails)
name
required
string (Subscription_Name)

A human-friendly name for the subscription.

cadence
string (Cadence)
Enum: "once" "hourly" "daily" "weekly" "monthly"

The cadence at which the subscription will be executed.

  • once: the subscription will run only once.
  • hourly: the subscription run every hour.
  • daily: the subscription run once per day.
  • weekly: the subscription run once per week.
  • monthly: the subscription run once per month.

Responses

Request samples

Content type
application/json
{
  • "budget": {
    },
  • "description": "subscription description",
  • "details": {
    },
  • "name": "subscription name",
  • "cadence": "monthly"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "budget": {
    },
  • "cancelled_at": "string",
  • "company_id": 0,
  • "created_at": "string",
  • "description": "string",
  • "details": {
    },
  • "name": "string",
  • "output": {
    },
  • "cadence": "once",
  • "status": "active",
  • "updated_at": "string"
}

Delete a subscription

Subscription deletion cannot be undone.

If a subscription is active it will be cancelled.

Authorizations:
BearerAuth
path Parameters
subscription_id
required
string <uuid>

Unique identifier for a subscription.

Responses

Activate a subscription

Activation will result in charges to your company's payment method.

Authorizations:
BearerAuth
path Parameters
subscription_id
required
string <uuid>

Unique identifier for a subscription.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "budget": {
    },
  • "cancelled_at": "string",
  • "company_id": 0,
  • "created_at": "string",
  • "description": "string",
  • "details": {
    },
  • "name": "string",
  • "output": {
    },
  • "cadence": "once",
  • "status": "active",
  • "updated_at": "string"
}

Cancel a subscription

A cancelled subscription cannot be reactivated.

Authorizations:
BearerAuth
path Parameters
subscription_id
required
string <uuid>

Unique identifier for a subscription.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "budget": {
    },
  • "cancelled_at": "string",
  • "company_id": 0,
  • "created_at": "string",
  • "description": "string",
  • "details": {
    },
  • "name": "string",
  • "output": {
    },
  • "cadence": "once",
  • "status": "active",
  • "updated_at": "string"
}

Checkout a subscription

Checkout creates and activates a subscription in a single API call.

Activation will result in charges to your company's payment method.

Authorizations:
BearerAuth
path Parameters
subscription_id
required
string <uuid>

Unique identifier for a subscription.

Request Body schema: application/json
required
object (Budget)

The maximum amount that can be spent as part of a subscription in a given time period. Once the budget has been exhausted in a given time period no more data is transacted until the start of the next one.

E.g. with a budget of $100 USD and a period of calendar_monthly you're guaranteed that you will not be charged more than $100 for your subscription in a given month.

description
string (Description)

A human-friendly description of the subscription.

required
DataStreamPurchaseDetails (object) or MarketplaceDetails (object) (SubscriptionCreateRequestDetails)
name
required
string (Subscription_Name)

A human-friendly name for the subscription.

cadence
string (Cadence)
Enum: "once" "hourly" "daily" "weekly" "monthly"

The cadence at which the subscription will be executed.

  • once: the subscription will run only once.
  • hourly: the subscription run every hour.
  • daily: the subscription run once per day.
  • weekly: the subscription run once per week.
  • monthly: the subscription run once per month.

Responses

Request samples

Content type
application/json
{
  • "budget": {
    },
  • "description": "the subscription description",
  • "details": {
    },
  • "name": "subscription name",
  • "cadence": "daily"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "budget": {
    },
  • "cancelled_at": "string",
  • "company_id": 0,
  • "created_at": "string",
  • "description": "string",
  • "details": {
    },
  • "name": "string",
  • "output": {
    },
  • "cadence": "once",
  • "status": "active",
  • "updated_at": "string"
}

Get subscription cost forecasts

Retrieve cost forecasts for a subscription.

Authorizations:
BearerAuth
path Parameters
subscription_id
required
string <uuid>

Unique identifier for a subscription.

Responses

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Create a cost forecast for a subscription

Create a cost forecast for a subscription, taking into account data already processed for the subscription.

Authorizations:
BearerAuth
path Parameters
subscription_id
required
string <uuid>

Unique identifier for a subscription.

Responses

Response samples

Content type
application/json
{
  • "id": "9cdd4b69-82cb-4454-aedf-197bc3930b44",
  • "company_id": 1,
  • "cost": {
    },
  • "created_at": "2021-11-26T20:20:13.909581Z",
  • "details": {
    },
  • "request_source": {
    },
  • "subscription_id": null
}

Get deliveries

Retrieve metadata about files containing data purchased as part of the subscription.

Authorizations:
BearerAuth
path Parameters
subscription_id
required
string <uuid>

Unique identifier for a subscription.

Responses

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Get a delivered file

Retrieve a AWS S3 presigned URL to download a file delivered as part of a subscription.

Authorizations:
BearerAuth
path Parameters
subscription_id
required
string <uuid>

Unique identifier for a subscription.

Request Body schema: application/json
transaction_batch_id
required
string <uuid> (TransactionBatchId)

Unique identifier for the subscription fulfillment event which produced the file.

file
required
string

The name of the delivered file to be downloaded.

file_name_override
string

If specified, when the delivery file is download it will have the name specified by file_name_override instead of the default name given by the file parameter.

Responses

Request samples

Content type
application/json
{
  • "transaction_batch_id": "2a2b1c72-dc18-4c07-a558-f7fbf09556f8",
  • "file": "string",
  • "file_name_override": "string"
}

Response samples

Content type
application/json
{
  • "download_url": "string"
}

Get subscription matches

Retrieve datasets matching a subscription's constraints.

Authorizations:
BearerAuth
path Parameters
subscription_id
required
string <uuid>

Unique identifier for a subscription.

Responses

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Get schema

Retrieve schema for deliveries from this subscription.

Authorizations:
BearerAuth
path Parameters
subscription_id
required
string <uuid>

Unique identifier for a subscription.

Responses

Response samples

Content type
application/json
{
  • "value": {
    },
  • "iso_4217_currency": {
    },
  • "tags": {
    }
}

Uploads

The uploads API allows you to send files to Narrative and use them to perform tasks like creating a list or adding data to a dataset.

Upload a file

Sending a file to Narrative is a two step process. This endpoint allows you to request an upload_url which can be used in a PUT request to upload the file.

For example, once you have received an upload_url you could use it as follows:

curl -v --upload-file my-file.csv {upload_url}

The generated upload_url is only valid for 30 minutes after issuance.

Authorizations:
BearerAuth
path Parameters
upload_path
required
string
Example: /lists/idlist.csv

A slash-separated path where the uploaded file should be stored

Responses

Response samples

Content type
application/json
{}

Usage

The usage API enables the recording of usage events associated with a product.

Create a usage event

Create a usage event to charge a customer for their use of a product.

Authorizations:
BearerAuth
Request Body schema: application/json
company_id
required
integer (Usage_CompanyId)

The ID of the company to which the usage will be applied.

created_by
integer (CreatedBy)

Optional. The ID of the user that triggered the usage event.

required
object (Dimensions)

An arbitrary collection of key-value pairs that can be used to categorize or tag the event.

These key-values become aggregable dimensions in usage reports.

event_timestamp
required
string <date-time> (EventTimestamp)

ISO-8601 timestamp indicating when the usage event occurred. Cannot be more than 72 hours in the past.

event_type
required
string (EventType)

The type of usage event. event_type works alongside dimensions and measures to describe the details of the event.

idempotency_key
required
string <uuid> (IdempotencyKey)

A UUID that ensures the usage event is processed and stored only once, even if the event is sent multiple times.

This unique identifier helps to prevent duplicate usage events from being recorded and allows for reliable processing and storage of the event. If a usage event with a previously used idempotency_key is received, the original stored event is returned instead of creating a new event.

object (Measures)

A set of additional numerical values associated with the usage event that are beyond what is captured in the usage field. These values may be used for reporting purposes and can provide additional context about the event.

sku
required
string (Sku)

Unique identifier for the product for .

required
object (Usage)

The amount of the product referred to by the sku that is being used, expressed as a numerical value and corresponding unit of measure.

The unit field must match the unit of measure for the product, and the value field indicates the amount of the product used in terms of the given unit.

Responses

Request samples

Content type
application/json
{
  • "company_id": 1,
  • "created_by": 2,
  • "dimensions": {
    },
  • "event_timestamp": "2022-11-10T00:00:00Z",
  • "event_type": "processing-dataset-ingestion",
  • "idempotency_key": "882e0a91-10a2-47c7-8e70-69344d725a6f",
  • "measures": {
    },
  • "sku": "general-purpose-processing-aws-us-east-1",
  • "usage": {
    }
}

Response samples

Content type
application/json
{
  • "id": "fe0212f6-3440-44e6-b049-ef6c5ad1f396",
  • "app_id": 5,
  • "company_id": 1,
  • "created_at": "2022-11-10T00:00:00Z",
  • "created_by": 2,
  • "dimensions": {
    },
  • "event_timestamp": "2022-11-10T00:00:00Z",
  • "event_type": "processing-dataset-ingestion",
  • "idempotency_key": "882e0a91-10a2-47c7-8e70-69344d725a6f",
  • "measures": {
    },
  • "sku": "general-purpose-processing-aws-us-east-1",
  • "usage": {
    }
}

Company

Get a company

path Parameters
company_id
required
integer <int64>
Example: 345

The id of an existing company

Responses

Response samples

Content type
application/json
{
  • "company_id": 42,
  • "slug": "acm",
  • "name": "ACM",
  • "long_description": "The Acme Corporation is an ironic name for the fictional corporation, appearing in the Road Runner/Wile E. Coyote animated shorts, where it was used as a running gag.",
  • "short_description": "American Company that Manufactures Everything",
  • "contact_email": "[email protected]",
  • "data_shop_url": "https://shop.acm.io",
  • "twitter_link": "https://twitter.com/acm_company",
  • "linkedin_link": "https://www.linkedin.com/company/acm_company",
  • "image_url": null,
  • "visibility": "visible",
  • "status": "active",
  • "website": null
}

Get a company

Authorizations:
BearerAuth
path Parameters
company_id
required
integer <int64>
Example: 345

The id of an existing company

Responses

Response samples

Content type
application/json
{
  • "company_id": 42,
  • "name": "ACM",
  • "slug": "acm",
  • "long_description": "The Acme Corporation is an ironic name for the fictional corporation, appearing in the Road Runner/Wile E. Coyote animated shorts, where it was used as a running gag.",
  • "short_description": "American Company that Manufactures Everything",
  • "contact_email": "[email protected]",
  • "twitter_link": "https://twitter.com/acm_company",
  • "linkedin_link": "https://www.linkedin.com/company/acm_company",
  • "image_url": null,
  • "visibility": "visible",
  • "status": "active",
  • "website": null,
  • "created_at": "2016-06-09T02:00:47Z",
  • "created_by": "[email protected]",
  • "last_updated_at": "2023-08-17T16:18:10.386058Z",
  • "last_updated_by": "[email protected]"
}

Delete (archive) a company

Authorizations:
BearerAuth
path Parameters
company_id
required
integer <int64>
Example: 345

The id of an existing company

Responses

Update a company

Update the company. Please note that "slug" could be changed only once (from null to some value). Lack of slug (in the request) considered as change to null and passes validation if current value is null too. Status can be changed from pending to active but not in the opposite direction.

Authorizations:
BearerAuth
path Parameters
company_id
required
integer <int64>
Example: 345

The id of an existing company

Request Body schema: application/json
company_id
integer (company-info_CompanyId)

Unique identifier of an existing company.

name
string

Name of the company

slug
string

Name of the company

short_description
string

A short description of the company

long_description
string

The complete description of the company

image_url
string

The url of the logo of the company

location
string

The geographical location of the company

size
string

The number of employees

website
string

The url of the website of the company

contact_email
string

Email contact

twitter_link
string

Twitter account

linkedin_link
string

LinkedIn account

visibility
string
Enum: "invisible" "visible" "invisible_in_discover"
status
string
Enum: "active" "deleted" "pending"

Responses

Request samples

Content type
application/json
{
  • "name": "ACM",
  • "slug": "acm",
  • "long_description": "The Acme Corporation is an ironic name for the fictional corporation, appearing in the Road Runner/Wile E. Coyote animated shorts, where it was used as a running gag.",
  • "short_description": "American Company that Manufactures Everything",
  • "contact_email": "[email protected]",
  • "twitter_link": "https://twitter.com/acm_company",
  • "linkedin_link": "https://www.linkedin.com/company/acm_company",
  • "image_url": null,
  • "visibility": "visible",
  • "status": "active",
  • "website": null
}

Response samples

Content type
application/json
{
  • "company_id": 42,
  • "name": "ACM",
  • "slug": "acm",
  • "long_description": "The Acme Corporation is an ironic name for the fictional corporation, appearing in the Road Runner/Wile E. Coyote animated shorts, where it was used as a running gag.",
  • "short_description": "American Company that Manufactures Everything",
  • "contact_email": "[email protected]",
  • "twitter_link": "https://twitter.com/acm_company",
  • "linkedin_link": "https://www.linkedin.com/company/acm_company",
  • "image_url": null,
  • "visibility": "visible",
  • "status": "active",
  • "website": null,
  • "created_at": "2016-06-09T02:00:47Z",
  • "created_by": "[email protected]",
  • "last_updated_at": "2023-08-17T16:18:10.386058Z",
  • "last_updated_by": "[email protected]"
}

Update a user

Authorizations:
BearerAuth
path Parameters
user_id
required
integer <int64> (UserId)
Example: 20

The user id

Request Body schema: application/json
name
string

User name

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "id": 20
}

App API

Delivery Commands

Lists delivery commands this app has access to.

Authorizations:
App_Token

Responses

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Delivery Files

Lists delivery files for a particular delivery command.

Authorizations:
App_Token
path Parameters
delivery_id
required
integer

Unique identifier for an delivery record.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Download file

Generates a download url for a particular delivery file

Authorizations:
App_Token
path Parameters
delivery_id
required
integer

Unique identifier for an delivery record.

filename
required
string

Name of a delivery file.

Responses

Response samples

Content type
application/json
{
  • "records": [
    ]
}

Permissions

Create a permission

Create a new permission

Authorizations:
BearerAuth
Request Body schema: application/json
resource
required
string

Resource type associated with a permissions

required
object

Status of a permission

required
object

Verb (action) associated with a permissions

Responses

Request samples

Content type
application/json
{
  • "resource": "test_resource",
  • "status": {
    },
  • "verb": {
    }
}

Response samples

Content type
application/json
{
  • "error": "Unauthorized",
  • "error_description": "You are not authorized to use this endpoint."
}

Whoami

Get a current user

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "user_id": 407,
  • "name": "John Doe",
  • "company_access_list": [
    ],
  • "current_company_scope": {},
  • "created_at": "2022-11-29T21:42:24.978707Z",
  • "created_by": null,
  • "last_updated_at": null,
  • "last_updated_by": null
}

Ingestion API

Returns a pre-sign S3 URL where to upload the file

Returns a pre-sign S3 URL where to upload the file

Authorizations:
BearerJWT
path Parameters
snapshot_id
required
string
Example: 698f1b19-3d2f-4a32-9bb5-3c1d7572d261

Required to upload multiple files as a single snapshot

Request Body schema: application/json
filename
required
string

The file name to use (e.g., maids.json.bz2)

Responses

Request samples

Content type
application/json
{
  • "filename": "maids.json.bz2"
}

proxy the request to S3

This endpoint is to allow snowflake app to only white list the api.narrative.io domain for everything. The endpoint /ingestion/sign returns a URL that refer to this endpoint.

path Parameters
path
required
string

The pre-signed URL path that we are proxying

Responses