Download OpenAPI specification:Download
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 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 an access rule.
access_rule_id required | integer Access rule identifier. |
{- "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",
- "status": "active",
- "tags": [
- "_nio_access_rule"
], - "nql": "select company_data.\"1\".columnA from company_data.\"1\" WHERE columnA = columnB",
- "schema": {
- "type": "object",
- "properties": {
- "columnA": {
- "display_name": "columnA",
- "type": "string"
}
}, - "required": [
- "columnA"
]
}, - "collaborators": {
- "type": "inclusion",
- "company_ids": [
- 1
]
}, - "price_cpm_usd": 1000.054,
- "metadata": {
- "created_at": "2023-12-14T21:36:51.847901",
- "updated_at": "2023-12-14T21:36:51.847901"
}, - "dataset_ids": [
- 42
], - "type": "owned",
- "is_owned": true
}
Update an access rule.
access_rule_id required | integer Access rule identifier. |
name | string (AccessRuleName) Optional. It should be unique. Also should not intersect with Dataset names. Must be <= 256 characters and consist of only alphanumeric characters and underscores. |
displayName | string (AccessRuleDisplayName) Optional. Display Name must be non-empty and less than 1000 chars. |
description | string (AccessRuleDescription) A human-friendly description of the access rule. |
tags | Array of strings (AccessRuleTags) Optional. |
object (AccessRuleCollaborators) A constraint describing which companies the access rule should or should not apply to. | |
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 |
status | string (AccessRuleStatus) Enum: "archived" "active" Current status of access rule: Active, Archieved |
priceCpmUsd | number <double> (AccessRulePriceCpmUsd) How much to charge for a row which matches this access rule. Cost per mille (CPM), more commonly called “cost per thousand,” is how much a buyer pays for 1,000 records. |
{- "display_name": "Updated Access Rule",
- "description": "This is an updated description for the access rule.",
- "status": "inactive",
- "tags": [
- "updated_tag1",
- "updated_tag2"
], - "collaborators": {
- "type": "exclusion",
- "company_ids": [
- 2,
- 543
]
}
}
{- "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",
- "status": "active",
- "tags": [
- "_nio_access_rule"
], - "nql": "select company_data.\"1\".columnA from company_data.\"1\" WHERE columnA = columnB",
- "schema": {
- "type": "object",
- "properties": {
- "columnA": {
- "display_name": "columnA",
- "type": "string"
}
}, - "required": [
- "columnA"
]
}, - "collaborators": {
- "type": "inclusion",
- "company_ids": [
- 1
]
}, - "price_cpm_usd": 1000.054,
- "metadata": {
- "created_at": "2023-12-14T21:36:51.847901",
- "updated_at": "2023-12-14T21:36:51.847901"
}, - "dataset_ids": [
- 42
], - "type": "owned",
- "is_owned": true
}
Get an access rule by name and company slug.
company_slug required | string Company slug. |
access_rule_name required | string Access rule name. |
{- "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",
- "status": "active",
- "tags": [
- "_nio_access_rule"
], - "nql": "select company_data.\"1\".columnA from company_data.\"1\" WHERE columnA = columnB",
- "schema": {
- "type": "object",
- "properties": {
- "columnA": {
- "display_name": "columnA",
- "type": "string"
}
}, - "required": [
- "columnA"
]
}, - "collaborators": {
- "type": "inclusion",
- "company_ids": [
- 1
]
}, - "price_cpm_usd": 1000.054,
- "metadata": {
- "created_at": "2023-12-14T21:36:51.847901",
- "updated_at": "2023-12-14T21:36:51.847901"
}, - "dataset_ids": [
- 42
], - "type": "owned",
- "is_owned": true
}
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'.
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. |
{- "prev_page": null,
- "current_page": 1,
- "next_page": null,
- "total_records": 2,
- "total_pages": 1,
- "records": [
- {
- "name": "name",
- "id": 2,
- "company_id": 42,
- "company_name": "company name",
- "company_slug": "company_slug",
- "display_name": "access rule",
- "description": "description",
- "tags": [
- "tag"
], - "schema": {
- "type": "object",
- "properties": {
- "id": {
- "order": 1,
- "display_name": "id of field",
- "type": "string"
}
}, - "required": [
- "id"
]
}, - "price_cpm_usd": 42,
- "metadata": {
- "created_at": "2007-12-03T10:15:30",
- "updated_at": "2008-12-03T10:15:30"
}, - "type": "explicit_share"
}, - {
- "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",
- "status": "active",
- "tags": [
- "_nio_access_rule"
], - "nql": "select company_data.\"1\".columnA from company_data.\"1\" WHERE columnA = columnB",
- "schema": {
- "type": "object",
- "properties": {
- "columnA": {
- "display_name": "columnA",
- "type": "string"
}
}, - "required": [
- "columnA"
]
}, - "collaborators": {
- "type": "inclusion",
- "company_ids": [
- 1
]
}, - "price_cpm_usd": 1000,
- "metadata": {
- "created_at": "2023-12-14T21:36:51.847901",
- "updated_at": "2023-12-14T21:36:51.847901"
}, - "dataset_ids": [
- 42
], - "type": "owned"
}
]
}
Creates a new access rule based on the provided NQL query.
name required | string (AccessRuleName) Optional. It should be unique. Also should not intersect with Dataset names. Must be <= 256 characters and consist of only alphanumeric characters and underscores. |
nql required | string (AccessRuleNQL) NQL query of access rule. |
display_name | string (AccessRuleDisplayName) Optional. Display Name must be non-empty and less than 1000 chars. |
description | string (AccessRuleDescription) A human-friendly description of the access rule. |
tags | Array of strings (AccessRuleTags) Optional. |
required | object (AccessRuleCollaborators) A constraint describing which companies the access rule should or should not apply to. |
price_cpm_usd required | number <double> (AccessRulePriceCpmUsd) How much to charge for a row which matches this access rule. Cost per mille (CPM), more commonly called “cost per thousand,” is how much a buyer pays for 1,000 records. |
{- "name": "example_access_rule",
- "display_name": "Example Access Rule",
- "description": "This is an example access rule.",
- "status": "active",
- "tags": [
- "tag1",
- "tag2"
], - "nql": "SELECT tar.\"maid\" FROM company_data.\"11370\" tar",
- "collaborators": {
- "type": "inclusion",
- "company_ids": [
- 1,
- 542
]
}, - "price_cpm_usd": 10
}
{- "prev_page": null,
- "current_page": 1,
- "next_page": null,
- "total_records": 2,
- "total_pages": 1,
- "records": [
- {
- "name": "name",
- "id": 2,
- "company_id": 42,
- "company_name": "company name",
- "company_slug": "company_slug",
- "display_name": "access rule",
- "description": "description",
- "tags": [
- "tag"
], - "schema": {
- "type": "object",
- "properties": {
- "id": {
- "order": 1,
- "display_name": "id of field",
- "type": "string"
}
}, - "required": [
- "id"
]
}, - "price_cpm_usd": 42,
- "metadata": {
- "created_at": "2007-12-03T10:15:30",
- "updated_at": "2008-12-03T10:15:30"
}, - "type": "explicit_share"
}, - {
- "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",
- "status": "active",
- "tags": [
- "_nio_access_rule"
], - "nql": "select company_data.\"1\".columnA from company_data.\"1\" WHERE columnA = columnB",
- "schema": {
- "type": "object",
- "properties": {
- "columnA": {
- "display_name": "columnA",
- "type": "string"
}
}, - "required": [
- "columnA"
]
}, - "collaborators": {
- "type": "inclusion",
- "company_ids": [
- 1
]
}, - "price_cpm_usd": 1000,
- "metadata": {
- "created_at": "2023-12-14T21:36:51.847901",
- "updated_at": "2023-12-14T21:36:51.847901"
}, - "dataset_ids": [
- 42
], - "type": "owned"
}
]
}
Submitting (create or update) JSON Schema (2019-09 version) for an app.
app_slug | string unique app name |
property name* additional property | any |
{ }
{- "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"
}
[- {
- "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"
}
]
version_id required | string <uuid> schema version id |
app_slug | string unique app name |
{- "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"
}
Submitting (create or update) data for a profile.
profile_id required | string <uuid> the profile id |
app_slug | string unique app name |
property name* additional property | any |
{ }
{- "data": { },
- "meta": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "schema_version_id": "4b5aa0f4-8eae-49a1-af8e-ef2be32c6e7d"
}
}
profile_id required | string <uuid> the profile id |
app_slug | string unique app name |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "schema_version_id": "4b5aa0f4-8eae-49a1-af8e-ef2be32c6e7d",
- "value": { },
- "created_at": "2019-08-24T14:15:22Z"
}
Slug can be changed (from NULL) just once.
app_id required | integer <int64> the app id |
slug | string |
{- "slug": "string"
}
{- "app_id": 0,
- "slug": "string"
}
{- "records": [
- {
- "id": "546c65d6-e589-4d3c-b1fe-7e61711cc418",
- "name": "My Read/Write Token",
- "permissions": [
- {
- "access": "read",
- "resource": "datasets"
}, - {
- "access": "write",
- "resource": "datasets"
}, - {
- "access": "read",
- "resource": "subscriptions"
}, - {
- "access": "write",
- "resource": "subscriptions"
}
], - "expires_at": "2023-10-31T11:19:13.400498Z"
}, - {
- "id": "2fb4df74-5318-4ecf-9f23-a8e1066689ba",
- "name": "My Read-Only Token",
- "permissions": [
- {
- "access": "read",
- "resource": "datasets"
}, - {
- "access": "read",
- "resource": "subscriptions"
}
], - "expires_at": "2023-11-30T11:19:13.400498Z"
}
]
}
Create a System Access Token
name required | string The name of the token |
Array of objects (Permission) The requested permissions | |
string or string |
{- "name": "My Token",
- "permissions": [
- {
- "access": "read",
- "resource": "datasets"
}, - {
- "access": "write",
- "resource": "datasets"
}, - {
- "access": "read",
- "resource": "subscriptions"
}, - {
- "access": "write",
- "resource": "subscriptions"
}
], - "expires_at": "2023-10-31T11:19:13.400498Z"
}
{- "id": "546c65d6-e589-4d3c-b1fe-7e61711cc418",
- "name": "My Token",
- "permissions": [
- {
- "access": "read",
- "resource": "datasets"
}, - {
- "access": "write",
- "resource": "datasets"
}, - {
- "access": "read",
- "resource": "subscriptions"
}, - {
- "access": "write",
- "resource": "subscriptions"
}
], - "expires_at": "2023-10-31T11:19:13.400498Z",
- "access_token": "ldg8uuGibVJNHI9s+dcdIQ=="
}
{- "record": {
- "id": "546c65d6-e589-4d3c-b1fe-7e61711cc418",
- "name": "My Token",
- "permissions": [
- {
- "access": "read",
- "resource": "datasets"
}, - {
- "access": "write",
- "resource": "datasets"
}, - {
- "access": "read",
- "resource": "subscriptions"
}, - {
- "access": "write",
- "resource": "subscriptions"
}
], - "expires_at": "2023-10-31T11:19:13.400498Z"
}
}
Update a System Access Token
name | string The name of the token |
Array of objects (Permission) The requested permissions | |
string or string |
{- "name": "My Token",
- "permissions": [
- {
- "access": "read",
- "resource": "datasets"
}, - {
- "access": "write",
- "resource": "datasets"
}, - {
- "access": "read",
- "resource": "subscriptions"
}, - {
- "access": "write",
- "resource": "subscriptions"
}
], - "expires_at": "2023-10-31T11:19:13.400498Z"
}
{- "id": "546c65d6-e589-4d3c-b1fe-7e61711cc418",
- "name": "My Token",
- "permissions": [
- {
- "access": "read",
- "resource": "datasets"
}, - {
- "access": "write",
- "resource": "datasets"
}, - {
- "access": "read",
- "resource": "subscriptions"
}, - {
- "access": "write",
- "resource": "subscriptions"
}
], - "expires_at": "2023-10-31T11:19:13.400498Z"
}
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.
Return all attributes.
resolve | boolean resolve attribute(s) which is true by default. |
{- "records": [
- {
- "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",
- "type": "object",
- "properties": {
- "value": {
- "type": "double",
- "validations": [
- "$this.value >= 0.0"
]
}, - "iso_4217_currency": {
- "type": "string",
- "enum": [
- "USD",
- "GBP",
- "JPY"
]
}, - "tags": {
- "type": "array",
- "items": {
- "type": "string"
}
}
}, - "required": [
- "value",
- "iso_4217_currency"
]
}
]
}
Create a new attribute.
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 If E.g. for an attribute with the following definition:
Valid validations include:
|
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. |
{- "type": "object",
- "validations": [
- "string"
], - "name": "price",
- "description": "The price of an order, product, or a price component. Currency field accepts ISO 4217 currency codes",
- "display_name": "Price",
- "properties": {
- "value": {
- "type": "double",
- "validations": [
- "$this.value >= 0.0"
]
}, - "iso_4217_currency": {
- "type": "string",
- "enum": [
- "USD",
- "GBP",
- "JPY"
]
}, - "tags": {
- "type": "array",
- "items": {
- "type": "string"
}
}
}, - "required": [
- "value",
- "iso_4217_currency"
]
}
{- "type": "object",
- "validations": [
- "string"
], - "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": {
- "value": {
- "type": "double",
- "validations": [
- "$this.value >= 0.0"
]
}, - "iso_4217_currency": {
- "type": "string",
- "enum": [
- "USD",
- "GBP",
- "JPY"
]
}, - "tags": {
- "type": "array",
- "items": {
- "type": "string"
}
}
}, - "required": [
- "value",
- "iso_4217_currency"
]
}
required | integer or string Either an attribute name or an attribute id |
resolve | boolean resolve attribute(s) which is true by default. |
{- "type": "object",
- "validations": [
- "string"
], - "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": {
- "value": {
- "type": "double",
- "validations": [
- "$this.value >= 0.0"
]
}, - "iso_4217_currency": {
- "type": "string",
- "enum": [
- "USD",
- "GBP",
- "JPY"
]
}, - "tags": {
- "type": "array",
- "items": {
- "type": "string"
}
}
}, - "required": [
- "value",
- "iso_4217_currency"
], - "metadata": {
- "attribute_cooccurrence": [
- {
- "attribute": {
- "id": 2,
- "name": "unique_id",
- "type": "string"
}, - "cooccurrence_pct": 0.42
}
]
}
}
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.
required | integer or string Either an attribute name or an attribute id |
attribute_id required | integer Unique identifier for an attribute. |
{- "type": "object",
- "validations": [
- "string"
], - "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": {
- "value": {
- "type": "double",
- "validations": [
- "$this.value >= 0.0"
]
}, - "iso_4217_currency": {
- "type": "string",
- "enum": [
- "USD",
- "GBP",
- "JPY"
]
}, - "tags": {
- "type": "array",
- "items": {
- "type": "string"
}
}
}, - "required": [
- "value",
- "iso_4217_currency"
]
}
Requests or refreshes the OAuth Token.
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 |
{- "access_token": "xxxxxxxxxxx",
- "access_token_expires_in": 3600,
- "refresh_token": "yyyyyyyyyyy",
- "refresh_token_expires_in": 14400
}
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.
stytch_session_token required | string The Stytch session token |
{- "stytch_session_token": "1rjpyoFiYLucsV-nuoi7dZ_VOkMUkcZLw6rICEYBzAy0"
}
{- "user": {
- "id": 10,
- "name": "First Last",
- "role": "partner_admin",
- "company_id": 100,
- "company_name": "ACME Corp"
}, - "api_token": {
- "access_token": "OI2Sfun5GnOS9zk0irkc3w==",
- "access_token_expires_in": 1000,
- "refresh_token": "yZYCdZrvHvlnEQw9/C640Q",
- "refresh_token_expires_in": 10000
}, - "legacy_token": "legacy-dsm-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.
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 |
{- "stytch_session_token": "1rjpyoFiYLucsV-nuoi7dZ_VOkMUkcZLw6rICEYBzAy0",
- "name": "First Last",
- "company_name": "ACME Corp"
}
{- "user_id": 100
}
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.
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 |
{- "stytch_token": {
- "token_type": "magiclinks",
- "token": "cykuz7f22h7rx5SPomBZUB359jj6GA-4NUBkuZDiduun"
}, - "session_duration_minutes": 5
}
{- "status": "complete",
- "stytch_session_token": "10hLht9FCo9cBp3I69uY5KjYMmy5VqmZjAVEz1CKZjsa",
- "stytch_session_jwt": "eyJhbGciOiJSUzI1NiIsImtpZCI6Imp3ay10ZXN0LTk1YjU2OGZhLTk1NWUtNGQ2OC04NDljLTM5MDA0MmEwZTlmOCIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsicHJvamVjdC10ZXN0LWQ1Y2E2MjhlLWFmMzctNDhmZC1hZTliLWIzMmUwY2Y5NmEyYyJdLCJleHAiOjE2ODUxMjkwNTAsImh0dHBzOi8vc3R5dGNoLmNvbS9zZXNzaW9uIjp7ImlkIjoic2Vzc2lvbi10ZXN0LTRlNTg4ZDQ3LTJlZjctNDZhNy1iMGQxLTQxOGJhMmZjNTljMiIsInN0YXJ0ZWRfYXQiOiIyMDIzLTA1LTI2VDE5OjE0OjU1WiIsImxhc3RfYWNjZXNzZWRfYXQiOiIyMDIzLTA1LTI2VDE5OjE5OjEwWiIsImV4cGlyZXNfYXQiOiIyMDIzLTA1LTI2VDIwOjE0OjU1WiIsImF0dHJpYnV0ZXMiOnsidXNlcl9hZ2VudCI6IiIsImlwX2FkZHJlc3MiOiIifSwiYXV0aGVudGljYXRpb25fZmFjdG9ycyI6W3sidHlwZSI6Im9hdXRoIiwiZGVsaXZlcnlfbWV0aG9kIjoib2F1dGhfZ2l0aHViIiwibGFzdF9hdXRoZW50aWNhdGVkX2F0IjoiMjAyMy0wNS0yNlQxOToxNDo1NVoiLCJnaXRodWJfb2F1dGhfZmFjdG9yIjp7ImlkIjoib2F1dGgtdXNlci10ZXN0LTdlY2M5YjUxLTU0YzUtNDg2MS04NjI2LTQyM2Q0Y2ZiYjQxMiIsInByb3ZpZGVyX3N1YmplY3QiOiIxNDIzMjkifX1dfSwiaWF0IjoxNjg1MTI4NzUwLCJpc3MiOiJzdHl0Y2guY29tL3Byb2plY3QtdGVzdC1kNWNhNjI4ZS1hZjM3LTQ4ZmQtYWU5Yi1iMzJlMGNmOTZhMmMiLCJuYmYiOjE2ODUxMjg3NTAsInN1YiI6InVzZXItdGVzdC03ZDYzYmMwNS05YzlmLTRmMTktODhhYS1iMmQwODk3ZGNiN2YifQ.OthwVlyy7Eu0g8h9K3tG2KzZBiOi3hykP-BpdTjrR4tZUXwqPyYPs8BmiaPRQOd17zyUNLxjGH4q5sfU6F0z4BXQXd3U8hWdRYRmUNVFPvLhFWva5FNP5ZYRD8XX_cjYTWV0E41Zd_W3YvFK5hCYs7cwYyR0mMw2XRzTYX1CjTfHOtNmPW-uLwhvHqAroLa2vM7PoyFlS0Xs2j0Dje01WI0eqJYgSVTwB5ZMTWttJKqXjFPaLQ-7XkJxHtmpXTxCoO-U38kDba26cyhTQrXBoHV2c8KMtrBWS3L3_kN-gw96FzcJ0C2W8HxhZJrI_GIZ4OLxFy3jxXvjDcsjMX940w"
}
Get dataset storage billings paginated.
per_page | integer Number of records to return. |
offset | integer Number of records to skip (it's usually page_number * per_page). |
[- {
- "billing_month": "2022-08-31T22:00:00Z",
- "company_id": 1,
- "company_name": "test_company1",
- "dataset_id": 322,
- "avg_gb_hours": 4
}
]
Get dataset storage billings for a company id paginated. Company id is extracted from token.
per_page | integer Number of records to return. |
offset | integer Number of records to skip (it's usually page_number * per_page). |
[- {
- "billing_month": "2022-08-31T22:00:00Z",
- "company_id": 1,
- "company_name": "test_company1",
- "dataset_id": 322,
- "avg_gb_hours": 4
}
]
Returns all domains registered by a specific company
company_id required | integer <int64> Example: 345 The id of an existing company |
{- "domains": [
- "string"
]
}
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.
image_name | string |
{- "image_name": "logo.png"
}
{- "expiry": "2022-12-06T17:00:31.098Z",
- "content_type": "image/png"
}
Returns all the companies providing data-stream market offers.
{- "records": [
- {
- "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",
- "location": "USA",
- "size": "200 - 500 Employees",
- "website": "N/A",
- "created_at": "2017-04-23T11:59:33"
}
]
}
Returns the marketing detailed information on a company.
company_id required | integer <int64> Example: 345 The id of an existing company |
{- "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",
- "location": "USA",
- "size": "200 - 500 Employees",
- "website": "N/A",
- "created_at": "2017-04-23T11:59:33"
}
connection_id required | string <uuid> Unique identifier for a connection. |
{- "id": "21691f26-f308-4e98-896c-579db27da04b",
- "dataset_id": 42,
- "profile_id": "d555f07f-f140-40d2-91af-e6aa54f7488b",
- "quick_settings": {
- "bucket_suffix": "/my-subscription",
- "number_of_files": "5"
}, - "status": "active"
}
connection_id required | string <uuid> Unique identifier for a connection. |
{- "id": "21691f26-f308-4e98-896c-579db27da04b",
- "dataset_id": 42,
- "profile_id": "d555f07f-f140-40d2-91af-e6aa54f7488b",
- "quick_settings": {
- "bucket_suffix": "/my-subscription",
- "number_of_files": "5"
}, - "status": "active"
}
dataset_id required | number Unique identifier for a dataset. |
{- "records": [
- {
- "id": "21691f26-f308-4e98-896c-579db27da04b",
- "dataset_id": 42,
- "profile_id": "d555f07f-f140-40d2-91af-e6aa54f7488b",
- "quick_settings": {
- "bucket_suffix": "/my-subscription",
- "number_of_files": "5"
}, - "status": "active"
}
]
}
dataset_id | number |
profile_id | string <uuid> (UUID) |
quick_settings | object |
{- "dataset_id": 42,
- "profile_id": "d555f07f-f140-40d2-91af-e6aa54f7488b",
- "quick_settings": {
- "bucket_suffix": "/my-subscription",
- "number_of_files": "5"
}
}
{- "id": "21691f26-f308-4e98-896c-579db27da04b",
- "dataset_id": 42,
- "profile_id": "d555f07f-f140-40d2-91af-e6aa54f7488b",
- "quick_settings": {
- "bucket_suffix": "/my-subscription",
- "number_of_files": "5"
}, - "status": "active"
}
Create a new data-shop.
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. |
{- "hostname": "string",
- "fe_manifest": { }
}
{- "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"
}
Gets the data-shop given its uuid.
data_shop_id required | string <uuid> Unique identifier for a data-shop. |
{- "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 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.
data_shop_id required | string <uuid> Unique identifier for a data-shop. |
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. |
{- "hostname": "string",
- "fe_manifest": { }
}
{- "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"
}
Gets the data-shop given its host name.
host_name required | string hostname like 'datashop.narrative.io' |
{- "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, 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.
ids required | Array of strings <uuid> (UUID) <= 200 characters |
{- "ids": [
- "cddfface-beda-4f84-ab22-a9933fad3992",
- "6460aa19-ddb2-424c-a54e-0f80b82b1698"
]
}
{- "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"
}
Gets all data-shops belonging to a company or empty if non exist.
company_id required | integer <int64> Example: 345 The id of an existing company |
{- "records": [
- {
- "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"
}
]
}
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 new data-stream.
Any datasets involved in the data-stream should exist and be active. Any fields referred
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) |
{- "name": "Greg Test Datastream",
- "slug": "greg-test-1",
- "content": {
- "description": "Greg created this datastream to test changes for attributes and is not going to upload any data for it.",
- "icon": null,
- "sections": [ ]
}, - "tags": [
- "Testing",
- "greg",
- "data",
- "datastream",
- "test"
], - "category": "Test",
- "offers": [
- {
- "id": "0488d937-b716-4df2-841c-8a63026c268d",
- "channel": "data_streams_market",
- "licensing": {
- "period": "P30D",
- "license": {
- "name": "Narrative Marketplace Data Purchase Agreement"
}
}, - "pricing": {
- "type": "per_record",
- "micro_cents_usd": 500000
}, - "shops": null
}, - {
- "id": "2ff93ef0-eb92-44ae-965e-dafbb6725fb9",
- "channel": "data_shop",
- "licensing": {
- "period": "P30D",
}, - "pricing": {
- "type": "per_record",
- "micro_cents_usd": 100000
}, - "shops": [
- "fanaticsdatashop.com"
]
}
], - "data_rules": {
- "column_sets": [
- {
- "dataset_id": 91,
- "fields": [
- {
- "field": "id",
- "filter": null,
- "exported": true
}, - {
- "field": "audience",
- "filter": null,
- "exported": true
}
]
}
], - "attributes": null,
- "deduplication": null,
- "frequency_filter": null
}, - "auth_rules": null
}
{- "id": "f94e8803-fc03-4c3e-a3fc-c3ffe3993788",
- "company_id": 100,
- "name": "best data stream name",
- "slug": "this-is-a-slug",
- "content": {
- "description": "Fabulous Data Stream even better than anything out there!",
- "sections": [
- {
- "title": "some title",
- "description": "some description",
- "image": "some-image"
}, - {
- "whatever": "whatever json structure FE would like to have here.",
- "free_form": "json here"
}
]
}, - "tags": [
- "tag1",
- "tag2"
], - "category": "categoryA",
- "offers": [
- {
- "id": "16310512-a8fb-4ce8-aec3-573693067df9",
- "channel": "data_streams_market",
- "licensing": {
- "period": "P90D",
- "license": {
- "name": "narrative opendata license"
}
}, - "pricing": {
- "type": "per_record",
- "micro_cents_usd": 70000
}, - "shops": null
}, - {
- "id": "d7542ec5-558f-4e98-9ff6-e049b24798fa",
- "channel": "data_shop",
- "licensing": {
- "period": "P90D",
- "license": {
- "name": "narrative opendata license"
}
}, - "pricing": {
- "type": "per_record",
- "micro_cents_usd": 50000
}, - "shops": null
}, - {
- "id": "5d52d8d8-b683-4ef4-9220-31347dc2237f",
- "channel": "data_shop",
- "licensing": {
- "period": "P90D",
- "license": {
- "name": "narrative opendata license"
}
}, - "pricing": {
- "type": "max_price_per_record",
- "micro_cents_usd": 30000
}, - "shops": [
- "only.on.tld.com"
]
}
], - "data_rules": {
- "column_sets": [
- {
- "dataset_id": 99999,
- "fields": [
- {
- "field": "col1",
- "filter": null,
- "exported": true
}, - {
- "field": "col2",
- "filter": "include_all_values_including_nulls_filter",
- "exported": true
}, - {
- "field": "col3",
- "filter": "include_only_if_not_null_filter",
- "exported": true
}, - {
- "field": "col4",
- "filter": {
- "type": "include",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col5",
- "filter": {
- "type": "exclude",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": {
- "type": "inclusive",
- "value": "-100"
}, - "max": {
- "type": "inclusive",
- "value": "100"
}
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": null,
- "max": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": false
}, - {
- "field": "col7",
- "filter": {
- "type": "include",
- "list": [
- "true"
]
}, - "exported": true
}, - {
- "field": "col8",
- "filter": {
- "recency": "P30D",
- "from": null,
- "to": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": true
}
]
}
], - "attributes": [
- {
- "attribute_id": 123,
- "fields": [
- {
- "field": "col1",
- "filter": null,
- "exported": true
}, - {
- "field": "col2",
- "filter": "include_all_values_including_nulls_filter",
- "exported": true
}, - {
- "field": "col3",
- "filter": "include_only_if_not_null_filter",
- "exported": true
}, - {
- "field": "col4",
- "filter": {
- "type": "include",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col5",
- "filter": {
- "type": "exclude",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": {
- "type": "inclusive",
- "value": "-100"
}, - "max": {
- "type": "inclusive",
- "value": "100"
}
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": null,
- "max": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": false
}, - {
- "field": "col7",
- "filter": {
- "type": "include",
- "list": [
- "true"
]
}, - "exported": true
}, - {
- "field": "col8",
- "filter": {
- "recency": "P30D",
- "from": null,
- "to": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": true
}, - {
- "field": "col9",
- "filter": {
- "expressions": [
- "col9 > -90",
- "col9 < 90"
]
}, - "exported": true
}
], - "optional": true
}, - {
- "attribute_id": 321,
- "fields": [
- {
- "field": "col9",
- "filter": {
- "expressions": [
- "col9 > -90",
- "col9 < 90"
]
}, - "exported": false
}
], - "optional": false
}
], - "deduplication": {
- "period": "P60D",
- "column_references": null,
- "attribute_references": [
- {
- "attribute_id": 123,
- "column_names": [
- "col9",
- "col9.foo.bar"
]
}
]
}, - "frequency_filter": {
- "column_references": null,
- "attribute_references": [
- {
- "attribute_id": 123,
- "column_names": [
- "col9.foo.bar"
]
}
], - "min_inclusive": 2,
- "max_inclusive": 5
}
}, - "auth_rules": {
- "company_constraint": {
- "type": "inclusion",
- "company_ids": [
- 160,
- 1701
]
}
}, - "created_by": 5000,
- "created_at": "2021-06-29T10:58:36.726Z",
- "updated_at": "2021-06-29T10:58:36.726Z",
- "datasets": null
}
Gets the data-stream given its uuid.
data_stream_id required | string <uuid> Unique identifier for a data-stream. |
{- "id": "f94e8803-fc03-4c3e-a3fc-c3ffe3993788",
- "company_id": 100,
- "name": "best data stream name",
- "slug": "this-is-a-slug",
- "content": {
- "description": "Fabulous Data Stream even better than anything out there!",
- "sections": [
- {
- "title": "some title",
- "description": "some description",
- "image": "some-image"
}, - {
- "whatever": "whatever json structure FE would like to have here.",
- "free_form": "json here"
}
]
}, - "tags": [
- "tag1",
- "tag2"
], - "category": "categoryA",
- "offers": [
- {
- "id": "16310512-a8fb-4ce8-aec3-573693067df9",
- "channel": "data_streams_market",
- "licensing": {
- "period": "P90D",
- "license": {
- "name": "narrative opendata license"
}
}, - "pricing": {
- "type": "per_record",
- "micro_cents_usd": 70000
}, - "shops": null
}, - {
- "id": "d7542ec5-558f-4e98-9ff6-e049b24798fa",
- "channel": "data_shop",
- "licensing": {
- "period": "P90D",
- "license": {
- "name": "narrative opendata license"
}
}, - "pricing": {
- "type": "per_record",
- "micro_cents_usd": 50000
}, - "shops": null
}, - {
- "id": "5d52d8d8-b683-4ef4-9220-31347dc2237f",
- "channel": "data_shop",
- "licensing": {
- "period": "P90D",
- "license": {
- "name": "narrative opendata license"
}
}, - "pricing": {
- "type": "max_price_per_record",
- "micro_cents_usd": 30000
}, - "shops": [
- "only.on.tld.com"
]
}
], - "data_rules": {
- "column_sets": [
- {
- "dataset_id": 99999,
- "fields": [
- {
- "field": "col1",
- "filter": null,
- "exported": true
}, - {
- "field": "col2",
- "filter": "include_all_values_including_nulls_filter",
- "exported": true
}, - {
- "field": "col3",
- "filter": "include_only_if_not_null_filter",
- "exported": true
}, - {
- "field": "col4",
- "filter": {
- "type": "include",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col5",
- "filter": {
- "type": "exclude",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": {
- "type": "inclusive",
- "value": "-100"
}, - "max": {
- "type": "inclusive",
- "value": "100"
}
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": null,
- "max": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": false
}, - {
- "field": "col7",
- "filter": {
- "type": "include",
- "list": [
- "true"
]
}, - "exported": true
}, - {
- "field": "col8",
- "filter": {
- "recency": "P30D",
- "from": null,
- "to": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": true
}
]
}
], - "attributes": [
- {
- "attribute_id": 123,
- "fields": [
- {
- "field": "col1",
- "filter": null,
- "exported": true
}, - {
- "field": "col2",
- "filter": "include_all_values_including_nulls_filter",
- "exported": true
}, - {
- "field": "col3",
- "filter": "include_only_if_not_null_filter",
- "exported": true
}, - {
- "field": "col4",
- "filter": {
- "type": "include",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col5",
- "filter": {
- "type": "exclude",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": {
- "type": "inclusive",
- "value": "-100"
}, - "max": {
- "type": "inclusive",
- "value": "100"
}
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": null,
- "max": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": false
}, - {
- "field": "col7",
- "filter": {
- "type": "include",
- "list": [
- "true"
]
}, - "exported": true
}, - {
- "field": "col8",
- "filter": {
- "recency": "P30D",
- "from": null,
- "to": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": true
}, - {
- "field": "col9",
- "filter": {
- "expressions": [
- "col9 > -90",
- "col9 < 90"
]
}, - "exported": true
}
], - "optional": true
}, - {
- "attribute_id": 321,
- "fields": [
- {
- "field": "col9",
- "filter": {
- "expressions": [
- "col9 > -90",
- "col9 < 90"
]
}, - "exported": false
}
], - "optional": false
}
], - "deduplication": {
- "period": "P60D",
- "column_references": null,
- "attribute_references": [
- {
- "attribute_id": 123,
- "column_names": [
- "col9",
- "col9.foo.bar"
]
}
]
}, - "frequency_filter": {
- "column_references": null,
- "attribute_references": [
- {
- "attribute_id": 123,
- "column_names": [
- "col9.foo.bar"
]
}
], - "min_inclusive": 2,
- "max_inclusive": 5
}
}, - "auth_rules": {
- "company_constraint": {
- "type": "inclusion",
- "company_ids": [
- 160,
- 1701
]
}
}, - "created_by": 5000,
- "created_at": "2021-06-29T10:58:36.726Z",
- "updated_at": "2021-06-29T10:58:36.726Z",
- "datasets": null
}
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
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.
data_stream_id required | string <uuid> Unique identifier for a data-stream. |
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. |
{- "id": "f94e8803-fc03-4c3e-a3fc-c3ffe3993788",
- "company_id": 100,
- "name": "best data stream name",
- "slug": "this-is-a-slug",
- "content": {
- "description": "Fabulous Data Stream even better than anything out there!",
- "sections": [
- {
- "title": "some title",
- "description": "some description",
- "image": "some-image"
}, - {
- "whatever": "whatever json structure FE would like to have here.",
- "free_form": "json here"
}
]
}, - "tags": [
- "tag1",
- "tag2"
], - "category": "categoryA",
- "offers": [
- {
- "id": "16310512-a8fb-4ce8-aec3-573693067df9",
- "channel": "data_streams_market",
- "licensing": {
- "period": "P90D",
- "license": {
- "name": "narrative opendata license"
}
}, - "pricing": {
- "type": "per_record",
- "micro_cents_usd": 70000
}, - "shops": null
}, - {
- "id": "d7542ec5-558f-4e98-9ff6-e049b24798fa",
- "channel": "data_shop",
- "licensing": {
- "period": "P90D",
- "license": {
- "name": "narrative opendata license"
}
}, - "pricing": {
- "type": "per_record",
- "micro_cents_usd": 50000
}, - "shops": null
}, - {
- "id": "5d52d8d8-b683-4ef4-9220-31347dc2237f",
- "channel": "data_shop",
- "licensing": {
- "period": "P90D",
- "license": {
- "name": "narrative opendata license"
}
}, - "pricing": {
- "type": "max_price_per_record",
- "micro_cents_usd": 30000
}, - "shops": [
- "only.on.tld.com"
]
}
], - "data_rules": {
- "column_sets": [
- {
- "dataset_id": 99999,
- "fields": [
- {
- "field": "col1",
- "filter": null,
- "exported": true
}, - {
- "field": "col2",
- "filter": "include_all_values_including_nulls_filter",
- "exported": true
}, - {
- "field": "col3",
- "filter": "include_only_if_not_null_filter",
- "exported": true
}, - {
- "field": "col4",
- "filter": {
- "type": "include",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col5",
- "filter": {
- "type": "exclude",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": {
- "type": "inclusive",
- "value": "-100"
}, - "max": {
- "type": "inclusive",
- "value": "100"
}
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": null,
- "max": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": false
}, - {
- "field": "col7",
- "filter": {
- "type": "include",
- "list": [
- "true"
]
}, - "exported": true
}, - {
- "field": "col8",
- "filter": {
- "recency": "P30D",
- "from": null,
- "to": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": true
}
]
}
], - "attributes": [
- {
- "attribute_id": 123,
- "fields": [
- {
- "field": "col1",
- "filter": null,
- "exported": true
}, - {
- "field": "col2",
- "filter": "include_all_values_including_nulls_filter",
- "exported": true
}, - {
- "field": "col3",
- "filter": "include_only_if_not_null_filter",
- "exported": true
}, - {
- "field": "col4",
- "filter": {
- "type": "include",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col5",
- "filter": {
- "type": "exclude",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": {
- "type": "inclusive",
- "value": "-100"
}, - "max": {
- "type": "inclusive",
- "value": "100"
}
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": null,
- "max": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": false
}, - {
- "field": "col7",
- "filter": {
- "type": "include",
- "list": [
- "true"
]
}, - "exported": true
}, - {
- "field": "col8",
- "filter": {
- "recency": "P30D",
- "from": null,
- "to": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": true
}, - {
- "field": "col9",
- "filter": {
- "expressions": [
- "col9 > -90",
- "col9 < 90"
]
}, - "exported": true
}
], - "optional": true
}, - {
- "attribute_id": 321,
- "fields": [
- {
- "field": "col9",
- "filter": {
- "expressions": [
- "col9 > -90",
- "col9 < 90"
]
}, - "exported": false
}
], - "optional": false
}
], - "deduplication": {
- "period": "P60D",
- "column_references": null,
- "attribute_references": [
- {
- "attribute_id": 123,
- "column_names": [
- "col9",
- "col9.foo.bar"
]
}
]
}, - "frequency_filter": {
- "column_references": null,
- "attribute_references": [
- {
- "attribute_id": 123,
- "column_names": [
- "col9.foo.bar"
]
}
], - "min_inclusive": 2,
- "max_inclusive": 5
}
}, - "auth_rules": {
- "company_constraint": {
- "type": "inclusion",
- "company_ids": [
- 160,
- 1701
]
}
}, - "created_by": 5000,
- "created_at": "2021-06-29T10:58:36.726Z",
- "updated_at": "2021-06-29T10:58:36.726Z",
- "datasets": null
}
{- "id": "f94e8803-fc03-4c3e-a3fc-c3ffe3993788",
- "company_id": 100,
- "name": "best data stream name",
- "slug": "this-is-a-slug",
- "content": {
- "description": "Fabulous Data Stream even better than anything out there!",
- "sections": [
- {
- "title": "some title",
- "description": "some description",
- "image": "some-image"
}, - {
- "whatever": "whatever json structure FE would like to have here.",
- "free_form": "json here"
}
]
}, - "tags": [
- "tag1",
- "tag2"
], - "category": "categoryA",
- "offers": [
- {
- "id": "16310512-a8fb-4ce8-aec3-573693067df9",
- "channel": "data_streams_market",
- "licensing": {
- "period": "P90D",
- "license": {
- "name": "narrative opendata license"
}
}, - "pricing": {
- "type": "per_record",
- "micro_cents_usd": 70000
}, - "shops": null
}, - {
- "id": "d7542ec5-558f-4e98-9ff6-e049b24798fa",
- "channel": "data_shop",
- "licensing": {
- "period": "P90D",
- "license": {
- "name": "narrative opendata license"
}
}, - "pricing": {
- "type": "per_record",
- "micro_cents_usd": 50000
}, - "shops": null
}, - {
- "id": "5d52d8d8-b683-4ef4-9220-31347dc2237f",
- "channel": "data_shop",
- "licensing": {
- "period": "P90D",
- "license": {
- "name": "narrative opendata license"
}
}, - "pricing": {
- "type": "max_price_per_record",
- "micro_cents_usd": 30000
}, - "shops": [
- "only.on.tld.com"
]
}
], - "data_rules": {
- "column_sets": [
- {
- "dataset_id": 99999,
- "fields": [
- {
- "field": "col1",
- "filter": null,
- "exported": true
}, - {
- "field": "col2",
- "filter": "include_all_values_including_nulls_filter",
- "exported": true
}, - {
- "field": "col3",
- "filter": "include_only_if_not_null_filter",
- "exported": true
}, - {
- "field": "col4",
- "filter": {
- "type": "include",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col5",
- "filter": {
- "type": "exclude",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": {
- "type": "inclusive",
- "value": "-100"
}, - "max": {
- "type": "inclusive",
- "value": "100"
}
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": null,
- "max": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": false
}, - {
- "field": "col7",
- "filter": {
- "type": "include",
- "list": [
- "true"
]
}, - "exported": true
}, - {
- "field": "col8",
- "filter": {
- "recency": "P30D",
- "from": null,
- "to": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": true
}
]
}
], - "attributes": [
- {
- "attribute_id": 123,
- "fields": [
- {
- "field": "col1",
- "filter": null,
- "exported": true
}, - {
- "field": "col2",
- "filter": "include_all_values_including_nulls_filter",
- "exported": true
}, - {
- "field": "col3",
- "filter": "include_only_if_not_null_filter",
- "exported": true
}, - {
- "field": "col4",
- "filter": {
- "type": "include",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col5",
- "filter": {
- "type": "exclude",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": {
- "type": "inclusive",
- "value": "-100"
}, - "max": {
- "type": "inclusive",
- "value": "100"
}
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": null,
- "max": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": false
}, - {
- "field": "col7",
- "filter": {
- "type": "include",
- "list": [
- "true"
]
}, - "exported": true
}, - {
- "field": "col8",
- "filter": {
- "recency": "P30D",
- "from": null,
- "to": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": true
}, - {
- "field": "col9",
- "filter": {
- "expressions": [
- "col9 > -90",
- "col9 < 90"
]
}, - "exported": true
}
], - "optional": true
}, - {
- "attribute_id": 321,
- "fields": [
- {
- "field": "col9",
- "filter": {
- "expressions": [
- "col9 > -90",
- "col9 < 90"
]
}, - "exported": false
}
], - "optional": false
}
], - "deduplication": {
- "period": "P60D",
- "column_references": null,
- "attribute_references": [
- {
- "attribute_id": 123,
- "column_names": [
- "col9",
- "col9.foo.bar"
]
}
]
}, - "frequency_filter": {
- "column_references": null,
- "attribute_references": [
- {
- "attribute_id": 123,
- "column_names": [
- "col9.foo.bar"
]
}
], - "min_inclusive": 2,
- "max_inclusive": 5
}
}, - "auth_rules": {
- "company_constraint": {
- "type": "inclusion",
- "company_ids": [
- 160,
- 1701
]
}
}, - "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, 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.
ids required | Array of strings <uuid> (UUID) <= 50 characters |
{- "ids": [
- "cddfface-beda-4f84-ab22-a9933fad3992",
- "6460aa19-ddb2-424c-a54e-0f80b82b1698"
]
}
{- "records": [
- {
- "id": "f94e8803-fc03-4c3e-a3fc-c3ffe3993788",
- "company_id": 100,
- "name": "best data stream name",
- "slug": "this-is-a-slug",
- "content": {
- "description": "Fabulous Data Stream even better than anything out there!",
- "sections": [
- {
- "title": "some title",
- "description": "some description",
- "image": "some-image"
}, - {
- "whatever": "whatever json structure FE would like to have here.",
- "free_form": "json here"
}
]
}, - "tags": [
- "tag1",
- "tag2"
], - "category": "categoryA",
- "offers": [
- {
- "id": "16310512-a8fb-4ce8-aec3-573693067df9",
- "channel": "data_streams_market",
- "licensing": {
- "period": "P90D",
- "license": {
- "name": "narrative opendata license"
}
}, - "pricing": {
- "type": "per_record",
- "micro_cents_usd": 70000
}, - "shops": null
}, - {
- "id": "d7542ec5-558f-4e98-9ff6-e049b24798fa",
- "channel": "data_shop",
- "licensing": {
- "period": "P90D",
- "license": {
- "name": "narrative opendata license"
}
}, - "pricing": {
- "type": "per_record",
- "micro_cents_usd": 50000
}, - "shops": null
}, - {
- "id": "5d52d8d8-b683-4ef4-9220-31347dc2237f",
- "channel": "data_shop",
- "licensing": {
- "period": "P90D",
- "license": {
- "name": "narrative opendata license"
}
}, - "pricing": {
- "type": "max_price_per_record",
- "micro_cents_usd": 30000
}, - "shops": [
- "only.on.tld.com"
]
}
], - "data_rules": {
- "column_sets": [
- {
- "dataset_id": 99999,
- "fields": [
- {
- "field": "col1",
- "filter": null,
- "exported": true
}, - {
- "field": "col2",
- "filter": "include_all_values_including_nulls_filter",
- "exported": true
}, - {
- "field": "col3",
- "filter": "include_only_if_not_null_filter",
- "exported": true
}, - {
- "field": "col4",
- "filter": {
- "type": "include",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col5",
- "filter": {
- "type": "exclude",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": {
- "type": "inclusive",
- "value": "-100"
}, - "max": {
- "type": "inclusive",
- "value": "100"
}
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": null,
- "max": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": false
}, - {
- "field": "col7",
- "filter": {
- "type": "include",
- "list": [
- "true"
]
}, - "exported": true
}, - {
- "field": "col8",
- "filter": {
- "recency": "P30D",
- "from": null,
- "to": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": true
}
]
}
], - "attributes": [
- {
- "attribute_id": 123,
- "fields": [
- {
- "field": "col1",
- "filter": null,
- "exported": true
}, - {
- "field": "col2",
- "filter": "include_all_values_including_nulls_filter",
- "exported": true
}, - {
- "field": "col3",
- "filter": "include_only_if_not_null_filter",
- "exported": true
}, - {
- "field": "col4",
- "filter": {
- "type": "include",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col5",
- "filter": {
- "type": "exclude",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": {
- "type": "inclusive",
- "value": "-100"
}, - "max": {
- "type": "inclusive",
- "value": "100"
}
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": null,
- "max": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": false
}, - {
- "field": "col7",
- "filter": {
- "type": "include",
- "list": [
- "true"
]
}, - "exported": true
}, - {
- "field": "col8",
- "filter": {
- "recency": "P30D",
- "from": null,
- "to": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": true
}, - {
- "field": "col9",
- "filter": {
- "expressions": [
- "col9 > -90",
- "col9 < 90"
]
}, - "exported": true
}
], - "optional": true
}, - {
- "attribute_id": 321,
- "fields": [
- {
- "field": "col9",
- "filter": {
- "expressions": [
- "col9 > -90",
- "col9 < 90"
]
}, - "exported": false
}
], - "optional": false
}
], - "deduplication": {
- "period": "P60D",
- "column_references": null,
- "attribute_references": [
- {
- "attribute_id": 123,
- "column_names": [
- "col9",
- "col9.foo.bar"
]
}
]
}, - "frequency_filter": {
- "column_references": null,
- "attribute_references": [
- {
- "attribute_id": 123,
- "column_names": [
- "col9.foo.bar"
]
}
], - "min_inclusive": 2,
- "max_inclusive": 5
}
}, - "auth_rules": {
- "company_constraint": {
- "type": "inclusion",
- "company_ids": [
- 160,
- 1701
]
}
}, - "created_by": 5000,
- "created_at": "2021-06-29T10:58:36.726Z",
- "updated_at": "2021-06-29T10:58:36.726Z",
- "datasets": null
}
]
}
Gets all data-streams belonging to a company or empty if non exist.
company_id required | integer <int64> Example: 345 The id of an existing company |
per_page | integer Number of records to return. |
offset | integer Number of records to skip (it's usually page_number * per_page). |
{- "records": [
- {
- "id": "f94e8803-fc03-4c3e-a3fc-c3ffe3993788",
- "company_id": 100,
- "name": "best data stream name",
- "slug": "this-is-a-slug",
- "content": {
- "description": "Fabulous Data Stream even better than anything out there!",
- "sections": [
- {
- "title": "some title",
- "description": "some description",
- "image": "some-image"
}, - {
- "whatever": "whatever json structure FE would like to have here.",
- "free_form": "json here"
}
]
}, - "tags": [
- "tag1",
- "tag2"
], - "category": "categoryA",
- "offers": [
- {
- "id": "16310512-a8fb-4ce8-aec3-573693067df9",
- "channel": "data_streams_market",
- "licensing": {
- "period": "P90D",
- "license": {
- "name": "narrative opendata license"
}
}, - "pricing": {
- "type": "per_record",
- "micro_cents_usd": 70000
}, - "shops": null
}, - {
- "id": "d7542ec5-558f-4e98-9ff6-e049b24798fa",
- "channel": "data_shop",
- "licensing": {
- "period": "P90D",
- "license": {
- "name": "narrative opendata license"
}
}, - "pricing": {
- "type": "per_record",
- "micro_cents_usd": 50000
}, - "shops": null
}, - {
- "id": "5d52d8d8-b683-4ef4-9220-31347dc2237f",
- "channel": "data_shop",
- "licensing": {
- "period": "P90D",
- "license": {
- "name": "narrative opendata license"
}
}, - "pricing": {
- "type": "max_price_per_record",
- "micro_cents_usd": 30000
}, - "shops": [
- "only.on.tld.com"
]
}
], - "data_rules": {
- "column_sets": [
- {
- "dataset_id": 99999,
- "fields": [
- {
- "field": "col1",
- "filter": null,
- "exported": true
}, - {
- "field": "col2",
- "filter": "include_all_values_including_nulls_filter",
- "exported": true
}, - {
- "field": "col3",
- "filter": "include_only_if_not_null_filter",
- "exported": true
}, - {
- "field": "col4",
- "filter": {
- "type": "include",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col5",
- "filter": {
- "type": "exclude",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": {
- "type": "inclusive",
- "value": "-100"
}, - "max": {
- "type": "inclusive",
- "value": "100"
}
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": null,
- "max": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": false
}, - {
- "field": "col7",
- "filter": {
- "type": "include",
- "list": [
- "true"
]
}, - "exported": true
}, - {
- "field": "col8",
- "filter": {
- "recency": "P30D",
- "from": null,
- "to": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": true
}
]
}
], - "attributes": [
- {
- "attribute_id": 123,
- "fields": [
- {
- "field": "col1",
- "filter": null,
- "exported": true
}, - {
- "field": "col2",
- "filter": "include_all_values_including_nulls_filter",
- "exported": true
}, - {
- "field": "col3",
- "filter": "include_only_if_not_null_filter",
- "exported": true
}, - {
- "field": "col4",
- "filter": {
- "type": "include",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col5",
- "filter": {
- "type": "exclude",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": {
- "type": "inclusive",
- "value": "-100"
}, - "max": {
- "type": "inclusive",
- "value": "100"
}
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": null,
- "max": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": false
}, - {
- "field": "col7",
- "filter": {
- "type": "include",
- "list": [
- "true"
]
}, - "exported": true
}, - {
- "field": "col8",
- "filter": {
- "recency": "P30D",
- "from": null,
- "to": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": true
}, - {
- "field": "col9",
- "filter": {
- "expressions": [
- "col9 > -90",
- "col9 < 90"
]
}, - "exported": true
}
], - "optional": true
}, - {
- "attribute_id": 321,
- "fields": [
- {
- "field": "col9",
- "filter": {
- "expressions": [
- "col9 > -90",
- "col9 < 90"
]
}, - "exported": false
}
], - "optional": false
}
], - "deduplication": {
- "period": "P60D",
- "column_references": null,
- "attribute_references": [
- {
- "attribute_id": 123,
- "column_names": [
- "col9",
- "col9.foo.bar"
]
}
]
}, - "frequency_filter": {
- "column_references": null,
- "attribute_references": [
- {
- "attribute_id": 123,
- "column_names": [
- "col9.foo.bar"
]
}
], - "min_inclusive": 2,
- "max_inclusive": 5
}
}, - "auth_rules": {
- "company_constraint": {
- "type": "inclusion",
- "company_ids": [
- 160,
- 1701
]
}
}, - "created_by": 5000,
- "created_at": "2021-06-29T10:58:36.726Z",
- "updated_at": "2021-06-29T10:58:36.726Z",
- "datasets": null
}
]
}
Gets all data-streams belonging to a company and the given search expression.
Search expressions follow the postgres 'websearch_to_tsquery' specification:
tshirt and apparel or accessories -leather
"find this" -"but not this"
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'
company_id required | integer <int64> Example: 345 The id of an existing company |
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). |
{- "records": [
- {
- "id": "f94e8803-fc03-4c3e-a3fc-c3ffe3993788",
- "company_id": 100,
- "name": "best data stream name",
- "slug": "this-is-a-slug",
- "content": {
- "description": "Fabulous Data Stream even better than anything out there!",
- "sections": [
- {
- "title": "some title",
- "description": "some description",
- "image": "some-image"
}, - {
- "whatever": "whatever json structure FE would like to have here.",
- "free_form": "json here"
}
]
}, - "tags": [
- "tag1",
- "tag2"
], - "category": "categoryA",
- "offers": [
- {
- "id": "16310512-a8fb-4ce8-aec3-573693067df9",
- "channel": "data_streams_market",
- "licensing": {
- "period": "P90D",
- "license": {
- "name": "narrative opendata license"
}
}, - "pricing": {
- "type": "per_record",
- "micro_cents_usd": 70000
}, - "shops": null
}, - {
- "id": "d7542ec5-558f-4e98-9ff6-e049b24798fa",
- "channel": "data_shop",
- "licensing": {
- "period": "P90D",
- "license": {
- "name": "narrative opendata license"
}
}, - "pricing": {
- "type": "per_record",
- "micro_cents_usd": 50000
}, - "shops": null
}, - {
- "id": "5d52d8d8-b683-4ef4-9220-31347dc2237f",
- "channel": "data_shop",
- "licensing": {
- "period": "P90D",
- "license": {
- "name": "narrative opendata license"
}
}, - "pricing": {
- "type": "max_price_per_record",
- "micro_cents_usd": 30000
}, - "shops": [
- "only.on.tld.com"
]
}
], - "data_rules": {
- "column_sets": [
- {
- "dataset_id": 99999,
- "fields": [
- {
- "field": "col1",
- "filter": null,
- "exported": true
}, - {
- "field": "col2",
- "filter": "include_all_values_including_nulls_filter",
- "exported": true
}, - {
- "field": "col3",
- "filter": "include_only_if_not_null_filter",
- "exported": true
}, - {
- "field": "col4",
- "filter": {
- "type": "include",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col5",
- "filter": {
- "type": "exclude",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": {
- "type": "inclusive",
- "value": "-100"
}, - "max": {
- "type": "inclusive",
- "value": "100"
}
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": null,
- "max": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": false
}, - {
- "field": "col7",
- "filter": {
- "type": "include",
- "list": [
- "true"
]
}, - "exported": true
}, - {
- "field": "col8",
- "filter": {
- "recency": "P30D",
- "from": null,
- "to": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": true
}
]
}
], - "attributes": [
- {
- "attribute_id": 123,
- "fields": [
- {
- "field": "col1",
- "filter": null,
- "exported": true
}, - {
- "field": "col2",
- "filter": "include_all_values_including_nulls_filter",
- "exported": true
}, - {
- "field": "col3",
- "filter": "include_only_if_not_null_filter",
- "exported": true
}, - {
- "field": "col4",
- "filter": {
- "type": "include",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col5",
- "filter": {
- "type": "exclude",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": {
- "type": "inclusive",
- "value": "-100"
}, - "max": {
- "type": "inclusive",
- "value": "100"
}
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": null,
- "max": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": false
}, - {
- "field": "col7",
- "filter": {
- "type": "include",
- "list": [
- "true"
]
}, - "exported": true
}, - {
- "field": "col8",
- "filter": {
- "recency": "P30D",
- "from": null,
- "to": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": true
}, - {
- "field": "col9",
- "filter": {
- "expressions": [
- "col9 > -90",
- "col9 < 90"
]
}, - "exported": true
}
], - "optional": true
}, - {
- "attribute_id": 321,
- "fields": [
- {
- "field": "col9",
- "filter": {
- "expressions": [
- "col9 > -90",
- "col9 < 90"
]
}, - "exported": false
}
], - "optional": false
}
], - "deduplication": {
- "period": "P60D",
- "column_references": null,
- "attribute_references": [
- {
- "attribute_id": 123,
- "column_names": [
- "col9",
- "col9.foo.bar"
]
}
]
}, - "frequency_filter": {
- "column_references": null,
- "attribute_references": [
- {
- "attribute_id": 123,
- "column_names": [
- "col9.foo.bar"
]
}
], - "min_inclusive": 2,
- "max_inclusive": 5
}
}, - "auth_rules": {
- "company_constraint": {
- "type": "inclusion",
- "company_ids": [
- 160,
- 1701
]
}
}, - "created_by": 5000,
- "created_at": "2021-06-29T10:58:36.726Z",
- "updated_at": "2021-06-29T10:58:36.726Z",
- "datasets": null
}
]
}
Gets the data-stream for a given company and slug
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. |
per_page | integer Number of records to return. |
offset | integer Number of records to skip (it's usually page_number * per_page). |
{- "records": [
- {
- "id": "f94e8803-fc03-4c3e-a3fc-c3ffe3993788",
- "company_id": 100,
- "name": "best data stream name",
- "slug": "this-is-a-slug",
- "content": {
- "description": "Fabulous Data Stream even better than anything out there!",
- "sections": [
- {
- "title": "some title",
- "description": "some description",
- "image": "some-image"
}, - {
- "whatever": "whatever json structure FE would like to have here.",
- "free_form": "json here"
}
]
}, - "tags": [
- "tag1",
- "tag2"
], - "category": "categoryA",
- "offers": [
- {
- "id": "16310512-a8fb-4ce8-aec3-573693067df9",
- "channel": "data_streams_market",
- "licensing": {
- "period": "P90D",
- "license": {
- "name": "narrative opendata license"
}
}, - "pricing": {
- "type": "per_record",
- "micro_cents_usd": 70000
}, - "shops": null
}, - {
- "id": "d7542ec5-558f-4e98-9ff6-e049b24798fa",
- "channel": "data_shop",
- "licensing": {
- "period": "P90D",
- "license": {
- "name": "narrative opendata license"
}
}, - "pricing": {
- "type": "per_record",
- "micro_cents_usd": 50000
}, - "shops": null
}, - {
- "id": "5d52d8d8-b683-4ef4-9220-31347dc2237f",
- "channel": "data_shop",
- "licensing": {
- "period": "P90D",
- "license": {
- "name": "narrative opendata license"
}
}, - "pricing": {
- "type": "max_price_per_record",
- "micro_cents_usd": 30000
}, - "shops": [
- "only.on.tld.com"
]
}
], - "data_rules": {
- "column_sets": [
- {
- "dataset_id": 99999,
- "fields": [
- {
- "field": "col1",
- "filter": null,
- "exported": true
}, - {
- "field": "col2",
- "filter": "include_all_values_including_nulls_filter",
- "exported": true
}, - {
- "field": "col3",
- "filter": "include_only_if_not_null_filter",
- "exported": true
}, - {
- "field": "col4",
- "filter": {
- "type": "include",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col5",
- "filter": {
- "type": "exclude",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": {
- "type": "inclusive",
- "value": "-100"
}, - "max": {
- "type": "inclusive",
- "value": "100"
}
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": null,
- "max": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": false
}, - {
- "field": "col7",
- "filter": {
- "type": "include",
- "list": [
- "true"
]
}, - "exported": true
}, - {
- "field": "col8",
- "filter": {
- "recency": "P30D",
- "from": null,
- "to": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": true
}
]
}
], - "attributes": [
- {
- "attribute_id": 123,
- "fields": [
- {
- "field": "col1",
- "filter": null,
- "exported": true
}, - {
- "field": "col2",
- "filter": "include_all_values_including_nulls_filter",
- "exported": true
}, - {
- "field": "col3",
- "filter": "include_only_if_not_null_filter",
- "exported": true
}, - {
- "field": "col4",
- "filter": {
- "type": "include",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col5",
- "filter": {
- "type": "exclude",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": {
- "type": "inclusive",
- "value": "-100"
}, - "max": {
- "type": "inclusive",
- "value": "100"
}
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": null,
- "max": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": false
}, - {
- "field": "col7",
- "filter": {
- "type": "include",
- "list": [
- "true"
]
}, - "exported": true
}, - {
- "field": "col8",
- "filter": {
- "recency": "P30D",
- "from": null,
- "to": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": true
}, - {
- "field": "col9",
- "filter": {
- "expressions": [
- "col9 > -90",
- "col9 < 90"
]
}, - "exported": true
}
], - "optional": true
}, - {
- "attribute_id": 321,
- "fields": [
- {
- "field": "col9",
- "filter": {
- "expressions": [
- "col9 > -90",
- "col9 < 90"
]
}, - "exported": false
}
], - "optional": false
}
], - "deduplication": {
- "period": "P60D",
- "column_references": null,
- "attribute_references": [
- {
- "attribute_id": 123,
- "column_names": [
- "col9",
- "col9.foo.bar"
]
}
]
}, - "frequency_filter": {
- "column_references": null,
- "attribute_references": [
- {
- "attribute_id": 123,
- "column_names": [
- "col9.foo.bar"
]
}
], - "min_inclusive": 2,
- "max_inclusive": 5
}
}, - "auth_rules": {
- "company_constraint": {
- "type": "inclusion",
- "company_ids": [
- 160,
- 1701
]
}
}, - "created_by": 5000,
- "created_at": "2021-06-29T10:58:36.726Z",
- "updated_at": "2021-06-29T10:58:36.726Z",
- "datasets": null
}
]
}
Retrieve schema for deliveries from this data stream.
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. |
{- "value": {
- "type": "double"
}, - "iso_4217_currency": {
- "type": "string"
}, - "tags": {
- "type": "array",
- "items": {
- "type": "string"
}
}
}
Gets all data-streams belonging to a company, filtered for the hostname.
company_id required | integer <int64> Example: 345 The id of an existing company |
host_name required | string hostname like 'datashop.narrative.io' |
per_page | integer Number of records to return. |
offset | integer Number of records to skip (it's usually page_number * per_page). |
{- "records": [
- {
- "id": "f94e8803-fc03-4c3e-a3fc-c3ffe3993788",
- "company_id": 100,
- "name": "best data stream name",
- "slug": "this-is-a-slug",
- "content": {
- "description": "Fabulous Data Stream even better than anything out there!",
- "sections": [
- {
- "title": "some title",
- "description": "some description",
- "image": "some-image"
}, - {
- "whatever": "whatever json structure FE would like to have here.",
- "free_form": "json here"
}
]
}, - "tags": [
- "tag1",
- "tag2"
], - "category": "categoryA",
- "offers": [
- {
- "id": "16310512-a8fb-4ce8-aec3-573693067df9",
- "channel": "data_streams_market",
- "licensing": {
- "period": "P90D",
- "license": {
- "name": "narrative opendata license"
}
}, - "pricing": {
- "type": "per_record",
- "micro_cents_usd": 70000
}, - "shops": null
}, - {
- "id": "d7542ec5-558f-4e98-9ff6-e049b24798fa",
- "channel": "data_shop",
- "licensing": {
- "period": "P90D",
- "license": {
- "name": "narrative opendata license"
}
}, - "pricing": {
- "type": "per_record",
- "micro_cents_usd": 50000
}, - "shops": null
}, - {
- "id": "5d52d8d8-b683-4ef4-9220-31347dc2237f",
- "channel": "data_shop",
- "licensing": {
- "period": "P90D",
- "license": {
- "name": "narrative opendata license"
}
}, - "pricing": {
- "type": "max_price_per_record",
- "micro_cents_usd": 30000
}, - "shops": [
- "only.on.tld.com"
]
}
], - "data_rules": {
- "column_sets": [
- {
- "dataset_id": 99999,
- "fields": [
- {
- "field": "col1",
- "filter": null,
- "exported": true
}, - {
- "field": "col2",
- "filter": "include_all_values_including_nulls_filter",
- "exported": true
}, - {
- "field": "col3",
- "filter": "include_only_if_not_null_filter",
- "exported": true
}, - {
- "field": "col4",
- "filter": {
- "type": "include",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col5",
- "filter": {
- "type": "exclude",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": {
- "type": "inclusive",
- "value": "-100"
}, - "max": {
- "type": "inclusive",
- "value": "100"
}
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": null,
- "max": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": false
}, - {
- "field": "col7",
- "filter": {
- "type": "include",
- "list": [
- "true"
]
}, - "exported": true
}, - {
- "field": "col8",
- "filter": {
- "recency": "P30D",
- "from": null,
- "to": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": true
}
]
}
], - "attributes": [
- {
- "attribute_id": 123,
- "fields": [
- {
- "field": "col1",
- "filter": null,
- "exported": true
}, - {
- "field": "col2",
- "filter": "include_all_values_including_nulls_filter",
- "exported": true
}, - {
- "field": "col3",
- "filter": "include_only_if_not_null_filter",
- "exported": true
}, - {
- "field": "col4",
- "filter": {
- "type": "include",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col5",
- "filter": {
- "type": "exclude",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": {
- "type": "inclusive",
- "value": "-100"
}, - "max": {
- "type": "inclusive",
- "value": "100"
}
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": null,
- "max": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": false
}, - {
- "field": "col7",
- "filter": {
- "type": "include",
- "list": [
- "true"
]
}, - "exported": true
}, - {
- "field": "col8",
- "filter": {
- "recency": "P30D",
- "from": null,
- "to": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": true
}, - {
- "field": "col9",
- "filter": {
- "expressions": [
- "col9 > -90",
- "col9 < 90"
]
}, - "exported": true
}
], - "optional": true
}, - {
- "attribute_id": 321,
- "fields": [
- {
- "field": "col9",
- "filter": {
- "expressions": [
- "col9 > -90",
- "col9 < 90"
]
}, - "exported": false
}
], - "optional": false
}
], - "deduplication": {
- "period": "P60D",
- "column_references": null,
- "attribute_references": [
- {
- "attribute_id": 123,
- "column_names": [
- "col9",
- "col9.foo.bar"
]
}
]
}, - "frequency_filter": {
- "column_references": null,
- "attribute_references": [
- {
- "attribute_id": 123,
- "column_names": [
- "col9.foo.bar"
]
}
], - "min_inclusive": 2,
- "max_inclusive": 5
}
}, - "auth_rules": {
- "company_constraint": {
- "type": "inclusion",
- "company_ids": [
- 160,
- 1701
]
}
}, - "created_by": 5000,
- "created_at": "2021-06-29T10:58:36.726Z",
- "updated_at": "2021-06-29T10:58:36.726Z",
- "datasets": null
}
]
}
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:
tshirt and apparel or accessories -leather
"find this" -"but not this"
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'
company_id required | integer <int64> Example: 345 The id of an existing company |
host_name required | string hostname like 'datashop.narrative.io' |
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). |
{- "records": [
- {
- "id": "f94e8803-fc03-4c3e-a3fc-c3ffe3993788",
- "company_id": 100,
- "name": "best data stream name",
- "slug": "this-is-a-slug",
- "content": {
- "description": "Fabulous Data Stream even better than anything out there!",
- "sections": [
- {
- "title": "some title",
- "description": "some description",
- "image": "some-image"
}, - {
- "whatever": "whatever json structure FE would like to have here.",
- "free_form": "json here"
}
]
}, - "tags": [
- "tag1",
- "tag2"
], - "category": "categoryA",
- "offers": [
- {
- "id": "16310512-a8fb-4ce8-aec3-573693067df9",
- "channel": "data_streams_market",
- "licensing": {
- "period": "P90D",
- "license": {
- "name": "narrative opendata license"
}
}, - "pricing": {
- "type": "per_record",
- "micro_cents_usd": 70000
}, - "shops": null
}, - {
- "id": "d7542ec5-558f-4e98-9ff6-e049b24798fa",
- "channel": "data_shop",
- "licensing": {
- "period": "P90D",
- "license": {
- "name": "narrative opendata license"
}
}, - "pricing": {
- "type": "per_record",
- "micro_cents_usd": 50000
}, - "shops": null
}, - {
- "id": "5d52d8d8-b683-4ef4-9220-31347dc2237f",
- "channel": "data_shop",
- "licensing": {
- "period": "P90D",
- "license": {
- "name": "narrative opendata license"
}
}, - "pricing": {
- "type": "max_price_per_record",
- "micro_cents_usd": 30000
}, - "shops": [
- "only.on.tld.com"
]
}
], - "data_rules": {
- "column_sets": [
- {
- "dataset_id": 99999,
- "fields": [
- {
- "field": "col1",
- "filter": null,
- "exported": true
}, - {
- "field": "col2",
- "filter": "include_all_values_including_nulls_filter",
- "exported": true
}, - {
- "field": "col3",
- "filter": "include_only_if_not_null_filter",
- "exported": true
}, - {
- "field": "col4",
- "filter": {
- "type": "include",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col5",
- "filter": {
- "type": "exclude",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": {
- "type": "inclusive",
- "value": "-100"
}, - "max": {
- "type": "inclusive",
- "value": "100"
}
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": null,
- "max": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": false
}, - {
- "field": "col7",
- "filter": {
- "type": "include",
- "list": [
- "true"
]
}, - "exported": true
}, - {
- "field": "col8",
- "filter": {
- "recency": "P30D",
- "from": null,
- "to": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": true
}
]
}
], - "attributes": [
- {
- "attribute_id": 123,
- "fields": [
- {
- "field": "col1",
- "filter": null,
- "exported": true
}, - {
- "field": "col2",
- "filter": "include_all_values_including_nulls_filter",
- "exported": true
}, - {
- "field": "col3",
- "filter": "include_only_if_not_null_filter",
- "exported": true
}, - {
- "field": "col4",
- "filter": {
- "type": "include",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col5",
- "filter": {
- "type": "exclude",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": {
- "type": "inclusive",
- "value": "-100"
}, - "max": {
- "type": "inclusive",
- "value": "100"
}
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": null,
- "max": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": false
}, - {
- "field": "col7",
- "filter": {
- "type": "include",
- "list": [
- "true"
]
}, - "exported": true
}, - {
- "field": "col8",
- "filter": {
- "recency": "P30D",
- "from": null,
- "to": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": true
}, - {
- "field": "col9",
- "filter": {
- "expressions": [
- "col9 > -90",
- "col9 < 90"
]
}, - "exported": true
}
], - "optional": true
}, - {
- "attribute_id": 321,
- "fields": [
- {
- "field": "col9",
- "filter": {
- "expressions": [
- "col9 > -90",
- "col9 < 90"
]
}, - "exported": false
}
], - "optional": false
}
], - "deduplication": {
- "period": "P60D",
- "column_references": null,
- "attribute_references": [
- {
- "attribute_id": 123,
- "column_names": [
- "col9",
- "col9.foo.bar"
]
}
]
}, - "frequency_filter": {
- "column_references": null,
- "attribute_references": [
- {
- "attribute_id": 123,
- "column_names": [
- "col9.foo.bar"
]
}
], - "min_inclusive": 2,
- "max_inclusive": 5
}
}, - "auth_rules": {
- "company_constraint": {
- "type": "inclusion",
- "company_ids": [
- 160,
- 1701
]
}
}, - "created_by": 5000,
- "created_at": "2021-06-29T10:58:36.726Z",
- "updated_at": "2021-06-29T10:58:36.726Z",
- "datasets": null
}
]
}
Gets all data-streams belonging to a company, given a sales channel.
Sales channels:
company_id required | integer <int64> Example: 345 The id of an existing company |
sales_channel required | string Enum: "data_streams_market" "data_shop" |
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). |
{- "records": [
- {
- "id": "f94e8803-fc03-4c3e-a3fc-c3ffe3993788",
- "company_id": 100,
- "name": "best data stream name",
- "slug": "this-is-a-slug",
- "content": {
- "description": "Fabulous Data Stream even better than anything out there!",
- "sections": [
- {
- "title": "some title",
- "description": "some description",
- "image": "some-image"
}, - {
- "whatever": "whatever json structure FE would like to have here.",
- "free_form": "json here"
}
]
}, - "tags": [
- "tag1",
- "tag2"
], - "category": "categoryA",
- "offers": [
- {
- "id": "16310512-a8fb-4ce8-aec3-573693067df9",
- "channel": "data_streams_market",
- "licensing": {
- "period": "P90D",
- "license": {
- "name": "narrative opendata license"
}
}, - "pricing": {
- "type": "per_record",
- "micro_cents_usd": 70000
}, - "shops": null
}, - {
- "id": "d7542ec5-558f-4e98-9ff6-e049b24798fa",
- "channel": "data_shop",
- "licensing": {
- "period": "P90D",
- "license": {
- "name": "narrative opendata license"
}
}, - "pricing": {
- "type": "per_record",
- "micro_cents_usd": 50000
}, - "shops": null
}, - {
- "id": "5d52d8d8-b683-4ef4-9220-31347dc2237f",
- "channel": "data_shop",
- "licensing": {
- "period": "P90D",
- "license": {
- "name": "narrative opendata license"
}
}, - "pricing": {
- "type": "max_price_per_record",
- "micro_cents_usd": 30000
}, - "shops": [
- "only.on.tld.com"
]
}
], - "data_rules": {
- "column_sets": [
- {
- "dataset_id": 99999,
- "fields": [
- {
- "field": "col1",
- "filter": null,
- "exported": true
}, - {
- "field": "col2",
- "filter": "include_all_values_including_nulls_filter",
- "exported": true
}, - {
- "field": "col3",
- "filter": "include_only_if_not_null_filter",
- "exported": true
}, - {
- "field": "col4",
- "filter": {
- "type": "include",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col5",
- "filter": {
- "type": "exclude",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": {
- "type": "inclusive",
- "value": "-100"
}, - "max": {
- "type": "inclusive",
- "value": "100"
}
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": null,
- "max": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": false
}, - {
- "field": "col7",
- "filter": {
- "type": "include",
- "list": [
- "true"
]
}, - "exported": true
}, - {
- "field": "col8",
- "filter": {
- "recency": "P30D",
- "from": null,
- "to": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": true
}
]
}
], - "attributes": [
- {
- "attribute_id": 123,
- "fields": [
- {
- "field": "col1",
- "filter": null,
- "exported": true
}, - {
- "field": "col2",
- "filter": "include_all_values_including_nulls_filter",
- "exported": true
}, - {
- "field": "col3",
- "filter": "include_only_if_not_null_filter",
- "exported": true
}, - {
- "field": "col4",
- "filter": {
- "type": "include",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col5",
- "filter": {
- "type": "exclude",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": {
- "type": "inclusive",
- "value": "-100"
}, - "max": {
- "type": "inclusive",
- "value": "100"
}
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": null,
- "max": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": false
}, - {
- "field": "col7",
- "filter": {
- "type": "include",
- "list": [
- "true"
]
}, - "exported": true
}, - {
- "field": "col8",
- "filter": {
- "recency": "P30D",
- "from": null,
- "to": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": true
}, - {
- "field": "col9",
- "filter": {
- "expressions": [
- "col9 > -90",
- "col9 < 90"
]
}, - "exported": true
}
], - "optional": true
}, - {
- "attribute_id": 321,
- "fields": [
- {
- "field": "col9",
- "filter": {
- "expressions": [
- "col9 > -90",
- "col9 < 90"
]
}, - "exported": false
}
], - "optional": false
}
], - "deduplication": {
- "period": "P60D",
- "column_references": null,
- "attribute_references": [
- {
- "attribute_id": 123,
- "column_names": [
- "col9",
- "col9.foo.bar"
]
}
]
}, - "frequency_filter": {
- "column_references": null,
- "attribute_references": [
- {
- "attribute_id": 123,
- "column_names": [
- "col9.foo.bar"
]
}
], - "min_inclusive": 2,
- "max_inclusive": 5
}
}, - "auth_rules": {
- "company_constraint": {
- "type": "inclusion",
- "company_ids": [
- 160,
- 1701
]
}
}, - "created_by": 5000,
- "created_at": "2021-06-29T10:58:36.726Z",
- "updated_at": "2021-06-29T10:58:36.726Z",
- "datasets": null
}
]
}
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:
tshirt and apparel or accessories -leather
"find this" -"but not this"
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'
company_id required | integer <int64> Example: 345 The id of an existing company |
sales_channel required | string Enum: "data_streams_market" "data_shop" |
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). |
{- "records": [
- {
- "id": "f94e8803-fc03-4c3e-a3fc-c3ffe3993788",
- "company_id": 100,
- "name": "best data stream name",
- "slug": "this-is-a-slug",
- "content": {
- "description": "Fabulous Data Stream even better than anything out there!",
- "sections": [
- {
- "title": "some title",
- "description": "some description",
- "image": "some-image"
}, - {
- "whatever": "whatever json structure FE would like to have here.",
- "free_form": "json here"
}
]
}, - "tags": [
- "tag1",
- "tag2"
], - "category": "categoryA",
- "offers": [
- {
- "id": "16310512-a8fb-4ce8-aec3-573693067df9",
- "channel": "data_streams_market",
- "licensing": {
- "period": "P90D",
- "license": {
- "name": "narrative opendata license"
}
}, - "pricing": {
- "type": "per_record",
- "micro_cents_usd": 70000
}, - "shops": null
}, - {
- "id": "d7542ec5-558f-4e98-9ff6-e049b24798fa",
- "channel": "data_shop",
- "licensing": {
- "period": "P90D",
- "license": {
- "name": "narrative opendata license"
}
}, - "pricing": {
- "type": "per_record",
- "micro_cents_usd": 50000
}, - "shops": null
}, - {
- "id": "5d52d8d8-b683-4ef4-9220-31347dc2237f",
- "channel": "data_shop",
- "licensing": {
- "period": "P90D",
- "license": {
- "name": "narrative opendata license"
}
}, - "pricing": {
- "type": "max_price_per_record",
- "micro_cents_usd": 30000
}, - "shops": [
- "only.on.tld.com"
]
}
], - "data_rules": {
- "column_sets": [
- {
- "dataset_id": 99999,
- "fields": [
- {
- "field": "col1",
- "filter": null,
- "exported": true
}, - {
- "field": "col2",
- "filter": "include_all_values_including_nulls_filter",
- "exported": true
}, - {
- "field": "col3",
- "filter": "include_only_if_not_null_filter",
- "exported": true
}, - {
- "field": "col4",
- "filter": {
- "type": "include",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col5",
- "filter": {
- "type": "exclude",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": {
- "type": "inclusive",
- "value": "-100"
}, - "max": {
- "type": "inclusive",
- "value": "100"
}
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": null,
- "max": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": false
}, - {
- "field": "col7",
- "filter": {
- "type": "include",
- "list": [
- "true"
]
}, - "exported": true
}, - {
- "field": "col8",
- "filter": {
- "recency": "P30D",
- "from": null,
- "to": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": true
}
]
}
], - "attributes": [
- {
- "attribute_id": 123,
- "fields": [
- {
- "field": "col1",
- "filter": null,
- "exported": true
}, - {
- "field": "col2",
- "filter": "include_all_values_including_nulls_filter",
- "exported": true
}, - {
- "field": "col3",
- "filter": "include_only_if_not_null_filter",
- "exported": true
}, - {
- "field": "col4",
- "filter": {
- "type": "include",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col5",
- "filter": {
- "type": "exclude",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": {
- "type": "inclusive",
- "value": "-100"
}, - "max": {
- "type": "inclusive",
- "value": "100"
}
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": null,
- "max": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": false
}, - {
- "field": "col7",
- "filter": {
- "type": "include",
- "list": [
- "true"
]
}, - "exported": true
}, - {
- "field": "col8",
- "filter": {
- "recency": "P30D",
- "from": null,
- "to": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": true
}, - {
- "field": "col9",
- "filter": {
- "expressions": [
- "col9 > -90",
- "col9 < 90"
]
}, - "exported": true
}
], - "optional": true
}, - {
- "attribute_id": 321,
- "fields": [
- {
- "field": "col9",
- "filter": {
- "expressions": [
- "col9 > -90",
- "col9 < 90"
]
}, - "exported": false
}
], - "optional": false
}
], - "deduplication": {
- "period": "P60D",
- "column_references": null,
- "attribute_references": [
- {
- "attribute_id": 123,
- "column_names": [
- "col9",
- "col9.foo.bar"
]
}
]
}, - "frequency_filter": {
- "column_references": null,
- "attribute_references": [
- {
- "attribute_id": 123,
- "column_names": [
- "col9.foo.bar"
]
}
], - "min_inclusive": 2,
- "max_inclusive": 5
}
}, - "auth_rules": {
- "company_constraint": {
- "type": "inclusion",
- "company_ids": [
- 160,
- 1701
]
}
}, - "created_by": 5000,
- "created_at": "2021-06-29T10:58:36.726Z",
- "updated_at": "2021-06-29T10:58:36.726Z",
- "datasets": null
}
]
}
Gets all data-streams available on the data-streams-market matching the given search expression.
Search expressions follow the postgres 'websearch_to_tsquery' specification:
tshirt and apparel or accessories -leather
"find this" -"but not this"
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'
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). |
{- "records": [
- {
- "id": "f94e8803-fc03-4c3e-a3fc-c3ffe3993788",
- "company_id": 100,
- "name": "best data stream name",
- "slug": "this-is-a-slug",
- "content": {
- "description": "Fabulous Data Stream even better than anything out there!",
- "sections": [
- {
- "title": "some title",
- "description": "some description",
- "image": "some-image"
}, - {
- "whatever": "whatever json structure FE would like to have here.",
- "free_form": "json here"
}
]
}, - "tags": [
- "tag1",
- "tag2"
], - "category": "categoryA",
- "offers": [
- {
- "id": "16310512-a8fb-4ce8-aec3-573693067df9",
- "channel": "data_streams_market",
- "licensing": {
- "period": "P90D",
- "license": {
- "name": "narrative opendata license"
}
}, - "pricing": {
- "type": "per_record",
- "micro_cents_usd": 70000
}, - "shops": null
}, - {
- "id": "d7542ec5-558f-4e98-9ff6-e049b24798fa",
- "channel": "data_shop",
- "licensing": {
- "period": "P90D",
- "license": {
- "name": "narrative opendata license"
}
}, - "pricing": {
- "type": "per_record",
- "micro_cents_usd": 50000
}, - "shops": null
}, - {
- "id": "5d52d8d8-b683-4ef4-9220-31347dc2237f",
- "channel": "data_shop",
- "licensing": {
- "period": "P90D",
- "license": {
- "name": "narrative opendata license"
}
}, - "pricing": {
- "type": "max_price_per_record",
- "micro_cents_usd": 30000
}, - "shops": [
- "only.on.tld.com"
]
}
], - "data_rules": {
- "column_sets": [
- {
- "dataset_id": 99999,
- "fields": [
- {
- "field": "col1",
- "filter": null,
- "exported": true
}, - {
- "field": "col2",
- "filter": "include_all_values_including_nulls_filter",
- "exported": true
}, - {
- "field": "col3",
- "filter": "include_only_if_not_null_filter",
- "exported": true
}, - {
- "field": "col4",
- "filter": {
- "type": "include",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col5",
- "filter": {
- "type": "exclude",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": {
- "type": "inclusive",
- "value": "-100"
}, - "max": {
- "type": "inclusive",
- "value": "100"
}
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": null,
- "max": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": false
}, - {
- "field": "col7",
- "filter": {
- "type": "include",
- "list": [
- "true"
]
}, - "exported": true
}, - {
- "field": "col8",
- "filter": {
- "recency": "P30D",
- "from": null,
- "to": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": true
}
]
}
], - "attributes": [
- {
- "attribute_id": 123,
- "fields": [
- {
- "field": "col1",
- "filter": null,
- "exported": true
}, - {
- "field": "col2",
- "filter": "include_all_values_including_nulls_filter",
- "exported": true
}, - {
- "field": "col3",
- "filter": "include_only_if_not_null_filter",
- "exported": true
}, - {
- "field": "col4",
- "filter": {
- "type": "include",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col5",
- "filter": {
- "type": "exclude",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": {
- "type": "inclusive",
- "value": "-100"
}, - "max": {
- "type": "inclusive",
- "value": "100"
}
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": null,
- "max": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": false
}, - {
- "field": "col7",
- "filter": {
- "type": "include",
- "list": [
- "true"
]
}, - "exported": true
}, - {
- "field": "col8",
- "filter": {
- "recency": "P30D",
- "from": null,
- "to": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": true
}, - {
- "field": "col9",
- "filter": {
- "expressions": [
- "col9 > -90",
- "col9 < 90"
]
}, - "exported": true
}
], - "optional": true
}, - {
- "attribute_id": 321,
- "fields": [
- {
- "field": "col9",
- "filter": {
- "expressions": [
- "col9 > -90",
- "col9 < 90"
]
}, - "exported": false
}
], - "optional": false
}
], - "deduplication": {
- "period": "P60D",
- "column_references": null,
- "attribute_references": [
- {
- "attribute_id": 123,
- "column_names": [
- "col9",
- "col9.foo.bar"
]
}
]
}, - "frequency_filter": {
- "column_references": null,
- "attribute_references": [
- {
- "attribute_id": 123,
- "column_names": [
- "col9.foo.bar"
]
}
], - "min_inclusive": 2,
- "max_inclusive": 5
}
}, - "auth_rules": {
- "company_constraint": {
- "type": "inclusion",
- "company_ids": [
- 160,
- 1701
]
}
}, - "created_by": 5000,
- "created_at": "2021-06-29T10:58:36.726Z",
- "updated_at": "2021-06-29T10:58:36.726Z",
- "datasets": null
}
]
}
Get contracts with details paginated.
per_page | integer Number of records to return. |
offset | integer Number of records to skip (it's usually page_number * per_page). |
{- "records": [
- {
- "contract": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "payable_company_id": 0,
- "payment_method": {
- "type": "credit_card"
}, - "internal_notes": "string",
- "revision": 0,
- "revision_notes": "string",
- "revision_start": "2019-08-24T14:15:22Z",
- "revision_end": "2019-08-24T14:15:22Z",
- "updated_by": 0,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}, - "rates": [
- {
- "rate": {
- "type": "per_unit",
- "unit_price": {
- "value": 0,
- "expressed_in": "cents",
- "currency": "USD"
}
}, - "product": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "sku": "string",
- "sku_type": {
- "category": "processing"
}, - "payable_company_id": 0,
- "name": "string",
- "unit": "string",
- "status": "active"
}, - "start_at": "2019-08-24T14:15:22Z",
- "end_at": "2019-08-24T14:15:22Z",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
]
}
]
}
Create a new contract with rates
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 |
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 |
{- "company_id": 0,
- "payment_method": {
- "type": "credit_card"
}, - "rates": [
- {
- "product_id": "0d012afa-f885-4e65-aeca-37e27701e2d1",
- "sku": "string",
- "end": "2019-08-24T14:15:22Z",
- "rate": {
- "type": "per_unit",
- "unit_price": {
- "value": 0,
- "expressed_in": "cents",
- "currency": "USD"
}
}
}
], - "start": "2019-08-24T14:15:22Z",
- "end": "2019-08-24T14:15:22Z",
- "internal_notes": "string",
- "revision_notes": "string"
}
{- "createdContract": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "payable_company_id": 0,
- "payment_method": {
- "type": "credit_card"
}, - "internal_notes": "string",
- "revision": 0,
- "revision_notes": "string",
- "revision_start": "2019-08-24T14:15:22Z",
- "revision_end": "2019-08-24T14:15:22Z",
- "updated_by": 0,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}, - "createdRates": [
- {
- "contract_id": "9aafc1a8-e497-46c9-ba0b-bd5b03c353e4",
- "contract_revision": 0,
- "product_id": "0d012afa-f885-4e65-aeca-37e27701e2d1",
- "rate": {
- "type": "per_unit",
- "unit_price": {
- "value": 0,
- "expressed_in": "cents",
- "currency": "USD"
}
}, - "start_at": "2019-08-24T14:15:22Z",
- "end_at": "2019-08-24T14:15:22Z",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
]
}
Update active contract for a company
company_id required | number Example: 123 Unique identifier for a company. |
start | string <date-time> Start date of a contract. If not specified it will be set to |
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 |
{- "start": "2019-08-24T14:15:22Z",
- "end": "2019-08-24T14:15:22Z",
- "payment_method": {
- "type": "credit_card"
}, - "rates": [
- {
- "product_id": "0d012afa-f885-4e65-aeca-37e27701e2d1",
- "sku": "string",
- "end": "2019-08-24T14:15:22Z",
- "rate": {
- "type": "per_unit",
- "unit_price": {
- "value": 0,
- "expressed_in": "cents",
- "currency": "USD"
}
}
}
], - "internal_notes": "string",
- "revision_notes": "string"
}
{- "createdContract": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "payable_company_id": 0,
- "payment_method": {
- "type": "credit_card"
}, - "internal_notes": "string",
- "revision": 0,
- "revision_notes": "string",
- "revision_start": "2019-08-24T14:15:22Z",
- "revision_end": "2019-08-24T14:15:22Z",
- "updated_by": 0,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}, - "createdRates": [
- {
- "contract_id": "9aafc1a8-e497-46c9-ba0b-bd5b03c353e4",
- "contract_revision": 0,
- "product_id": "0d012afa-f885-4e65-aeca-37e27701e2d1",
- "rate": {
- "type": "per_unit",
- "unit_price": {
- "value": 0,
- "expressed_in": "cents",
- "currency": "USD"
}
}, - "start_at": "2019-08-24T14:15:22Z",
- "end_at": "2019-08-24T14:15:22Z",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
]
}
Return single contract with details by id and revision.
revision required | number Example: 1 Contract revision |
contract_id required | string <uuid> Example: ea9dddd2-e3ee-40b5-b03e-c3cd37c8a6f0 Unique identifier for a contract. |
{- "contract": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "payable_company_id": 0,
- "payment_method": {
- "type": "credit_card"
}, - "internal_notes": "string",
- "revision": 0,
- "revision_notes": "string",
- "revision_start": "2019-08-24T14:15:22Z",
- "revision_end": "2019-08-24T14:15:22Z",
- "updated_by": 0,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}, - "rates": [
- {
- "rate": {
- "type": "per_unit",
- "unit_price": {
- "value": 0,
- "expressed_in": "cents",
- "currency": "USD"
}
}, - "product": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "sku": "string",
- "sku_type": {
- "category": "processing"
}, - "payable_company_id": 0,
- "name": "string",
- "unit": "string",
- "status": "active"
}, - "start_at": "2019-08-24T14:15:22Z",
- "end_at": "2019-08-24T14:15:22Z",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
]
}
Return active contract with details for a company id.
company_id required | number Example: 123 Unique identifier for a company. |
{- "contract": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "payable_company_id": 0,
- "payment_method": {
- "type": "credit_card"
}, - "internal_notes": "string",
- "revision": 0,
- "revision_notes": "string",
- "revision_start": "2019-08-24T14:15:22Z",
- "revision_end": "2019-08-24T14:15:22Z",
- "updated_by": 0,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}, - "rates": [
- {
- "rate": {
- "type": "per_unit",
- "unit_price": {
- "value": 0,
- "expressed_in": "cents",
- "currency": "USD"
}
}, - "product": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "sku": "string",
- "sku_type": {
- "category": "processing"
}, - "payable_company_id": 0,
- "name": "string",
- "unit": "string",
- "status": "active"
}, - "start_at": "2019-08-24T14:15:22Z",
- "end_at": "2019-08-24T14:15:22Z",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
]
}
Return all rates for a active contract for company_id
company_id required | number Example: 123 Unique identifier for a company. |
{- "records": {
- "contract_id": "9aafc1a8-e497-46c9-ba0b-bd5b03c353e4",
- "contract_revision": 0,
- "product_id": "0d012afa-f885-4e65-aeca-37e27701e2d1",
- "rate": {
- "type": "per_unit",
- "unit_price": {
- "value": 0,
- "expressed_in": "cents",
- "currency": "USD"
}
}, - "start_at": "2019-08-24T14:15:22Z",
- "end_at": "2019-08-24T14:15:22Z",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
}
Return all contract with details for a company id. Company id is extracted from token.
{- "records": [
- {
- "contract": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "payable_company_id": 0,
- "payment_method": {
- "type": "credit_card"
}, - "internal_notes": "string",
- "revision": 0,
- "revision_notes": "string",
- "revision_start": "2019-08-24T14:15:22Z",
- "revision_end": "2019-08-24T14:15:22Z",
- "updated_by": 0,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}, - "rates": [
- {
- "rate": {
- "type": "per_unit",
- "unit_price": {
- "value": 0,
- "expressed_in": "cents",
- "currency": "USD"
}
}, - "product": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "sku": "string",
- "sku_type": {
- "category": "processing"
}, - "payable_company_id": 0,
- "name": "string",
- "unit": "string",
- "status": "active"
}, - "start_at": "2019-08-24T14:15:22Z",
- "end_at": "2019-08-24T14:15:22Z",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
]
}
]
}
Return active contract with details for a company id. Company id is extracted from token.
{- "contract": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "payable_company_id": 0,
- "payment_method": {
- "type": "credit_card"
}, - "internal_notes": "string",
- "revision": 0,
- "revision_notes": "string",
- "revision_start": "2019-08-24T14:15:22Z",
- "revision_end": "2019-08-24T14:15:22Z",
- "updated_by": 0,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}, - "rates": [
- {
- "rate": {
- "type": "per_unit",
- "unit_price": {
- "value": 0,
- "expressed_in": "cents",
- "currency": "USD"
}
}, - "product": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "sku": "string",
- "sku_type": {
- "category": "processing"
}, - "payable_company_id": 0,
- "name": "string",
- "unit": "string",
- "status": "active"
}, - "start_at": "2019-08-24T14:15:22Z",
- "end_at": "2019-08-24T14:15:22Z",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
]
}
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.
Return all datasets belonging to the authenticated company.
{- "records": [
- {
- "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",
- "retention_policy": {
- "type": "retain_everything"
}, - "schema": {
- "file_config": {
- "type": "flat",
- "delimiter": ",",
- "escape": "\"",
- "header": true,
- "quote": "\""
}, - "type": "object",
- "properties": {
- "idValue": {
- "display_name": "Id Value",
- "order": 0,
- "approximate_cardinality": 100000,
- "description": "ID values",
- "type": "string"
}, - "idType": {
- "display_name": "Id Type",
- "order": 1,
- "approximate_cardinality": 1,
- "type": "string",
- "enum": [
- "md5_email",
- "sha256_email"
]
}, - "eventTimestamp": {
- "display_name": "Event TS",
- "order": 2,
- "description": "When the observation was collected",
- "type": "timestamptz",
- "validations": [
- "eventTimestamp < current_timestamp()"
]
}, - "countryCode": {
- "display_name": "countryCode",
- "order": 3,
- "approximate_cardinality": 6,
- "description": "The country of residence of the individual",
- "type": "string"
}, - "age": {
- "display_name": "Age",
- "order": 4,
- "approximate_cardinality": 90,
- "description": "How old this individual is in years",
- "type": "long"
}, - "birthInfo": {
- "display_name": "birth info",
- "order": 5,
- "description": "The year this individual was born",
- "type": "double"
}
}, - "required": [
- "idValue",
- "idType",
- "eventTimestamp",
- "countryCode",
- "age"
], - "primary": "/age"
}, - "status": "active",
- "tags": [
- "age",
- "demo",
- "demographic",
- "demographics"
], - "updated_at": "2021-06-24T00:54:40.029056Z",
- "write_mode": "append",
- "subscription_id": "123e4567-e89b-12d3-a456-426614174000"
}
]
}
Create a new dataset.
Newly created datasets are in the pending
status and require activation.
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.
|
derive_metrics_config | boolean (DeriveMetricsConfig) A flag to enable derivation of the config. |
{- "description": "Mobile identifiers tied to birth information provided as part of app registration.",
- "name": "Declared_Age",
- "schema": {
- "file_config": {
- "type": "flat",
- "delimiter": ",",
- "escape": "\"",
- "header": true,
- "quote": "\""
}, - "type": "object",
- "properties": {
- "idValue": {
- "approximate_cardinality": 100000,
- "description": "ID values",
- "type": "string"
}, - "idType": {
- "approximate_cardinality": 1,
- "type": "string",
- "enum": [
- "md5_email",
- "sha256_email"
]
}, - "eventTimestamp": {
- "description": "When the observation was collected",
- "type": "timestamptz",
- "validations": [
- "eventTimestamp < current_timestamp()"
]
}, - "countryCode": {
- "approximate_cardinality": 6,
- "description": "The country of residence of the individual",
- "type": "string"
}, - "age": {
- "approximate_cardinality": 90,
- "description": "How old this individual is in years",
- "type": "long"
}, - "birthInfo": {
- "description": "The year this individual was born",
- "type": "double"
}
}, - "required": [
- "idValue",
- "idType",
- "eventTimestamp",
- "countryCode",
- "age"
], - "primary": "/age"
}, - "tags": [
- "age",
- "demo",
- "demographic",
- "demographics"
], - "derive_metrics_config": true
}
{- "id": 18923,
- "company_id": 382,
- "created_at": "2021-06-24T00:54:40.029056Z",
- "description": "Mobile identifiers tied to birth information provided as part of app registration.",
- "name": "declared_age",
- "display_name": "Declared Age",
- "schema": {
- "file_config": {
- "type": "flat",
- "delimiter": ",",
- "escape": "\"",
- "header": true,
- "quote": "\""
}, - "type": "object",
- "properties": {
- "idValue": {
- "display_name": "id value",
- "order": 0,
- "approximate_cardinality": 100000,
- "description": "ID values",
- "type": "string"
}, - "idType": {
- "display_name": "id type",
- "order": 1,
- "approximate_cardinality": 1,
- "type": "string",
- "enum": [
- "md5_email",
- "sha256_email"
]
}, - "eventTimestamp": {
- "display_name": "event timestamp",
- "order": 2,
- "description": "When the observation was collected",
- "type": "timestamptz",
- "validations": [
- "eventTimestamp < current_timestamp()"
]
}, - "countryCode": {
- "display_name": "country code",
- "order": 3,
- "approximate_cardinality": 6,
- "description": "The country of residence of the individual",
- "type": "string"
}, - "age": {
- "display_name": "age",
- "order": 4,
- "approximate_cardinality": 90,
- "description": "How old this individual is in years",
- "type": "long"
}, - "birthInfo": {
- "display_name": "birth info",
- "order": 5,
- "description": "The year this individual was born",
- "type": "double"
}
}, - "required": [
- "idValue",
- "idType",
- "eventTimestamp",
- "countryCode",
- "age"
], - "primary": "/age"
}, - "status": "active",
- "tags": [
- "age",
- "demo",
- "demographic",
- "demographics"
], - "updated_at": "2021-06-24T00:54:40.029056Z",
- "write_mode": "append",
- "subscription_id": "123e4567-e89b-12d3-a456-426614174000",
- "last_snapshot_created_at": "2023-06-09T16:51:34.215Z",
- "stats": {
- "est_total_dataset_stored_files": 10,
- "est_total_dataset_stored_records": 500059,
- "est_total_dataset_stored_bytes": 4206454,
- "active_dataset_stored_files": 10,
- "active_dataset_stored_records": 500059,
- "active_dataset_stored_bytes": 4206454,
- "last_snapshot_added_files": 2,
- "last_snapshot_added_records": 499999,
- "last_snapshot_deleted_records": 0,
- "last_snapshot_added_bytes": 4193500,
- "last_snapshot_deleted_files": 0,
- "last_snapshot_added_delete_files": 0,
- "last_snapshot_removed_delete_files": 0,
- "last_snapshot_removed_bytes": 0
}
}
Update existing dataset.
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.
|
derive_metrics_config | boolean (DeriveMetricsConfig) A flag to enable derivation of the config. |
{- "description": "Mobile identifiers tied to birth information provided as part of app registration.",
- "name": "Declared_Age",
- "schema": {
- "file_config": {
- "type": "flat",
- "delimiter": ",",
- "escape": "\"",
- "header": true,
- "quote": "\""
}, - "type": "object",
- "properties": {
- "idValue": {
- "approximate_cardinality": 100000,
- "description": "ID values",
- "type": "string"
}, - "idType": {
- "approximate_cardinality": 1,
- "type": "string",
- "enum": [
- "md5_email",
- "sha256_email"
]
}, - "eventTimestamp": {
- "description": "When the observation was collected",
- "type": "timestamptz",
- "validations": [
- "eventTimestamp < current_timestamp()"
]
}, - "countryCode": {
- "approximate_cardinality": 6,
- "description": "The country of residence of the individual",
- "type": "string"
}, - "age": {
- "approximate_cardinality": 90,
- "description": "How old this individual is in years",
- "type": "long"
}, - "birthInfo": {
- "description": "The year this individual was born",
- "type": "double"
}
}, - "required": [
- "idValue",
- "idType",
- "eventTimestamp",
- "countryCode",
- "age"
], - "primary": "/age"
}, - "tags": [
- "age",
- "demo",
- "demographic",
- "demographics"
], - "derive_metrics_config": true
}
{- "id": 18923,
- "company_id": 382,
- "created_at": "2021-06-24T00:54:40.029056Z",
- "description": "Mobile identifiers tied to birth information provided as part of app registration.",
- "name": "declared_age",
- "display_name": "Declared Age",
- "schema": {
- "file_config": {
- "type": "flat",
- "delimiter": ",",
- "escape": "\"",
- "header": true,
- "quote": "\""
}, - "type": "object",
- "properties": {
- "idValue": {
- "display_name": "id value",
- "order": 0,
- "approximate_cardinality": 100000,
- "description": "ID values",
- "type": "string"
}, - "idType": {
- "display_name": "id type",
- "order": 1,
- "approximate_cardinality": 1,
- "type": "string",
- "enum": [
- "md5_email",
- "sha256_email"
]
}, - "eventTimestamp": {
- "display_name": "event timestamp",
- "order": 2,
- "description": "When the observation was collected",
- "type": "timestamptz",
- "validations": [
- "eventTimestamp < current_timestamp()"
]
}, - "countryCode": {
- "display_name": "country code",
- "order": 3,
- "approximate_cardinality": 6,
- "description": "The country of residence of the individual",
- "type": "string"
}, - "age": {
- "display_name": "age",
- "order": 4,
- "approximate_cardinality": 90,
- "description": "How old this individual is in years",
- "type": "long"
}, - "birthInfo": {
- "display_name": "birth info",
- "order": 5,
- "description": "The year this individual was born",
- "type": "double"
}
}, - "required": [
- "idValue",
- "idType",
- "eventTimestamp",
- "countryCode",
- "age"
], - "primary": "/age"
}, - "status": "active",
- "tags": [
- "age",
- "demo",
- "demographic",
- "demographics"
], - "updated_at": "2021-06-24T00:54:40.029056Z",
- "write_mode": "append",
- "subscription_id": "123e4567-e89b-12d3-a456-426614174000",
- "last_snapshot_created_at": "2023-06-09T16:51:34.215Z",
- "stats": {
- "est_total_dataset_stored_files": 10,
- "est_total_dataset_stored_records": 500059,
- "est_total_dataset_stored_bytes": 4206454,
- "active_dataset_stored_files": 10,
- "active_dataset_stored_records": 500059,
- "active_dataset_stored_bytes": 4206454,
- "last_snapshot_added_files": 2,
- "last_snapshot_added_records": 499999,
- "last_snapshot_deleted_records": 0,
- "last_snapshot_added_bytes": 4193500,
- "last_snapshot_deleted_files": 0,
- "last_snapshot_added_delete_files": 0,
- "last_snapshot_removed_delete_files": 0,
- "last_snapshot_removed_bytes": 0
}
}
dataset_id required | integer Unique identifier for a dataset. |
{- "id": 18923,
- "company_id": 382,
- "created_at": "2021-06-24T00:54:40.029056Z",
- "description": "Mobile identifiers tied to birth information provided as part of app registration.",
- "name": "declared_age",
- "display_name": "Declared Age",
- "schema": {
- "file_config": {
- "type": "flat",
- "delimiter": ",",
- "escape": "\"",
- "header": true,
- "quote": "\""
}, - "type": "object",
- "properties": {
- "idValue": {
- "display_name": "id value",
- "order": 0,
- "approximate_cardinality": 100000,
- "description": "ID values",
- "type": "string"
}, - "idType": {
- "display_name": "id type",
- "order": 1,
- "approximate_cardinality": 1,
- "type": "string",
- "enum": [
- "md5_email",
- "sha256_email"
]
}, - "eventTimestamp": {
- "display_name": "event timestamp",
- "order": 2,
- "description": "When the observation was collected",
- "type": "timestamptz",
- "validations": [
- "eventTimestamp < current_timestamp()"
]
}, - "countryCode": {
- "display_name": "country code",
- "order": 3,
- "approximate_cardinality": 6,
- "description": "The country of residence of the individual",
- "type": "string"
}, - "age": {
- "display_name": "age",
- "order": 4,
- "approximate_cardinality": 90,
- "description": "How old this individual is in years",
- "type": "long"
}, - "birthInfo": {
- "display_name": "birth info",
- "order": 5,
- "description": "The year this individual was born",
- "type": "double"
}
}, - "required": [
- "idValue",
- "idType",
- "eventTimestamp",
- "countryCode",
- "age"
], - "primary": "/age"
}, - "status": "active",
- "tags": [
- "age",
- "demo",
- "demographic",
- "demographics"
], - "updated_at": "2021-06-24T00:54:40.029056Z",
- "write_mode": "append",
- "subscription_id": "123e4567-e89b-12d3-a456-426614174000",
- "last_snapshot_created_at": "2023-06-09T16:51:34.215Z",
- "stats": {
- "est_total_dataset_stored_files": 10,
- "est_total_dataset_stored_records": 500059,
- "est_total_dataset_stored_bytes": 4206454,
- "active_dataset_stored_files": 10,
- "active_dataset_stored_records": 500059,
- "active_dataset_stored_bytes": 4206454,
- "last_snapshot_added_files": 2,
- "last_snapshot_added_records": 499999,
- "last_snapshot_deleted_records": 0,
- "last_snapshot_added_bytes": 4193500,
- "last_snapshot_deleted_files": 0,
- "last_snapshot_added_delete_files": 0,
- "last_snapshot_removed_delete_files": 0,
- "last_snapshot_removed_bytes": 0
}
}
Permanently removes a dataset from the platform.
Dataset deletion cannot be undone.
dataset_id required | integer Unique identifier for a dataset. |
X-Narrative-Retention-Days | string A number of days between 1 and 30. Defaults to 30. |
{- "error": "Unauthorized",
- "error_description": "You are not authorized to use this endpoint."
}
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.
dataset_id required | integer Unique identifier for a dataset. |
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.
|
{- "description": "Mobile identifiers tied to birth information provided as part of app registration.",
- "name": "declared_age",
- "display_name": "Declared Age",
- "schema": {
- "file_config": {
- "type": "flat",
- "delimiter": ",",
- "escape": "\"",
- "header": true,
- "quote": "\""
}, - "type": "object",
- "properties": {
- "idValue": {
- "approximate_cardinality": 100000,
- "description": "ID values",
- "type": "string"
}, - "idType": {
- "approximate_cardinality": 1,
- "type": "string",
- "enum": [
- "md5_email",
- "sha256_email"
]
}, - "eventTimestamp": {
- "description": "When the observation was collected",
- "type": "timestamptz",
- "validations": [
- "eventTimestamp < current_timestamp()"
]
}, - "countryCode": {
- "approximate_cardinality": 6,
- "description": "The country of residence of the individual",
- "type": "string"
}, - "age": {
- "approximate_cardinality": 90,
- "description": "How old this individual is in years",
- "type": "long"
}, - "birthInfo": {
- "description": "The year this individual was born",
- "type": "double"
}
}, - "required": [
- "idValue",
- "idType",
- "eventTimestamp",
- "countryCode",
- "age"
], - "primary": "/age"
}, - "tags": [
- "age",
- "demo",
- "demographic",
- "demographics"
]
}
{- "id": 18923,
- "company_id": 382,
- "created_at": "2021-06-24T00:54:40.029056Z",
- "description": "Mobile identifiers tied to birth information provided as part of app registration.",
- "name": "declared_age",
- "display_name": "Declared Age",
- "schema": {
- "file_config": {
- "type": "flat",
- "delimiter": ",",
- "escape": "\"",
- "header": true,
- "quote": "\""
}, - "type": "object",
- "properties": {
- "idValue": {
- "display_name": "id value",
- "order": 0,
- "approximate_cardinality": 100000,
- "description": "ID values",
- "type": "string"
}, - "idType": {
- "display_name": "id type",
- "order": 1,
- "approximate_cardinality": 1,
- "type": "string",
- "enum": [
- "md5_email",
- "sha256_email"
]
}, - "eventTimestamp": {
- "display_name": "event timestamp",
- "order": 2,
- "description": "When the observation was collected",
- "type": "timestamptz",
- "validations": [
- "eventTimestamp < current_timestamp()"
]
}, - "countryCode": {
- "display_name": "country code",
- "order": 3,
- "approximate_cardinality": 6,
- "description": "The country of residence of the individual",
- "type": "string"
}, - "age": {
- "display_name": "age",
- "order": 4,
- "approximate_cardinality": 90,
- "description": "How old this individual is in years",
- "type": "long"
}, - "birthInfo": {
- "display_name": "birth info",
- "order": 5,
- "description": "The year this individual was born",
- "type": "double"
}
}, - "required": [
- "idValue",
- "idType",
- "eventTimestamp",
- "countryCode",
- "age"
], - "primary": "/age"
}, - "status": "active",
- "tags": [
- "age",
- "demo",
- "demographic",
- "demographics"
], - "updated_at": "2021-06-24T00:54:40.029056Z",
- "write_mode": "append",
- "subscription_id": "123e4567-e89b-12d3-a456-426614174000",
- "last_snapshot_created_at": "2023-06-09T16:51:34.215Z",
- "stats": {
- "est_total_dataset_stored_files": 10,
- "est_total_dataset_stored_records": 500059,
- "est_total_dataset_stored_bytes": 4206454,
- "active_dataset_stored_files": 10,
- "active_dataset_stored_records": 500059,
- "active_dataset_stored_bytes": 4206454,
- "last_snapshot_added_files": 2,
- "last_snapshot_added_records": 499999,
- "last_snapshot_deleted_records": 0,
- "last_snapshot_added_bytes": 4193500,
- "last_snapshot_deleted_files": 0,
- "last_snapshot_added_delete_files": 0,
- "last_snapshot_removed_delete_files": 0,
- "last_snapshot_removed_bytes": 0
}
}
Get a sample of rows from a dataset as JSON.
dataset_id required | integer Unique identifier for a dataset. |
size | integer ( 0 .. 1000 ] The number of rows to sample from the dataset. |
{- "records": [
- {
- "idValue": "9a200747-86ea-4ab3-a5c5-ce384e4f93dc",
- "idType": "ADID",
- "timestamp": "2021-12-10T00:00:00Z"
}, - {
- "idValue": "6657fa10-4e5f-4ff5-8e46-53ffb1df692f",
- "idType": "ADID",
- "timestamp": "2021-12-10T00:00:01Z"
}
]
}
Get a dataset including information about the backing Iceberg table.
dataset_id required | integer Unique identifier for a dataset. |
{- "id": 18923,
- "company_id": 382,
- "created_at": "2021-06-24T00:54:40.029056Z",
- "description": "Mobile identifiers tied to birth information provided as part of app registration.",
- "name": "declared_age",
- "display_name": "Declared Age",
- "schema": {
- "file_config": {
- "type": "flat",
- "delimiter": ",",
- "escape": "\"",
- "header": true,
- "quote": "\""
}, - "type": "object",
- "properties": {
- "idValue": {
- "display_name": "id value",
- "order": 0,
- "approximate_cardinality": 100000,
- "description": "ID values",
- "type": "string"
}, - "idType": {
- "display_name": "id type",
- "order": 1,
- "approximate_cardinality": 1,
- "type": "string",
- "enum": [
- "md5_email",
- "sha256_email"
]
}, - "eventTimestamp": {
- "display_name": "event timestamp",
- "order": 2,
- "description": "When the observation was collected",
- "type": "timestamptz",
- "validations": [
- "eventTimestamp < current_timestamp()"
]
}, - "countryCode": {
- "display_name": "country code",
- "order": 3,
- "approximate_cardinality": 6,
- "description": "The country of residence of the individual",
- "type": "string"
}, - "age": {
- "display_name": "age",
- "order": 4,
- "approximate_cardinality": 90,
- "description": "How old this individual is in years",
- "type": "long"
}, - "birthInfo": {
- "display_name": "birth info",
- "order": 5,
- "description": "The year this individual was born",
- "type": "double"
}
}, - "required": [
- "idValue",
- "idType",
- "eventTimestamp",
- "countryCode",
- "age"
], - "primary": "/age"
}, - "status": "active",
- "tags": [
- "age",
- "demo",
- "demographic",
- "demographics"
], - "updated_at": "2021-06-24T00:54:40.029056Z",
- "write_mode": "append",
- "subscription_id": "123e4567-e89b-12d3-a456-426614174000",
- "last_snapshot_created_at": "2023-06-09T16:51:34.215Z",
- "stats": {
- "est_total_dataset_stored_files": 10,
- "est_total_dataset_stored_records": 500059,
- "est_total_dataset_stored_bytes": 4206454,
- "active_dataset_stored_files": 10,
- "active_dataset_stored_records": 500059,
- "active_dataset_stored_bytes": 4206454,
- "last_snapshot_added_files": 2,
- "last_snapshot_added_records": 499999,
- "last_snapshot_deleted_records": 0,
- "last_snapshot_added_bytes": 4193500,
- "last_snapshot_deleted_files": 0,
- "last_snapshot_added_delete_files": 0,
- "last_snapshot_removed_delete_files": 0,
- "last_snapshot_removed_bytes": 0
}, - "table": { }
}
Get a sample of rows from a dataset as JSON.
dataset_id required | integer Unique identifier for a dataset. |
size | integer ( 0 .. 1000 ] The number of rows to sample from the dataset. |
{- "records": [
- {
- "idValue": "9a200747-86ea-4ab3-a5c5-ce384e4f93dc",
- "idType": "ADID",
- "timestamp": "2021-12-10T00:00:00Z"
}, - {
- "idValue": "6657fa10-4e5f-4ff5-8e46-53ffb1df692f",
- "idType": "ADID",
- "timestamp": "2021-12-10T00:00:01Z"
}
]
}
Update the partition specification of the Iceberg table backing the dataset.
See:
dataset_id required | integer Unique identifier for a dataset. |
required | Array of PartitionSpecAddField (object) or PartitionSpecRemoveField (object) (PartitionSpecUpdate) |
{- "updates": [
- {
- "type": "add",
- "field": "id.value",
- "transform": "bucket[128]"
}, - {
- "type": "remove",
- "field": "__NARRATIVE_DEFAULT_PARTITION___bucket"
}
]
}
{- "id": 18923,
- "company_id": 382,
- "created_at": "2021-06-24T00:54:40.029056Z",
- "description": "Mobile identifiers tied to birth information provided as part of app registration.",
- "name": "declared_age",
- "display_name": "Declared Age",
- "schema": {
- "file_config": {
- "type": "flat",
- "delimiter": ",",
- "escape": "\"",
- "header": true,
- "quote": "\""
}, - "type": "object",
- "properties": {
- "idValue": {
- "display_name": "id value",
- "order": 0,
- "approximate_cardinality": 100000,
- "description": "ID values",
- "type": "string"
}, - "idType": {
- "display_name": "id type",
- "order": 1,
- "approximate_cardinality": 1,
- "type": "string",
- "enum": [
- "md5_email",
- "sha256_email"
]
}, - "eventTimestamp": {
- "display_name": "event timestamp",
- "order": 2,
- "description": "When the observation was collected",
- "type": "timestamptz",
- "validations": [
- "eventTimestamp < current_timestamp()"
]
}, - "countryCode": {
- "display_name": "country code",
- "order": 3,
- "approximate_cardinality": 6,
- "description": "The country of residence of the individual",
- "type": "string"
}, - "age": {
- "display_name": "age",
- "order": 4,
- "approximate_cardinality": 90,
- "description": "How old this individual is in years",
- "type": "long"
}, - "birthInfo": {
- "display_name": "birth info",
- "order": 5,
- "description": "The year this individual was born",
- "type": "double"
}
}, - "required": [
- "idValue",
- "idType",
- "eventTimestamp",
- "countryCode",
- "age"
], - "primary": "/age"
}, - "status": "active",
- "tags": [
- "age",
- "demo",
- "demographic",
- "demographics"
], - "updated_at": "2021-06-24T00:54:40.029056Z",
- "write_mode": "append",
- "subscription_id": "123e4567-e89b-12d3-a456-426614174000",
- "last_snapshot_created_at": "2023-06-09T16:51:34.215Z",
- "stats": {
- "est_total_dataset_stored_files": 10,
- "est_total_dataset_stored_records": 500059,
- "est_total_dataset_stored_bytes": 4206454,
- "active_dataset_stored_files": 10,
- "active_dataset_stored_records": 500059,
- "active_dataset_stored_bytes": 4206454,
- "last_snapshot_added_files": 2,
- "last_snapshot_added_records": 499999,
- "last_snapshot_deleted_records": 0,
- "last_snapshot_added_bytes": 4193500,
- "last_snapshot_deleted_files": 0,
- "last_snapshot_added_delete_files": 0,
- "last_snapshot_removed_delete_files": 0,
- "last_snapshot_removed_bytes": 0
}, - "table": { }
}
Preview snapshot expirations given a retention policy.
dataset_id required | integer Unique identifier for a dataset. |
type | string Value: "expire_everything" |
{- "type": "expire_everything"
}
{- "snapshots_to_expire": [
- {
- "snapshot_id": 8840810861846963000,
- "created_at": "2022-01-28T16:25:47.987Z"
}, - {
- "snapshot_id": 6511121635994506000,
- "created_at": "2022-01-28T16:58:59.264Z"
}, - {
- "snapshot_id": 4359653450296158700,
- "created_at": "2022-01-28T17:33:25.560Z"
}, - {
- "snapshot_id": 7422070807769186000,
- "created_at": "2022-01-28T18:58:45.856Z"
}
]
}
Updates snapshot retention policy
dataset_id required | integer Unique identifier for a dataset. |
type | string Value: "expire_everything" |
{- "type": "expire_everything"
}
{- "id": 18923,
- "company_id": 382,
- "created_at": "2021-06-24T00:54:40.029056Z",
- "description": "Mobile identifiers tied to birth information provided as part of app registration.",
- "name": "declared_age",
- "display_name": "Declared Age",
- "schema": {
- "file_config": {
- "type": "flat",
- "delimiter": ",",
- "escape": "\"",
- "header": true,
- "quote": "\""
}, - "type": "object",
- "properties": {
- "idValue": {
- "display_name": "id value",
- "order": 0,
- "approximate_cardinality": 100000,
- "description": "ID values",
- "type": "string"
}, - "idType": {
- "display_name": "id type",
- "order": 1,
- "approximate_cardinality": 1,
- "type": "string",
- "enum": [
- "md5_email",
- "sha256_email"
]
}, - "eventTimestamp": {
- "display_name": "event timestamp",
- "order": 2,
- "description": "When the observation was collected",
- "type": "timestamptz",
- "validations": [
- "eventTimestamp < current_timestamp()"
]
}, - "countryCode": {
- "display_name": "country code",
- "order": 3,
- "approximate_cardinality": 6,
- "description": "The country of residence of the individual",
- "type": "string"
}, - "age": {
- "display_name": "age",
- "order": 4,
- "approximate_cardinality": 90,
- "description": "How old this individual is in years",
- "type": "long"
}, - "birthInfo": {
- "display_name": "birth info",
- "order": 5,
- "description": "The year this individual was born",
- "type": "double"
}
}, - "required": [
- "idValue",
- "idType",
- "eventTimestamp",
- "countryCode",
- "age"
], - "primary": "/age"
}, - "status": "active",
- "tags": [
- "age",
- "demo",
- "demographic",
- "demographics"
], - "updated_at": "2021-06-24T00:54:40.029056Z",
- "write_mode": "append",
- "subscription_id": "123e4567-e89b-12d3-a456-426614174000",
- "last_snapshot_created_at": "2023-06-09T16:51:34.215Z",
- "stats": {
- "est_total_dataset_stored_files": 10,
- "est_total_dataset_stored_records": 500059,
- "est_total_dataset_stored_bytes": 4206454,
- "active_dataset_stored_files": 10,
- "active_dataset_stored_records": 500059,
- "active_dataset_stored_bytes": 4206454,
- "last_snapshot_added_files": 2,
- "last_snapshot_added_records": 499999,
- "last_snapshot_deleted_records": 0,
- "last_snapshot_added_bytes": 4193500,
- "last_snapshot_deleted_files": 0,
- "last_snapshot_added_delete_files": 0,
- "last_snapshot_removed_delete_files": 0,
- "last_snapshot_removed_bytes": 0
}
}
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.
dataset_id required | integer Unique identifier for a dataset. |
size | integer ( 0 .. 1000 ] The number of rows to sample from the dataset. |
[- {
- "mapping_id": "62db1e99-7e0e-46c3-802b-1b13a0ebdb7b",
- "records": [
- {
- "input": {
- "idType": "idType1",
- "idValue": "idValue1"
}, - "output": {
- "unique_id_95b79302_0f80_4cfd_9e43_ea26aa13b9a7": {
- "type": "idType1"
}
}
}, - {
- "input": {
- "idType": "idType2",
- "idValue": "idValue2"
}, - "output": {
- "unique_id_95b79302_0f80_4cfd_9e43_ea26aa13b9a7": {
- "type": "idType2"
}
}
}
]
}, - {
- "mapping_id": "f2d14fb8-2c9b-4ade-851e-388bfcd942f1",
- "records": [
- {
- "input": {
- "idType": "idType1",
- "idValue": "idValue1"
}, - "output": {
- "unique_id_322d2d83_d8ec_4808_80be_66d08e446de5": {
- "value": "idValue1"
}
}
}, - {
- "input": {
- "idType": "idType2",
- "idValue": "idValue2"
}, - "output": {
- "unique_id_322d2d83_d8ec_4808_80be_66d08e446de5": {
- "value": "idValue2"
}
}
}
]
}
]
Schedule the execution of a mappings suggestion job for a given dataset, using the Rosetta Stone API (Snowflake data plane only).
dataset_id required | integer Unique identifier for a dataset. |
{ }
{- "job_id": "a81e1460-fbdc-4204-bd76-a9e496bf760d"
}
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.
dataset_id required | integer Unique identifier for a dataset. |
all_records | boolean If true will return 100 records. If false, only returns the most recent record.
Pagination api with |
per_page | integer Number of records to return. |
offset | integer Number of records to skip (it's usually page_number * per_page). |
{- "dataset_id": 1,
- "records": [
- {
- "snapshot_id": 1111111111111111200,
- "est_total_dataset_stored_files": 999,
- "est_total_dataset_stored_records": 9999,
- "est_total_dataset_stored_bytes": 999999,
- "active_dataset_stored_files": 999,
- "active_dataset_stored_records": 9999,
- "active_dataset_stored_bytes": 999999,
- "snapshot_added_files": 9,
- "snapshot_added_records": 999,
- "snapshot_deleted_records": 9,
- "snapshot_added_bytes": 9999,
- "snapshot_deleted_files": 9,
- "snapshot_added_delete_files": 9,
- "snapshot_removed_delete_files": 9,
- "snapshot_removed_bytes": 9
}
]
}
Get statistics for each column.
dataset_id required | integer Unique identifier for a dataset. |
histogram_bin_limit | integer > 0 The maximum number of bins to return for the histograms. |
{- "advanced_statistics_metadata": {
- "snapshot_range": {
- "from_snapshot": null,
- "until_snapshot": null,
- "from_snapshot_timestamp": null,
- "until_snapshot_timestamp": null
}, - "configuration": {
- "value_histogram": {
- "columns": [
- "firstName",
- "secondName",
- "firstChars",
- "age"
]
}, - "completeness": {
- "columns": [
- "firstName",
- "secondName",
- "firstChars",
- "age"
]
}, - "approx_count_distinct": {
- "columns": [
- "firstChars",
- "age"
]
}, - "count_distinct": {
- "columns": [
- "firstName",
- "secondName"
]
}, - "observed_types_histogram": {
- "columns": [
- "firstName"
]
}, - "mean": {
- "columns": [
- "age"
]
}, - "deviation": {
- "columns": [
- "age"
]
}
}
}, - "columns_summary": [
- {
- "name": "age",
- "type": "LONG",
- "basic_statistics": {
- "nan_value_count": null,
- "null_value_count": 0,
- "lower_bound": 22,
- "upper_bound": 52,
- "value_count": 60,
- "column_store_bytes": 655
}, - "advanced_statistics": {
- "approx_count_distinct": 13,
- "count_distinct": null,
- "histogram": {
- "values": {
- "22": {
- "absolute": 3,
- "ratio": 0.0667
}, - "25": {
- "absolute": 3,
- "ratio": 0.0667
}, - "28": {
- "absolute": 9,
- "ratio": 0.2
}, - "31": {
- "absolute": 3,
- "ratio": 0.0667
}, - "32": {
- "absolute": 3,
- "ratio": 0.0667
}, - "34": {
- "absolute": 3,
- "ratio": 0.0667
}, - "36": {
- "absolute": 3,
- "ratio": 0.0667
}, - "39": {
- "absolute": 3,
- "ratio": 0.0667
}, - "40": {
- "absolute": 3,
- "ratio": 0.0667
}, - "45": {
- "absolute": 3,
- "ratio": 0.0667
}, - "47": {
- "absolute": 3,
- "ratio": 0.0667
}, - "50": {
- "absolute": 3,
- "ratio": 0.0667
}, - "52": {
- "absolute": 3,
- "ratio": 0.0667
}
}, - "number_of_bins": 13
}, - "mean": 35.8,
- "standard_deviation": 9.064215354899726,
- "completeness": 1,
- "observed_types": null
}
}
]
}
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.
Array of objects |
{- "records": [
- {
- "column_name": "idType",
- "approx_count_distinct": 2,
- "count_distinct": null,
- "histogram": {
- "values": {
- "adid": {
- "absolute": 2,
- "ratio": 0.5
}, - "idfa": {
- "absolute": 2,
- "ratio": 0.5
}
}, - "number_of_bins": 2
}, - "mean": null,
- "standard_deviation": null,
- "completeness": null,
- "observed_types": null
}, - {
- "column_name": "idValue",
- "approx_count_distinct": 20000,
- "count_distinct": null,
- "histogram": null,
- "mean": null,
- "standard_deviation": null,
- "completeness": null,
- "observed_types": null
}
]
}
{- "error": "Unauthorized",
- "error_description": "You are not authorized to use this endpoint."
}
Run recalculation for the dataset.
dataset_id required | integer Unique identifier for a dataset. |
from_snapshot | string Start of the recalculation range |
{- "from_snapshot": "string"
}
{- "recalculation_id": "a81e1460-fbdc-4204-bd76-a9e496bf760d",
- "snapshots": [
- "4396758588236543"
], - "from_snapshot_timestamp": "2023-06-28T19:47:36.604706Z",
- "until_snapshot_timestamp": "2023-06-28T19:47:36.604709Z"
}
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:
dataset_id required | integer Unique identifier for a dataset. |
source_file required | string The file to be ingested. This must be equal to the |
{- "source_file": "/2021-12-01/example.csv"
}
Lists files added by a snapshot
dataset_id required | integer Unique identifier for a dataset. |
snapshot_id required | integer Unique identifier for a snapshot. |
[- {
- "name": "00000-357-27b8ca02-1c02-4761-85e5-5df9694015da-00001.parquet"
}, - {
- "name": "00000-357-27b8ca02-1c02-4761-85e5-5df9694015da-00002.parquet"
}
]
Lists snapshots and associated files
dataset_id required | integer Unique identifier for a dataset. |
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. |
{- "snapshots": [
- {
- "snapshot_id": 1,
- "timestamp": "2023-02-02T14:11:43.324",
- "is_downloadable": true,
- "files": {
- "added": [
- "s3://some-bucket/file1.parquet"
]
}, - "operation": "append"
}
], - "has_next": true,
- "next_snapshot": 0
}
Lists metrics for a dataset
dataset_id required | integer Unique identifier for a dataset. |
{- "value": [
- {
- "value": [
- {
- "columnName": "string",
- "approxCountDistinct": 0,
- "countDistinct": 0,
- "histogram": {
- "values": {
- "property1": {
- "absolute": 0,
- "ratio": 0
}, - "property2": {
- "absolute": 0,
- "ratio": 0
}
}, - "numberOfBins": 0
}, - "mean": 0,
- "standardDeviation": 0,
- "completeness": 0,
- "observedTypes": {
- "values": {
- "property1": {
- "absolute": 0,
- "ratio": 0
}, - "property2": {
- "absolute": 0,
- "ratio": 0
}
}, - "numberOfBins": 0
}
}
]
}
]
}
Metrics for a snapshot
dataset_id required | integer Unique identifier for a dataset. |
snapshot_id required | integer Unique identifier for a snapshot. |
{- "value": [
- {
- "columnName": "string",
- "approxCountDistinct": 0,
- "countDistinct": 0,
- "histogram": {
- "values": {
- "property1": {
- "absolute": 0,
- "ratio": 0
}, - "property2": {
- "absolute": 0,
- "ratio": 0
}
}, - "numberOfBins": 0
}, - "mean": 0,
- "standardDeviation": 0,
- "completeness": 0,
- "observedTypes": {
- "values": {
- "property1": {
- "absolute": 0,
- "ratio": 0
}, - "property2": {
- "absolute": 0,
- "ratio": 0
}
}, - "numberOfBins": 0
}
}
]
}
Put new version of configuration.
dataset_id required | integer Unique identifier for a dataset. |
object (Columns) | |
object (Columns) | |
object (Columns) | |
object (Columns) | |
object (Columns) | |
object (Columns) | |
object (Columns) |
{- "value_histogram": {
- "columns": [
- "string"
]
}, - "completeness": {
- "columns": [
- "string"
]
}, - "approx_count_distinct": {
- "columns": [
- "string"
]
}, - "count_distinct": {
- "columns": [
- "string"
]
}, - "observed_types_histogram": {
- "columns": [
- "string"
]
}, - "mean": {
- "columns": [
- "string"
]
}, - "deviation": {
- "columns": [
- "string"
]
}
}
{- "stream_id": "173fd1b7-72c4-44c4-9244-55a0a167a352",
- "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c"
}
Put new version of configuration.
dataset_id required | integer Unique identifier for a dataset. |
{- "value_histogram": {
- "columns": [
- "string"
]
}, - "completeness": {
- "columns": [
- "string"
]
}, - "approx_count_distinct": {
- "columns": [
- "string"
]
}, - "count_distinct": {
- "columns": [
- "string"
]
}, - "observed_types_histogram": {
- "columns": [
- "string"
]
}, - "mean": {
- "columns": [
- "string"
]
}, - "deviation": {
- "columns": [
- "string"
]
}, - "version": 0,
- "disabled": true
}
Lists snapshots and associated files
dataset_id required | integer Unique identifier for a dataset. |
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. |
{- "files_per_snapshot": [
- {
- "files": [
- {
- "path": "string",
- "size": 0
}
], - "snapshot_id": 0,
- "timestamp": "string",
- "is_downloadable": true
}
], - "has_next": true,
- "next_snapshot": 0
}
Retrieve the download URL for a file
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. |
Creates new request for request derivation
dataset_id required | integer Unique identifier for a dataset. |
cron | string cron expression "for example: @hourly, 0 12 * * 1-5" |
cron_zone_id | 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 | |
object (ExecutionCluster) | |
stats_enabled | 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 |
{- "cron": "@hourly",
- "cron_zone_id": "EST",
- "stats_enabled": false,
- "status": "active"
}
Creates new request for request derivation
dataset_id required | integer Unique identifier for a dataset. |
cron required | string cron expression "for example: @hourly, 0 12 * * 1-5" |
cron_zone_id required | string zone id where the cron should take place "for example: EST, GMT+2" |
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 |
object (ExecutionCluster) | |
stats_enabled | 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 |
{- "cron": "@hourly",
- "cron_zone_id": "EST",
- "stats_enabled": false,
- "status": "active"
}
dataset_id required | integer Unique identifier for a dataset. |
type required | string Enum: "full" "incremental" full will skip progress tracking and run the materialized view from scratch, incremental will use the progress tracking. |
object (ExecutionCluster) |
{- "type": "full",
- "execution_cluster": {
- "type": "dedicated"
}
}
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.
subscription_id | string <uuid> (UUID) |
profile_id | string <uuid> (UUID) |
quick_settings | object |
{- "subscription_id": "21691f26-f308-4e98-896c-579db27da04b",
- "profile_id": "d13867f7-a6c0-4f83-b129-f6c6f2de7c15",
- "quick_settings": {
- "bucket_suffix": "/my-subscription",
- "number_of_files": "5"
}
}
{- "id": "8aaa069b-cc15-486f-9cdc-c56c3d831508",
- "subscription_id": "21691f26-f308-4e98-896c-579db27da04b",
- "profile_id": "d13867f7-a6c0-4f83-b129-f6c6f2de7c15",
- "quick_settings": {
- "bucket_suffix": "/my-subscription",
- "number_of_files": "5"
}
}
destination_id required | string <uuid> Unique identifier for a destination. |
{- "id": "8aaa069b-cc15-486f-9cdc-c56c3d831508",
- "subscription_id": "21691f26-f308-4e98-896c-579db27da04b",
- "profile_id": "d13867f7-a6c0-4f83-b129-f6c6f2de7c15",
- "quick_settings": {
- "bucket_suffix": "/my-subscription",
- "number_of_files": "5"
}
}
destination_id required | string <uuid> Unique identifier for a destination. |
{- "bucket_suffix": "/my-subscription",
- "number_of_files": "5"
}
{- "id": "8aaa069b-cc15-486f-9cdc-c56c3d831508",
- "subscription_id": "21691f26-f308-4e98-896c-579db27da04b",
- "profile_id": "d13867f7-a6c0-4f83-b129-f6c6f2de7c15",
- "quick_settings": {
- "bucket_suffix": "/my-subscription",
- "number_of_files": "5"
}
}
subscription_id required | string <uuid> Unique identifier for a subscription. |
{- "records": [
- {
- "id": "8aaa069b-cc15-486f-9cdc-c56c3d831508",
- "subscription_id": "21691f26-f308-4e98-896c-579db27da04b",
- "profile_id": "d13867f7-a6c0-4f83-b129-f6c6f2de7c15",
- "quick_settings": {
- "bucket_suffix": "/my-subscription",
- "number_of_files": "5"
}
}
]
}
profile_id required | string <uuid> Unique identifier for an app profile. |
{- "records": [
- {
- "id": "8aaa069b-cc15-486f-9cdc-c56c3d831508",
- "subscription_id": "21691f26-f308-4e98-896c-579db27da04b",
- "profile_id": "d13867f7-a6c0-4f83-b129-f6c6f2de7c15",
- "quick_settings": {
- "bucket_suffix": "/my-subscription",
- "number_of_files": "5"
}
}
]
}
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.
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.
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) |
{- "records": [
- {
- "job_id": "2a5b9ad7-dc8f-47bb-8e62-843a38f8054c",
- "request_source": {
- "type": "api_user",
- "company_id": 1,
- "user_id": 407
}, - "state": "completed",
- "type": "materialize-view",
- "input": {
- "nql": "CREATE MATERIALIZED VIEW \"test_stats\" AS SELECT \"value\" FROM \"company_data\".\"10674\"",
- "budget": {
- "amount": {
- "value": 0,
- "currency": "USD"
}, - "period": {
- "type": "calendar_monthly"
}
}, - "dataset_id": 10736,
- "stats_enabled": true,
- "compiled_select": "SELECT\n `ds_10674`.`value`\nFROM\n narrative.datasets.ds_10674 `ds_10674`"
}, - "executor": "job-executor-98e1f48e-bf54-4f11-bbd1-73c445120266",
- "idempotency_key": "10736:29329c64e7b8a4eda86aaabe04872b832ab456b5543d0c259c812525391f158c:669a5f8e4f373c2f907700decde47511aac6470f5698e2b856fb07f09160e5f2",
- "result": {
- "dataset_id": 10736,
- "snapshot_id": 1724919539450264600,
- "recalculation_id": "abf9a2ec-426b-4751-bd16-fcb435061925"
}, - "created_at": "2023-10-31T11:19:13.400498",
- "updated_at": "2023-10-31T11:25:08.327209",
- "ended_at": "2023-10-31T11:25:08.327194"
}
]
}
This endpoint retrieves all details associated with a specific job ID from the jobs table.
job_id required | string Unique identifier for a job. |
{- "job_id": "2a5b9ad7-dc8f-47bb-8e62-843a38f8054c",
- "request_source": {
- "type": "api_user",
- "company_id": 1,
- "user_id": 407
}, - "state": "completed",
- "type": "materialize-view",
- "input": {
- "nql": "CREATE MATERIALIZED VIEW \"test_stats\" AS SELECT \"value\" FROM \"company_data\".\"10674\"",
- "budget": {
- "amount": {
- "value": 0,
- "currency": "USD"
}, - "period": {
- "type": "calendar_monthly"
}
}, - "dataset_id": 10736,
- "stats_enabled": true,
- "compiled_select": "SELECT\n `ds_10674`.`value`\nFROM\n narrative.datasets.ds_10674 `ds_10674`"
}, - "executor": "job-executor-98e1f48e-bf54-4f11-bbd1-73c445120266",
- "idempotency_key": "10736:29329c64e7b8a4eda86aaabe04872b832ab456b5543d0c259c812525391f158c:669a5f8e4f373c2f907700decde47511aac6470f5698e2b856fb07f09160e5f2",
- "result": {
- "dataset_id": 10736,
- "snapshot_id": 1724919539450264600,
- "recalculation_id": "abf9a2ec-426b-4751-bd16-fcb435061925"
}, - "created_at": "2023-10-31T11:19:13.400498",
- "updated_at": "2023-10-31T11:25:08.327209",
- "ended_at": "2023-10-31T11:25:08.327194"
}
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.
Return all mappings, both private and global.
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. |
{- "records": [
- {
- "id": "ea9dddd2-e3ee-40b5-b03e-c3cd37c8a7f0",
- "attribute_id": 1,
- "created_at": "2021-12-10T00:00:00Z",
- "dataset_id": 3,
- "mapping": {
- "type": "object_mapping",
- "property_mappings": [
- {
- "path": "foo",
- "expression": "upper(`US Kennel ID`)"
}, - {
- "path": "bar.baz.qux",
- "expression": "weight * 10000"
}
]
}, - "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"
}, - {
- "id": "ea9dddd2-e3ee-40b5-b03e-c3cd37c8a6f0",
- "attribute_id": 1,
- "created_at": "2021-12-10T00:00:00Z",
- "dataset_id": 3,
- "mapping": {
- "type": "value_mapping",
- "expression": "foo bar baz"
}, - "status": "archived",
- "updated_at": "2021-12-10T00:00:01Z",
- "created_by": 1,
- "updated_by": 2,
- "company_id": 100,
- "scope": "global",
- "source": "admin",
- "derived_from": null
}
]
}
Create a new global mapping.
Only admins can use this endpoint.
attribute_id | integer The target attribute's ID. |
dataset_id | integer The source dataset's ID. |
ObjectMapping (object) or ValueMapping (object) (MappingDefinition) |
{- "attribute_id": 123,
- "dataset_id": 456,
- "mapping": {
- "type": "object_mapping",
- "property_mappings": [
- {
- "path": "product.brand",
- "expression": "itemBrand"
}, - {
- "path": "product.category",
- "expression": "itemCategory"
}, - {
- "path": "product.id.type",
- "expression": "'SKU'"
}, - {
- "path": "product.id.value",
- "expression": "itemID"
}
]
}
}
{- "id": "ea9dddd2-e3ee-40b5-b03e-c3cd37c8a7f0",
- "attribute_id": 1,
- "created_at": "2021-12-10T00:00:00Z",
- "dataset_id": 3,
- "mapping": {
- "type": "object_mapping",
- "property_mappings": [
- {
- "path": "foo",
- "expression": "upper(`US Kennel ID`)"
}, - {
- "path": "bar.baz.qux",
- "expression": "weight * 10000"
}
]
}, - "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"
}
Return all system
mappings.
Only admins can call this endpoint.
{- "records": [
- {
- "id": "ea9dddd2-e3ee-40b5-b03e-c3cd37c8a7f0",
- "attribute_id": 1,
- "created_at": "2021-12-10T00:00:00Z",
- "dataset_id": 3,
- "mapping": {
- "type": "object_mapping",
- "property_mappings": [
- {
- "path": "foo",
- "expression": "upper(`US Kennel ID`)"
}, - {
- "path": "bar.baz.qux",
- "expression": "weight * 10000"
}
]
}, - "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"
}, - {
- "id": "ea9dddd2-e3ee-40b5-b03e-c3cd37c8a6f0",
- "attribute_id": 1,
- "created_at": "2021-12-10T00:00:00Z",
- "dataset_id": 3,
- "mapping": {
- "type": "value_mapping",
- "expression": "foo bar baz"
}, - "status": "archived",
- "updated_at": "2021-12-10T00:00:01Z",
- "created_by": 1,
- "updated_by": 2,
- "company_id": 100,
- "scope": "global",
- "source": "admin",
- "derived_from": null
}
]
}
Create a system
mapping.
Only admins can call this endpoint.
attribute_id | integer The target attribute's ID. |
dataset_id | integer The source dataset's ID. |
ObjectMapping (object) or ValueMapping (object) (MappingDefinition) |
{- "attribute_id": 123,
- "dataset_id": 456,
- "mapping": {
- "type": "object_mapping",
- "property_mappings": [
- {
- "path": "product.brand",
- "expression": "itemBrand"
}, - {
- "path": "product.category",
- "expression": "itemCategory"
}, - {
- "path": "product.id.type",
- "expression": "'SKU'"
}, - {
- "path": "product.id.value",
- "expression": "itemID"
}
]
}
}
{- "id": "ea9dddd2-e3ee-40b5-b03e-c3cd37c8a7f0",
- "attribute_id": 1,
- "created_at": "2021-12-10T00:00:00Z",
- "dataset_id": 3,
- "mapping": {
- "type": "object_mapping",
- "property_mappings": [
- {
- "path": "foo",
- "expression": "upper(`US Kennel ID`)"
}, - {
- "path": "bar.baz.qux",
- "expression": "weight * 10000"
}
]
}, - "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"
}
Return a specific mapping based on its id.
mapping_id required | string <uuid> Example: ea9dddd2-e3ee-40b5-b03e-c3cd37c8a6f0 Unique identifier for a mapping. |
{- "id": "ea9dddd2-e3ee-40b5-b03e-c3cd37c8a7f0",
- "attribute_id": 1,
- "created_at": "2021-12-10T00:00:00Z",
- "dataset_id": 3,
- "mapping": {
- "type": "object_mapping",
- "property_mappings": [
- {
- "path": "foo",
- "expression": "upper(`US Kennel ID`)"
}, - {
- "path": "bar.baz.qux",
- "expression": "weight * 10000"
}
]
}, - "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 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.
mapping_id required | string <uuid> Example: ea9dddd2-e3ee-40b5-b03e-c3cd37c8a6f0 Unique identifier for a mapping. |
ObjectMapping (object) or ValueMapping (object) (MappingDefinition) |
{- "mapping": {
- "type": "object_mapping",
- "property_mappings": [
- {
- "expression": "string",
- "path": "string"
}
]
}
}
{- "id": "ea9dddd2-e3ee-40b5-b03e-c3cd37c8a7f0",
- "attribute_id": 1,
- "created_at": "2021-12-10T00:00:00Z",
- "dataset_id": 3,
- "mapping": {
- "type": "object_mapping",
- "property_mappings": [
- {
- "path": "foo",
- "expression": "upper(`US Kennel ID`)"
}, - {
- "path": "bar.baz.qux",
- "expression": "weight * 10000"
}
]
}, - "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"
}
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.
mapping_id required | string <uuid> Example: ea9dddd2-e3ee-40b5-b03e-c3cd37c8a6f0 Unique identifier for 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.
mapping_id required | string <uuid> Example: ea9dddd2-e3ee-40b5-b03e-c3cd37c8a6f0 Unique identifier for a mapping. |
{- "id": "ea9dddd2-e3ee-40b5-b03e-c3cd37c8a7f0",
- "attribute_id": 1,
- "created_at": "2021-12-10T00:00:00Z",
- "dataset_id": 3,
- "mapping": {
- "type": "object_mapping",
- "property_mappings": [
- {
- "path": "foo",
- "expression": "upper(`US Kennel ID`)"
}, - {
- "path": "bar.baz.qux",
- "expression": "weight * 10000"
}
]
}, - "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 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.
mapping_id required | string <uuid> Example: ea9dddd2-e3ee-40b5-b03e-c3cd37c8a6f0 Unique identifier for a mapping. |
{- "id": "ea9dddd2-e3ee-40b5-b03e-c3cd37c8a7f0",
- "attribute_id": 1,
- "created_at": "2021-12-10T00:00:00Z",
- "dataset_id": 3,
- "mapping": {
- "type": "object_mapping",
- "property_mappings": [
- {
- "path": "foo",
- "expression": "upper(`US Kennel ID`)"
}, - {
- "path": "bar.baz.qux",
- "expression": "weight * 10000"
}
]
}, - "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"
}
Return all private mappings related to a specific company based on its id
company_id required | integer Unique identifier for a company |
{- "records": [
- {
- "id": "ea9dddd2-e3ee-40b5-b03e-c3cd37c8a7f0",
- "attribute_id": 1,
- "created_at": "2021-12-10T00:00:00Z",
- "dataset_id": 3,
- "mapping": {
- "type": "object_mapping",
- "property_mappings": [
- {
- "path": "foo",
- "expression": "upper(`US Kennel ID`)"
}, - {
- "path": "bar.baz.qux",
- "expression": "weight * 10000"
}
]
}, - "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"
}, - {
- "id": "ea9dddd2-e3ee-40b5-b03e-c3cd37c8a6f0",
- "attribute_id": 1,
- "created_at": "2021-12-10T00:00:00Z",
- "dataset_id": 3,
- "mapping": {
- "type": "value_mapping",
- "expression": "foo bar baz"
}, - "status": "archived",
- "updated_at": "2021-12-10T00:00:01Z",
- "created_by": 1,
- "updated_by": 2,
- "company_id": 100,
- "scope": "global",
- "source": "admin",
- "derived_from": null
}
]
}
Create a private mapping.
company_id required | integer Unique identifier for a company |
attribute_id | integer The target attribute's ID. |
dataset_id | integer The source dataset's ID. |
ObjectMapping (object) or ValueMapping (object) (MappingDefinition) |
{- "attribute_id": 123,
- "dataset_id": 456,
- "mapping": {
- "type": "object_mapping",
- "property_mappings": [
- {
- "path": "product.brand",
- "expression": "itemBrand"
}, - {
- "path": "product.category",
- "expression": "itemCategory"
}, - {
- "path": "product.id.type",
- "expression": "'SKU'"
}, - {
- "path": "product.id.value",
- "expression": "itemID"
}
]
}
}
{- "id": "ea9dddd2-e3ee-40b5-b03e-c3cd37c8a7f0",
- "attribute_id": 1,
- "created_at": "2021-12-10T00:00:00Z",
- "dataset_id": 3,
- "mapping": {
- "type": "object_mapping",
- "property_mappings": [
- {
- "path": "foo",
- "expression": "upper(`US Kennel ID`)"
}, - {
- "path": "bar.baz.qux",
- "expression": "weight * 10000"
}
]
}, - "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"
}
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.
mapping_id required | string <uuid> Example: ea9dddd2-e3ee-40b5-b03e-c3cd37c8a6f0 Unique identifier for a mapping. |
size | integer ( 0 .. 1000 ] The number of rows to sample from the dataset. |
{- "records": [
- {
- "input": {
- "idType": "idType1",
- "idValue": "idValue1"
}, - "output": {
- "unique_id_f7635d42_51ce_4535_ae8b_9ac64df85501": {
- "type": "idType1",
- "value": "idValue1"
}
}
}, - {
- "input": {
- "idType": "idType2",
- "idValue": "idValue2"
}, - "output": {
- "unique_id_f7635d42_51ce_4535_ae8b_9ac64df85501": {
- "type": "idType2",
- "value": "idValue2"
}
}
}
]
}
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.
size | integer ( 0 .. 1000 ] The number of rows to sample from the dataset. |
attribute_id | integer The target attribute's ID. |
dataset_id | integer The source dataset's ID. |
ObjectMapping (object) or ValueMapping (object) (MappingDefinition) |
{- "attribute_id": 123,
- "dataset_id": 456,
- "mapping": {
- "type": "object_mapping",
- "property_mappings": [
- {
- "path": "product.brand",
- "expression": "itemBrand"
}, - {
- "path": "product.category",
- "expression": "itemCategory"
}, - {
- "path": "product.id.type",
- "expression": "'SKU'"
}, - {
- "path": "product.id.value",
- "expression": "itemID"
}
]
}
}
{- "records": [
- {
- "input": {
- "idType": "idType1",
- "idValue": "idValue1"
}, - "output": {
- "unique_id_f7635d42_51ce_4535_ae8b_9ac64df85501": {
- "type": "idType1",
- "value": "idValue1"
}
}
}, - {
- "input": {
- "idType": "idType2",
- "idValue": "idValue2"
}, - "output": {
- "unique_id_f7635d42_51ce_4535_ae8b_9ac64df85501": {
- "type": "idType2",
- "value": "idValue2"
}
}
}
]
}
Get products paginated
per_page | integer Number of records to return. |
offset | integer Number of records to skip (it's usually page_number * per_page). |
{- "records": [
- {
- "id": "cd98bbb6-1086-4aea-9b5f-8ba39671a659",
- "sku": "general-storage",
- "sku_type": {
- "category": "storage"
}, - "payable_company_id": 1,
- "name": "name",
- "cloud_platform": {
- "region": "us-east-1",
- "platform": "aws"
}, - "unit": "bytes",
- "default_rate": {
- "type": "per_unit",
- "unit_price": {
- "value": 1,
- "expressed_in": "cents",
- "currency": "USD"
}
}, - "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
}
]
}
Create a new product.
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" |
{- "sku": "general-storage",
- "sku_type": {
- "category": "storage"
}, - "payable_company_id": 1,
- "name": "name",
- "cloud_platform": {
- "platform": "aws",
- "region": "us-east-1"
}, - "unit": "bytes",
- "default_rate": {
- "type": "per_unit",
- "unit_price": {
- "type": "test-price",
- "currency": "USD",
- "price_in_micro_cents": 1
}
}, - "status": "active"
}
{- "id": "cd98bbb6-1086-4aea-9b5f-8ba39671a659",
- "sku": "general-storage",
- "sku_type": {
- "category": "storage"
}, - "payable_company_id": 1,
- "name": "name",
- "cloud_platform": {
- "region": "us-east-1",
- "platform": "aws"
}, - "unit": "bytes",
- "default_rate": {
- "type": "per_unit",
- "unit_price": {
- "value": 1,
- "expressed_in": "cents",
- "currency": "USD"
}
}, - "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
}
Return single product
sku required | string Example: general-purpose-processing-aws-us-east-1 Unique identifier for a product. |
{- "id": "cd98bbb6-1086-4aea-9b5f-8ba39671a659",
- "sku": "general-storage",
- "sku_type": {
- "category": "storage"
}, - "payable_company_id": 1,
- "name": "name",
- "cloud_platform": {
- "region": "us-east-1",
- "platform": "aws"
}, - "unit": "bytes",
- "default_rate": {
- "type": "per_unit",
- "unit_price": {
- "value": 1,
- "expressed_in": "cents",
- "currency": "USD"
}
}, - "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 by sku.
sku required | string Example: general-purpose-processing-aws-us-east-1 Unique identifier for a product. |
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 |
{- "name": "string",
- "description": "string",
- "cloud_platform": {
- "region": "string",
- "platform": "string"
}, - "default_rate": {
- "type": "per_unit",
- "unit_price": {
- "value": 0,
- "expressed_in": "cents",
- "currency": "USD"
}
}, - "status": "active",
- "unit": "string"
}
{- "id": "cd98bbb6-1086-4aea-9b5f-8ba39671a659",
- "sku": "general-storage",
- "sku_type": {
- "category": "storage"
}, - "payable_company_id": 1,
- "name": "name",
- "cloud_platform": {
- "region": "us-east-1",
- "platform": "aws"
}, - "unit": "bytes",
- "default_rate": {
- "type": "per_unit",
- "unit_price": {
- "value": 1,
- "expressed_in": "cents",
- "currency": "USD"
}
}, - "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
}
Attaches given permission to a given product
product_id required | string <uuid> (Product_UUID) UUID |
permission_id required | string <uuid> (Product_UUID) UUID |
{- "product_id": "0d012afa-f885-4e65-aeca-37e27701e2d1",
- "permission_id": "2793a5a1-5444-40bb-8094-97de834ce9e4"
}
{- "error": "Unauthorized",
- "error_description": "You are not authorized to use this endpoint."
}
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.
installation_id required | string <uuid> The installation ID |
[- {
- "id": "7bc22af4-fb6e-431e-92bc-e366e4f960ff",
- "name": "My profile name",
- "description": "My profile description",
- "status": "disabled"
}
]
The profile will be assigned a unique identifier upon creation. New profiles are "disabled" and should be activated after creation.
installation_id required | string <uuid> The installation ID |
name | string |
description | string |
{- "name": "My profile name",
- "description": "My profile description"
}
{- "id": "7bc22af4-fb6e-431e-92bc-e366e4f960ff",
- "name": "My profile name",
- "description": "My profile description",
- "status": "disabled"
}
app_profile_id required | string <uuid> The profile ID |
installation_id required | string <uuid> The installation ID |
{- "id": "7bc22af4-fb6e-431e-92bc-e366e4f960ff",
- "name": "My profile name",
- "description": "My profile description",
- "status": "disabled"
}
app_profile_id required | string <uuid> The profile ID |
installation_id required | string <uuid> The installation ID |
Profile creation payload
name | string |
description | string |
{- "description": "My profile description"
}
{- "id": "7bc22af4-fb6e-431e-92bc-e366e4f960ff",
- "name": "My profile name",
- "description": "My profile description",
- "status": "disabled"
}
Only profiles that are enabled will be considered when delivering subscriptions.
app_profile_id required | string <uuid> The profile ID |
installation_id required | string <uuid> The installation ID |
{- "id": "7bc22af4-fb6e-431e-92bc-e366e4f960ff",
- "name": "My profile name",
- "description": "My profile description",
- "status": "disabled"
}
Only profiles that are enabled will be considered when delivering subscriptions.
app_profile_id required | string <uuid> The profile ID |
installation_id required | string <uuid> The installation ID |
{- "id": "7bc22af4-fb6e-431e-92bc-e366e4f960ff",
- "name": "My profile name",
- "description": "My profile description",
- "status": "disabled"
}
Archiving prevents using the profile again in the future.
app_profile_id required | string <uuid> The profile ID |
installation_id required | string <uuid> The installation ID |
{- "id": "7bc22af4-fb6e-431e-92bc-e366e4f960ff",
- "name": "My profile name",
- "description": "My profile description",
- "status": "disabled"
}
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.
Return the AWS S3 buckets assigned to the authenticated company.
{- "records": [
- {
- "id": "45b40bf5-02fc-4f18-bfcd-50ac58dabfa1",
- "company_id": 1,
- "auth": {
- "type": "bucket_policy",
- "account_id": "123456789012"
}, - "name": "nio-yourcompany-821627dd2931",
- "created_at": "2021-08-31T20:22:02Z",
- "updated_at": "2021-08-31T20:22:02Z"
}
]
}
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.
account_id required | string Your 12 digit AWS account ID. That ID will be used:
|
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:
|
object |
{- "account_id": 12345678901,
- "resource_id": "yourcompany",
- "access": {
- "type": "role",
- "external_id": "22a7553b-9240-4b81-93ae-54ccbcde0a8"
}
}
{- "id": "45b40bf5-02fc-4f18-bfcd-50ac58dabfa1",
- "company_id": 1,
- "auth": {
- "type": "bucket_policy",
- "account_id": "123456789012"
}, - "name": "nio-yourcompany-821627dd2931",
- "created_at": "2021-08-31T20:22:02Z",
- "updated_at": "2021-08-31T20:22:02Z"
}
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.
bucket_name | string Full name of the bucket that should be affected. |
BucketPolicyAccessTypeRequest (object) or RoleAccessTypeRequest (object) |
{- "bucket_name": "nio-yourcompany-iwhhrql8sgvp",
- "new_access": {
- "type": "bucket_policy"
}
}
{- "id": "45b40bf5-02fc-4f18-bfcd-50ac58dabfa1",
- "company_id": 1,
- "auth": {
- "type": "bucket_policy",
- "account_id": "123456789012"
}, - "name": "nio-yourcompany-821627dd2931",
- "created_at": "2021-08-31T20:22:02Z",
- "updated_at": "2021-08-31T20:22:02Z"
}
The schema-inference
API analyzes submitted files to automatically infer and return their structure as a dataset schema.
file | string <binary> |
{- "schema": {
- "file_config": {
- "type": "flat",
- "header": true,
- "delimiter": "string",
- "quote": "string",
- "escape": "string"
}, - "primary": "string",
- "type": "object",
- "properties": { },
- "required": [
- "string"
], - "unsellable": [
- "string"
], - "sensitive": [
- "string"
]
}
}
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.
List the schema presets that are publicly available.
{- "records": [
- {
- "id": 19,
- "company_id": 1,
- "created_at": "2021-09-29T15:20:56.44361",
- "archived_at": null,
- "name": "Age",
- "description": "A person's age gathered from registrations and surveys.",
- "scope": "public",
- "based_on_preset_id": null,
- "status": "active",
- "display_color": "#FFFFFF",
- "tags": [
- "age"
], - "details": {
- "attributes": [
- {
- "attribute_id": 1,
- "fields": [
- {
- "field": "age",
- "delivered": true,
- "filterable": true,
- "required": true,
- "forecastable": false
}
]
}
]
}
}
]
}
List the schema presets that are publicly available and the ones owned by the authenticated account.
{- "records": [
- {
- "id": 19,
- "company_id": 1,
- "created_at": "2021-09-29T15:20:56.44361",
- "archived_at": null,
- "name": "Age",
- "description": "A person's age gathered from registrations and surveys.",
- "scope": "public",
- "based_on_preset_id": null,
- "status": "active",
- "display_color": "#FFFFFF",
- "tags": [
- "age"
], - "details": {
- "attributes": [
- {
- "attribute_id": 1,
- "fields": [
- {
- "field": "age",
- "delivered": true,
- "filterable": true,
- "required": true,
- "forecastable": false
}
]
}
]
}
}
]
}
Create a private schema preset owned by the authenticated account. Only members of the same organization are able to see this schema preset.
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 |
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) |
{- "name": "string",
- "description": "string",
- "based_on_preset_id": 7,
- "icon": "string",
- "display_color": "string",
- "banner_image": "string",
- "tags": [
- "string"
], - "details": {
- "attributes": [
- {
- "attribute_id": 0,
- "fields": [
- {
- "field": "string",
- "delivered": true,
- "filterable": true,
- "required": true,
- "forecastable": true
}
]
}
]
}
}
{- "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": [
- "string"
], - "details": {
- "attributes": [
- {
- "attribute_id": 0,
- "fields": [
- {
- "field": "string",
- "delivered": true,
- "filterable": true,
- "required": true,
- "forecastable": true
}
]
}
]
}
}
Returns detailed information on a specific schema preset given its id.
schema_preset_id required | integer <int64> Unique identifier of an existing schema preset. |
{- "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": [
- "string"
], - "details": {
- "attributes": [
- {
- "attribute_id": 0,
- "fields": [
- {
- "field": "string",
- "delivered": true,
- "filterable": true,
- "required": true,
- "forecastable": true
}
]
}
]
}
}
Archive (soft delete) a specific schema preset given its id. The schema preset will not be visible from that point forward.
schema_preset_id required | integer <int64> Unique identifier of an existing schema preset. |
{- "error": "string",
- "error_description": "string"
}
Create a public schema preset available platform wide. This endpoint is only available to administrators.
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 |
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) |
{- "name": "string",
- "description": "string",
- "based_on_preset_id": 7,
- "icon": "string",
- "display_color": "string",
- "banner_image": "string",
- "tags": [
- "string"
], - "details": {
- "attributes": [
- {
- "attribute_id": 0,
- "fields": [
- {
- "field": "string",
- "delivered": true,
- "filterable": true,
- "required": true,
- "forecastable": true
}
]
}
]
}
}
{- "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": [
- "string"
], - "details": {
- "attributes": [
- {
- "attribute_id": 0,
- "fields": [
- {
- "field": "string",
- "delivered": true,
- "filterable": true,
- "required": true,
- "forecastable": true
}
]
}
]
}
}
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.
Return all subscriptions belonging to the authenticated company.
{- "records": [
- [
- {
- "id": "f82ac0d3-9391-45f5-b524-4905c383fec7",
- "cancelled_at": "2022-08-10T12:00:00Z",
- "company_id": 123,
- "created_at": "2021-12-10T00:12:23Z",
- "budget": {
- "amount": {
- "value": 100.23,
- "currency": "USD"
}, - "period": {
- "type": "calendar_monthly"
}
}, - "details": {
- "type": "marketplace",
- "company_constraint": {
- "type": "inclusion",
- "company_ids": [
- 1,
- 2,
- 3
]
}, - "data_rules": {
- "attributes": [
- {
- "attribute_id": 321,
- "fields": [
- {
- "field": "foo",
- "filter": {
- "recency": "P30D",
- "from": {
- "type": "inclusive",
- "value": "2021-12-10 12:00:00"
}
}, - "exported": false
}, - {
- "field": "bar",
- "exported": true
}
], - "optional": true
}, - {
- "attribute_id": 123,
- "fields": [
- {
- "field": "baz",
- "exported": false
}, - {
- "field": "qux",
- "exported": true
}
], - "optional": false
}
], - "deduplication": {
- "period": "P180D",
- "attribute_references": [
- {
- "attribute_id": 321,
- "column_names": [
- "baz"
]
}
]
}, - "frequency_filter": {
- "attribute_references": [
- {
- "attribute_id": 321,
- "column_names": [
- "baz"
]
}
], - "min_inclusive": 2,
- "max_inclusive": 5
}
}, - "pricing": {
- "micro_cents_usd": 123321
}
}, - "description": "subscriptiondescription",
- "name": "subscription name",
- "output": {
- "dataset_id": 42
}, - "cadence": "daily",
- "status": "cancelled",
- "updated_at": "2021-12-20T00:00:00Z"
}, - {
- "id": "9b3fd441-9add-41d8-b58a-a6ce6b0c9972",
- "company_id": 123,
- "created_at": "2021-12-10T00:12:23Z",
- "budget": {
- "amount": {
- "value": 100.23,
- "currency": "USD"
}, - "period": {
- "type": "calendar_monthly"
}
}, - "details": {
- "type": "data_stream",
- "data_rules": {
- "column_sets": [
- {
- "dataset_id": 123,
- "fields": [
- {
- "field": "col1",
- "exported": true
}, - {
- "field": "col2",
- "filter": "include_all_values_including_nulls_filter",
- "exported": true
}, - {
- "field": "col3",
- "filter": "include_only_if_not_null_filter",
- "exported": true
}, - {
- "field": "col4",
- "filter": {
- "type": "include",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col5",
- "filter": {
- "type": "exclude",
- "list": [
- "this",
- "that",
- "that too",
- "some more"
]
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "min": {
- "type": "inclusive",
- "value": "-100"
}, - "max": {
- "type": "inclusive",
- "value": "100"
}
}, - "exported": true
}, - {
- "field": "col6",
- "filter": {
- "max": {
- "type": "exclusive",
- "value": "timestamp01"
}
}, - "exported": false
}, - {
- "field": "col7",
- "filter": {
- "recency": "P30D",
- "from": {
- "type": "inclusive",
- "value": "2021-12-10 12:00:00"
}
}, - "exported": false
}, - {
- "field": "col8",
- "filter": {
- "expressions": [
- "col8 > 10"
]
}, - "exported": true
}
]
}
], - "deduplication": {
- "period": "P90D",
- "column_references": [
- {
- "dataset_id": 123,
- "column_names": [
- "col2",
- "col4"
]
}
]
}, - "frequency_filter": {
- "column_references": [
- {
- "dataset_id": 123,
- "column_names": [
- "col2"
]
}
], - "min_inclusive": 2,
- "max_inclusive": 5
}
}, - "data_stream_company_id": 3742,
- "data_stream_content": {
- "description": "description is required"
}, - "data_stream_id": "d00b2d0d-6d42-4e56-9116-c7dd8ccf638f",
- "data_stream_name": "the data stream name",
- "data_stream_slug": "a_data_product",
- "offer": {
- "id": "3f7c2ef3-17cc-4d37-ba1c-74bb2a287e13",
- "channel": "data_streams_market",
- "licensing": {
- "period": "P90D",
- "license": {
- "name": "narrative opendata license"
}
}, - "pricing": {
- "type": "per_record",
- "micro_cents_usd": 70000
}
}
}, - "description": "subscription description",
- "name": "subscription name",
- "cadence": "weekly",
- "status": "active",
- "updated_at": "2021-12-20T00:00:00Z"
}
]
]
}
Subscriptions created using this endpoint are left in the pending
state and require activation.
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 |
description | string (Subscription_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.
|
{- "budget": {
- "amount": {
- "value": 100.23,
- "currency": "USD"
}, - "period": {
- "type": "calendar_monthly"
}
}, - "description": "the subscription description",
- "details": {
- "type": "data_stream",
- "data_shop_id": "www.exampledatashop.com",
- "data_stream_id": "402c7f6e-4304-407f-9369-c7e8b787e6e9",
- "offer_id": "545494d8-74b1-4508-a634-d329555f03f8"
}, - "name": "subscription name",
- "cadence": "daily"
}
{- "id": "string",
- "budget": {
- "amount": {
- "currency": "USD",
- "value": 0
}, - "period": {
- "type": "calendar_daily"
}
}, - "cancelled_at": "string",
- "company_id": 0,
- "created_at": "string",
- "description": "string",
- "details": {
- "type": "data_stream",
- "data_rules": {
- "column_sets": [
- {
- "dataset_id": 0,
- "fields": [
- {
- "field": "/id/value",
- "filter": "include_all_values_including_nulls_filter",
- "exported": true
}
]
}
], - "attributes": [
- {
- "attribute_id": 0,
- "fields": [
- {
- "field": "/id/value",
- "filter": "include_all_values_including_nulls_filter",
- "exported": true
}
], - "optional": true
}
], - "deduplication": {
- "period": "string",
- "column_references": [
- {
- "dataset_id": 0,
- "column_names": [
- "/id/value"
]
}
], - "attribute_references": [
- {
- "attribute_id": 0,
- "column_names": [
- "/id/value"
]
}
]
}, - "frequency_filter": {
- "column_references": [
- {
- "dataset_id": 0,
- "column_names": [
- "/id/value"
]
}
], - "attribute_references": [
- {
- "attribute_id": 0,
- "column_names": [
- "/id/value"
]
}
], - "min_inclusive": 0,
- "max_inclusive": 0
}, - "dataset_filter": {
- "dataset_id": 0,
- "attribute": {
- "attribute_id": 0,
- "field": "/id/value"
}, - "inclusion": "include"
}
}, - "data_shop_id": "string",
- "data_stream_company_id": 0,
- "data_stream_content": {
- "description": "string",
- "icon": "string",
- "sections": [
- { }
]
}, - "data_stream_id": "7a4b81a1-fe0b-453f-8554-63b6549f81ba",
- "data_stream_name": "string",
- "data_stream_slug": "string",
- "offer": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "channel": "data_streams_market",
- "licensing": {
- "period": "string",
- "license": {
- "name": "string"
}
}, - "pricing": {
- "type": "per_record",
- "micro_cents_usd": 0
}, - "shops": [
- "string"
]
}
}, - "name": "string",
- "output": {
- "dataset_id": 0
}, - "cadence": "once",
- "status": "active",
- "updated_at": "string"
}
Return all cost forecasts belonging to the authenticated company.
{- "records": [
- {
- "id": "9cdd4b69-82cb-4454-aedf-197bc3930b44",
- "company_id": 1,
- "cost": {
- "rows": 26565354859246,
- "size": 1299135691639572,
- "sources": [
- {
- "source": {
- "type": "dataset",
- "dataset_id": 192
}, - "rows": 26565354859246,
- "size": 1299135691639572
}
]
}, - "created_at": "2021-11-26T20:20:13.909581Z",
- "details": {
- "type": "marketplace",
- "company_constraint": {
- "type": "exclusion",
- "company_ids": [
- 56
]
}, - "data_rules": {
- "attributes": [
- {
- "attribute_id": 2,
- "fields": [
- {
- "field": "event_timestamp",
- "filter": {
- "recency": "P30D"
}, - "exported": true
}
], - "optional": false
}, - {
- "attribute_id": 1,
- "fields": [
- {
- "field": "unique_id.type",
- "filter": {
- "type": "include",
- "list": [
- "idfa",
- "adid"
]
}, - "exported": true
}, - {
- "field": "unique_id.value",
- "filter": "include_only_if_not_null_filter",
- "exported": true
}
], - "optional": false
}, - {
- "attribute_id": 11,
- "fields": [
- {
- "field": "ip_address",
- "filter": "include_only_if_not_null_filter",
- "exported": true
}
], - "optional": false
}
], - "frequency_filter": {
- "attribute_references": [
- {
- "attribute_id": 1,
- "column_names": [
- "unique_id.type",
- "unique_id.value"
]
}
], - "min_inclusive": 2
}
}, - "pricing": {
- "micro_cents_usd": 10000000
}
}, - "request_source": {
- "type": "api_user",
- "company_id": 1,
- "user_id": 1
}, - "subscription_id": null
}
]
}
Create an estimate of the "cost" of servicing a set of subscription constraints.
Cost has two components:
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.
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. |
{- "type": "data_stream",
- "data_shop_id": "string",
- "data_stream_id": "7a4b81a1-fe0b-453f-8554-63b6549f81ba",
- "offer_id": "d5a7a5b7-a4a3-49e7-9c69-b44d2cbe15cf",
- "details": {
- "type": "marketplace",
- "company_constraint": {
- "type": "inclusion",
- "company_ids": [
- 1,
- 2,
- 3
]
}, - "data_rules": {
- "attributes": [
- {
- "attribute_id": 123,
- "fields": [
- {
- "field": "example.timestamp",
- "filter": {
- "recency": "P30D",
- "from": {
- "type": "inclusive",
- "value": "2021-12-10 12:00:00"
}, - "to": null
}, - "exported": false
}, - {
- "field": "example.string_field",
- "filter": null,
- "exported": true
}
], - "optional": true
}
]
}, - "pricing": {
- "micro_cents_usd": 1000000000
}
}
}
{- "records": [
- {
- "type": "attributes",
- "attributes": [
- {
- "id": 0,
- "name": "string"
}
], - "dataset": {
- "id": 0,
- "company_id": 0,
- "name": "string",
- "description": "string"
}, - "matching_access_rules": {
- "id": 0,
- "constraints": [
- "string"
], - "pricing": 0
}, - "non_matching_access_rules": {
- "id": 0,
- "constraints": [
- "string"
], - "pricing": 0
}
}
]
}
Get a cost forecast by id.
cost_forecast_id required | string <uuid> Unique identifier for a cost forecast. |
{- "id": "9cdd4b69-82cb-4454-aedf-197bc3930b44",
- "company_id": 1,
- "cost": {
- "rows": 26565354859246,
- "size": 1299135691639572,
- "sources": [
- {
- "source": {
- "type": "dataset",
- "dataset_id": 192
}, - "rows": 26565354859246,
- "size": 1299135691639572
}
]
}, - "created_at": "2021-11-26T20:20:13.909581Z",
- "details": {
- "type": "marketplace",
- "company_constraint": {
- "type": "exclusion",
- "company_ids": [
- 56
]
}, - "data_rules": {
- "attributes": [
- {
- "attribute_id": 2,
- "fields": [
- {
- "field": "event_timestamp",
- "filter": {
- "recency": "P30D"
}, - "exported": true
}
], - "optional": false
}, - {
- "attribute_id": 1,
- "fields": [
- {
- "field": "unique_id.type",
- "filter": {
- "type": "include",
- "list": [
- "idfa",
- "adid"
]
}, - "exported": true
}, - {
- "field": "unique_id.value",
- "filter": "include_only_if_not_null_filter",
- "exported": true
}
], - "optional": false
}, - {
- "attribute_id": 11,
- "fields": [
- {
- "field": "ip_address",
- "filter": "include_only_if_not_null_filter",
- "exported": true
}
], - "optional": false
}
], - "frequency_filter": {
- "attribute_references": [
- {
- "attribute_id": 1,
- "column_names": [
- "unique_id.type",
- "unique_id.value"
]
}
], - "min_inclusive": 2
}
}, - "pricing": {
- "micro_cents_usd": 10000000
}
}, - "request_source": {
- "type": "api_user",
- "company_id": 1,
- "user_id": 1
}, - "subscription_id": null
}
Retrieve datasets matching a set of subscription constraints.
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. |
{- "type": "data_stream",
- "data_shop_id": "string",
- "data_stream_id": "7a4b81a1-fe0b-453f-8554-63b6549f81ba",
- "offer_id": "d5a7a5b7-a4a3-49e7-9c69-b44d2cbe15cf",
- "details": {
- "type": "marketplace",
- "company_constraint": {
- "type": "inclusion",
- "company_ids": [
- 1,
- 2,
- 3
]
}, - "data_rules": {
- "attributes": [
- {
- "attribute_id": 123,
- "fields": [
- {
- "field": "example.timestamp",
- "filter": {
- "recency": "P30D",
- "from": {
- "type": "inclusive",
- "value": "2021-12-10 12:00:00"
}, - "to": null
}, - "exported": false
}, - {
- "field": "example.string_field",
- "filter": null,
- "exported": true
}
], - "optional": true
}
]
}, - "pricing": {
- "micro_cents_usd": 1000000000
}
}
}
{- "records": [
- {
- "type": "attributes",
- "attributes": [
- {
- "id": 0,
- "name": "string"
}
], - "dataset": {
- "id": 0,
- "company_id": 0,
- "name": "string",
- "description": "string"
}, - "matching_access_rules": {
- "id": 0,
- "constraints": [
- "string"
], - "pricing": 0
}, - "non_matching_access_rules": {
- "id": 0,
- "constraints": [
- "string"
], - "pricing": 0
}
}
]
}
Get a subscription by id.
subscription_id required | string <uuid> Unique identifier for a subscription. |
{- "id": "string",
- "budget": {
- "amount": {
- "currency": "USD",
- "value": 0
}, - "period": {
- "type": "calendar_daily"
}
}, - "cancelled_at": "string",
- "company_id": 0,
- "created_at": "string",
- "description": "string",
- "details": {
- "type": "data_stream",
- "data_rules": {
- "column_sets": [
- {
- "dataset_id": 0,
- "fields": [
- {
- "field": "/id/value",
- "filter": "include_all_values_including_nulls_filter",
- "exported": true
}
]
}
], - "attributes": [
- {
- "attribute_id": 0,
- "fields": [
- {
- "field": "/id/value",
- "filter": "include_all_values_including_nulls_filter",
- "exported": true
}
], - "optional": true
}
], - "deduplication": {
- "period": "string",
- "column_references": [
- {
- "dataset_id": 0,
- "column_names": [
- "/id/value"
]
}
], - "attribute_references": [
- {
- "attribute_id": 0,
- "column_names": [
- "/id/value"
]
}
]
}, - "frequency_filter": {
- "column_references": [
- {
- "dataset_id": 0,
- "column_names": [
- "/id/value"
]
}
], - "attribute_references": [
- {
- "attribute_id": 0,
- "column_names": [
- "/id/value"
]
}
], - "min_inclusive": 0,
- "max_inclusive": 0
}, - "dataset_filter": {
- "dataset_id": 0,
- "attribute": {
- "attribute_id": 0,
- "field": "/id/value"
}, - "inclusion": "include"
}
}, - "data_shop_id": "string",
- "data_stream_company_id": 0,
- "data_stream_content": {
- "description": "string",
- "icon": "string",
- "sections": [
- { }
]
}, - "data_stream_id": "7a4b81a1-fe0b-453f-8554-63b6549f81ba",
- "data_stream_name": "string",
- "data_stream_slug": "string",
- "offer": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "channel": "data_streams_market",
- "licensing": {
- "period": "string",
- "license": {
- "name": "string"
}
}, - "pricing": {
- "type": "per_record",
- "micro_cents_usd": 0
}, - "shops": [
- "string"
]
}
}, - "name": "string",
- "output": {
- "dataset_id": 0
}, - "cadence": "once",
- "status": "active",
- "updated_at": "string"
}
Update a subscription
NOTE: If the cadence of the subscription is modified, the frequency filter will automatically be adjusted to match the new cadence.
subscription_id required | string <uuid> Unique identifier for a subscription. |
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 |
description | string (Subscription_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.
|
{- "budget": {
- "amount": {
- "value": 250,
- "currency": "USD"
}, - "period": {
- "type": "calendar_monthly"
}
}, - "description": "subscription description",
- "details": {
- "type": "marketplace",
- "data_rules": {
- "attributes": [
- {
- "attribute_id": 32,
- "fields": [
- {
- "field": "customer_v1.id.type",
- "filter": {
- "type": "include",
- "list": [
- "idfa"
]
}, - "exported": true
}, - {
- "field": "customer_v1.id.value",
- "exported": true
}, - {
- "field": "customer_v1.name.full_name",
- "exported": true
}
], - "optional": false
}, - {
- "attribute_id": 45,
- "fields": [
- {
- "field": "event_timestamp_v2",
- "filter": {
- "recency": "P180D"
}, - "exported": true
}
], - "optional": true
}, - {
- "attribute_id": 30,
- "fields": [
- {
- "field": "product_v2.name",
- "exported": true
}
], - "optional": true
}
], - "deduplication": {
- "period": "P90D",
- "attribute_references": [
- {
- "attribute_id": 123,
- "column_names": [
- "event_timestamp_v2"
]
}
]
}, - "frequency_filter": {
- "attribute_references": [
- {
- "attribute_id": 123,
- "column_names": [
- "event_timestamp_v2"
]
}
], - "min_inclusive": 2,
- "max_inclusive": 5
}
}, - "pricing": {
- "micro_cents_usd": 1000000000
}
}, - "name": "subscription name",
- "cadence": "monthly"
}
{- "id": "string",
- "budget": {
- "amount": {
- "currency": "USD",
- "value": 0
}, - "period": {
- "type": "calendar_daily"
}
}, - "cancelled_at": "string",
- "company_id": 0,
- "created_at": "string",
- "description": "string",
- "details": {
- "type": "data_stream",
- "data_rules": {
- "column_sets": [
- {
- "dataset_id": 0,
- "fields": [
- {
- "field": "/id/value",
- "filter": "include_all_values_including_nulls_filter",
- "exported": true
}
]
}
], - "attributes": [
- {
- "attribute_id": 0,
- "fields": [
- {
- "field": "/id/value",
- "filter": "include_all_values_including_nulls_filter",
- "exported": true
}
], - "optional": true
}
], - "deduplication": {
- "period": "string",
- "column_references": [
- {
- "dataset_id": 0,
- "column_names": [
- "/id/value"
]
}
], - "attribute_references": [
- {
- "attribute_id": 0,
- "column_names": [
- "/id/value"
]
}
]
}, - "frequency_filter": {
- "column_references": [
- {
- "dataset_id": 0,
- "column_names": [
- "/id/value"
]
}
], - "attribute_references": [
- {
- "attribute_id": 0,
- "column_names": [
- "/id/value"
]
}
], - "min_inclusive": 0,
- "max_inclusive": 0
}, - "dataset_filter": {
- "dataset_id": 0,
- "attribute": {
- "attribute_id": 0,
- "field": "/id/value"
}, - "inclusion": "include"
}
}, - "data_shop_id": "string",
- "data_stream_company_id": 0,
- "data_stream_content": {
- "description": "string",
- "icon": "string",
- "sections": [
- { }
]
}, - "data_stream_id": "7a4b81a1-fe0b-453f-8554-63b6549f81ba",
- "data_stream_name": "string",
- "data_stream_slug": "string",
- "offer": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "channel": "data_streams_market",
- "licensing": {
- "period": "string",
- "license": {
- "name": "string"
}
}, - "pricing": {
- "type": "per_record",
- "micro_cents_usd": 0
}, - "shops": [
- "string"
]
}
}, - "name": "string",
- "output": {
- "dataset_id": 0
}, - "cadence": "once",
- "status": "active",
- "updated_at": "string"
}
Activation will result in charges to your company's payment method.
subscription_id required | string <uuid> Unique identifier for a subscription. |
{- "id": "string",
- "budget": {
- "amount": {
- "currency": "USD",
- "value": 0
}, - "period": {
- "type": "calendar_daily"
}
}, - "cancelled_at": "string",
- "company_id": 0,
- "created_at": "string",
- "description": "string",
- "details": {
- "type": "data_stream",
- "data_rules": {
- "column_sets": [
- {
- "dataset_id": 0,
- "fields": [
- {
- "field": "/id/value",
- "filter": "include_all_values_including_nulls_filter",
- "exported": true
}
]
}
], - "attributes": [
- {
- "attribute_id": 0,
- "fields": [
- {
- "field": "/id/value",
- "filter": "include_all_values_including_nulls_filter",
- "exported": true
}
], - "optional": true
}
], - "deduplication": {
- "period": "string",
- "column_references": [
- {
- "dataset_id": 0,
- "column_names": [
- "/id/value"
]
}
], - "attribute_references": [
- {
- "attribute_id": 0,
- "column_names": [
- "/id/value"
]
}
]
}, - "frequency_filter": {
- "column_references": [
- {
- "dataset_id": 0,
- "column_names": [
- "/id/value"
]
}
], - "attribute_references": [
- {
- "attribute_id": 0,
- "column_names": [
- "/id/value"
]
}
], - "min_inclusive": 0,
- "max_inclusive": 0
}, - "dataset_filter": {
- "dataset_id": 0,
- "attribute": {
- "attribute_id": 0,
- "field": "/id/value"
}, - "inclusion": "include"
}
}, - "data_shop_id": "string",
- "data_stream_company_id": 0,
- "data_stream_content": {
- "description": "string",
- "icon": "string",
- "sections": [
- { }
]
}, - "data_stream_id": "7a4b81a1-fe0b-453f-8554-63b6549f81ba",
- "data_stream_name": "string",
- "data_stream_slug": "string",
- "offer": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "channel": "data_streams_market",
- "licensing": {
- "period": "string",
- "license": {
- "name": "string"
}
}, - "pricing": {
- "type": "per_record",
- "micro_cents_usd": 0
}, - "shops": [
- "string"
]
}
}, - "name": "string",
- "output": {
- "dataset_id": 0
}, - "cadence": "once",
- "status": "active",
- "updated_at": "string"
}
A cancelled subscription cannot be reactivated.
subscription_id required | string <uuid> Unique identifier for a subscription. |
{- "id": "string",
- "budget": {
- "amount": {
- "currency": "USD",
- "value": 0
}, - "period": {
- "type": "calendar_daily"
}
}, - "cancelled_at": "string",
- "company_id": 0,
- "created_at": "string",
- "description": "string",
- "details": {
- "type": "data_stream",
- "data_rules": {
- "column_sets": [
- {
- "dataset_id": 0,
- "fields": [
- {
- "field": "/id/value",
- "filter": "include_all_values_including_nulls_filter",
- "exported": true
}
]
}
], - "attributes": [
- {
- "attribute_id": 0,
- "fields": [
- {
- "field": "/id/value",
- "filter": "include_all_values_including_nulls_filter",
- "exported": true
}
], - "optional": true
}
], - "deduplication": {
- "period": "string",
- "column_references": [
- {
- "dataset_id": 0,
- "column_names": [
- "/id/value"
]
}
], - "attribute_references": [
- {
- "attribute_id": 0,
- "column_names": [
- "/id/value"
]
}
]
}, - "frequency_filter": {
- "column_references": [
- {
- "dataset_id": 0,
- "column_names": [
- "/id/value"
]
}
], - "attribute_references": [
- {
- "attribute_id": 0,
- "column_names": [
- "/id/value"
]
}
], - "min_inclusive": 0,
- "max_inclusive": 0
}, - "dataset_filter": {
- "dataset_id": 0,
- "attribute": {
- "attribute_id": 0,
- "field": "/id/value"
}, - "inclusion": "include"
}
}, - "data_shop_id": "string",
- "data_stream_company_id": 0,
- "data_stream_content": {
- "description": "string",
- "icon": "string",
- "sections": [
- { }
]
}, - "data_stream_id": "7a4b81a1-fe0b-453f-8554-63b6549f81ba",
- "data_stream_name": "string",
- "data_stream_slug": "string",
- "offer": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "channel": "data_streams_market",
- "licensing": {
- "period": "string",
- "license": {
- "name": "string"
}
}, - "pricing": {
- "type": "per_record",
- "micro_cents_usd": 0
}, - "shops": [
- "string"
]
}
}, - "name": "string",
- "output": {
- "dataset_id": 0
}, - "cadence": "once",
- "status": "active",
- "updated_at": "string"
}
Checkout creates and activates a subscription in a single API call.
Activation will result in charges to your company's payment method.
subscription_id required | string <uuid> Unique identifier for a subscription. |
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 |
description | string (Subscription_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.
|
{- "budget": {
- "amount": {
- "value": 100.23,
- "currency": "USD"
}, - "period": {
- "type": "calendar_monthly"
}
}, - "description": "the subscription description",
- "details": {
- "type": "data_stream",
- "data_shop_id": "www.exampledatashop.com",
- "data_stream_id": "402c7f6e-4304-407f-9369-c7e8b787e6e9",
- "offer_id": "545494d8-74b1-4508-a634-d329555f03f8"
}, - "name": "subscription name",
- "cadence": "daily"
}
{- "id": "string",
- "budget": {
- "amount": {
- "currency": "USD",
- "value": 0
}, - "period": {
- "type": "calendar_daily"
}
}, - "cancelled_at": "string",
- "company_id": 0,
- "created_at": "string",
- "description": "string",
- "details": {
- "type": "data_stream",
- "data_rules": {
- "column_sets": [
- {
- "dataset_id": 0,
- "fields": [
- {
- "field": "/id/value",
- "filter": "include_all_values_including_nulls_filter",
- "exported": true
}
]
}
], - "attributes": [
- {
- "attribute_id": 0,
- "fields": [
- {
- "field": "/id/value",
- "filter": "include_all_values_including_nulls_filter",
- "exported": true
}
], - "optional": true
}
], - "deduplication": {
- "period": "string",
- "column_references": [
- {
- "dataset_id": 0,
- "column_names": [
- "/id/value"
]
}
], - "attribute_references": [
- {
- "attribute_id": 0,
- "column_names": [
- "/id/value"
]
}
]
}, - "frequency_filter": {
- "column_references": [
- {
- "dataset_id": 0,
- "column_names": [
- "/id/value"
]
}
], - "attribute_references": [
- {
- "attribute_id": 0,
- "column_names": [
- "/id/value"
]
}
], - "min_inclusive": 0,
- "max_inclusive": 0
}, - "dataset_filter": {
- "dataset_id": 0,
- "attribute": {
- "attribute_id": 0,
- "field": "/id/value"
}, - "inclusion": "include"
}
}, - "data_shop_id": "string",
- "data_stream_company_id": 0,
- "data_stream_content": {
- "description": "string",
- "icon": "string",
- "sections": [
- { }
]
}, - "data_stream_id": "7a4b81a1-fe0b-453f-8554-63b6549f81ba",
- "data_stream_name": "string",
- "data_stream_slug": "string",
- "offer": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "channel": "data_streams_market",
- "licensing": {
- "period": "string",
- "license": {
- "name": "string"
}
}, - "pricing": {
- "type": "per_record",
- "micro_cents_usd": 0
}, - "shops": [
- "string"
]
}
}, - "name": "string",
- "output": {
- "dataset_id": 0
}, - "cadence": "once",
- "status": "active",
- "updated_at": "string"
}
Retrieve cost forecasts for a subscription.
subscription_id required | string <uuid> Unique identifier for a subscription. |
{- "records": [
- {
- "id": "9cdd4b69-82cb-4454-aedf-197bc3930b44",
- "company_id": 1,
- "cost": {
- "rows": 26565354859246,
- "size": 1299135691639572,
- "sources": [
- {
- "source": {
- "type": "dataset",
- "dataset_id": 192
}, - "rows": 26565354859246,
- "size": 1299135691639572
}
]
}, - "created_at": "2021-11-26T20:20:13.909581Z",
- "details": {
- "type": "marketplace",
- "company_constraint": {
- "type": "exclusion",
- "company_ids": [
- 56
]
}, - "data_rules": {
- "attributes": [
- {
- "attribute_id": 2,
- "fields": [
- {
- "field": "event_timestamp",
- "filter": {
- "recency": "P30D"
}, - "exported": true
}
], - "optional": false
}, - {
- "attribute_id": 1,
- "fields": [
- {
- "field": "unique_id.type",
- "filter": {
- "type": "include",
- "list": [
- "idfa",
- "adid"
]
}, - "exported": true
}, - {
- "field": "unique_id.value",
- "filter": "include_only_if_not_null_filter",
- "exported": true
}
], - "optional": false
}, - {
- "attribute_id": 11,
- "fields": [
- {
- "field": "ip_address",
- "filter": "include_only_if_not_null_filter",
- "exported": true
}
], - "optional": false
}
], - "frequency_filter": {
- "attribute_references": [
- {
- "attribute_id": 1,
- "column_names": [
- "unique_id.type",
- "unique_id.value"
]
}
], - "min_inclusive": 2
}
}, - "pricing": {
- "micro_cents_usd": 10000000
}
}, - "request_source": {
- "type": "api_user",
- "company_id": 1,
- "user_id": 1
}, - "subscription_id": null
}
]
}
Create a cost forecast for a subscription, taking into account data already processed for the subscription.
subscription_id required | string <uuid> Unique identifier for a subscription. |
{- "id": "9cdd4b69-82cb-4454-aedf-197bc3930b44",
- "company_id": 1,
- "cost": {
- "rows": 26565354859246,
- "size": 1299135691639572,
- "sources": [
- {
- "source": {
- "type": "dataset",
- "dataset_id": 192
}, - "rows": 26565354859246,
- "size": 1299135691639572
}
]
}, - "created_at": "2021-11-26T20:20:13.909581Z",
- "details": {
- "type": "marketplace",
- "company_constraint": {
- "type": "exclusion",
- "company_ids": [
- 56
]
}, - "data_rules": {
- "attributes": [
- {
- "attribute_id": 2,
- "fields": [
- {
- "field": "event_timestamp",
- "filter": {
- "recency": "P30D"
}, - "exported": true
}
], - "optional": false
}, - {
- "attribute_id": 1,
- "fields": [
- {
- "field": "unique_id.type",
- "filter": {
- "type": "include",
- "list": [
- "idfa",
- "adid"
]
}, - "exported": true
}, - {
- "field": "unique_id.value",
- "filter": "include_only_if_not_null_filter",
- "exported": true
}
], - "optional": false
}, - {
- "attribute_id": 11,
- "fields": [
- {
- "field": "ip_address",
- "filter": "include_only_if_not_null_filter",
- "exported": true
}
], - "optional": false
}
], - "frequency_filter": {
- "attribute_references": [
- {
- "attribute_id": 1,
- "column_names": [
- "unique_id.type",
- "unique_id.value"
]
}
], - "min_inclusive": 2
}
}, - "pricing": {
- "micro_cents_usd": 10000000
}
}, - "request_source": {
- "type": "api_user",
- "company_id": 1,
- "user_id": 1
}, - "subscription_id": null
}
Retrieve metadata about files containing data purchased as part of the subscription.
subscription_id required | string <uuid> Unique identifier for a subscription. |
{- "records": [
- {
- "company_id": 123,
- "file": "part-000001-dbba05a2-2924-424a-80ab-2a8af07ddd19.json",
- "size": 1231231231,
- "subscription_id": "7c39a38d-a23a-4c48-9dcf-681400e0c552",
- "transaction_batch_id": "2ed2ecdd-5f17-4e08-8f13-948cecdd4c38",
- "timestamp": "2021-12-31T00:00:01Z"
}
]
}
Retrieve a AWS S3 presigned URL to download a file delivered as part of a subscription.
subscription_id required | string <uuid> Unique identifier for a subscription. |
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 |
{- "transaction_batch_id": "2a2b1c72-dc18-4c07-a558-f7fbf09556f8",
- "file": "string",
- "file_name_override": "string"
}
{- "download_url": "string"
}
Retrieve datasets matching a subscription's constraints.
subscription_id required | string <uuid> Unique identifier for a subscription. |
{- "records": [
- {
- "type": "attributes",
- "attributes": [
- {
- "id": 0,
- "name": "string"
}
], - "dataset": {
- "id": 0,
- "company_id": 0,
- "name": "string",
- "description": "string"
}, - "matching_access_rules": {
- "id": 0,
- "constraints": [
- "string"
], - "pricing": 0
}, - "non_matching_access_rules": {
- "id": 0,
- "constraints": [
- "string"
], - "pricing": 0
}
}
]
}
Retrieve schema for deliveries from this subscription.
subscription_id required | string <uuid> Unique identifier for a subscription. |
{- "value": {
- "type": "double"
}, - "iso_4217_currency": {
- "type": "string"
}, - "tags": {
- "type": "array",
- "items": {
- "type": "string"
}
}
}
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.
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.
upload_path required | string Example: /lists/idlist.csv A slash-separated path where the uploaded file should be stored |
Create a usage event to charge a customer for their use of a product.
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. |
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 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. |
{- "company_id": 1,
- "created_by": 2,
- "dimensions": {
- "dataset_id": "123"
}, - "event_timestamp": "2022-11-10T00:00:00Z",
- "event_type": "processing-dataset-ingestion",
- "idempotency_key": "882e0a91-10a2-47c7-8e70-69344d725a6f",
- "measures": {
- "rows": 8212837
}, - "sku": "general-purpose-processing-aws-us-east-1",
- "usage": {
- "unit": "gigabytes",
- "value": 181.281
}
}
{- "id": "fe0212f6-3440-44e6-b049-ef6c5ad1f396",
- "app_id": 5,
- "company_id": 1,
- "created_at": "2022-11-10T00:00:00Z",
- "created_by": 2,
- "dimensions": {
- "dataset_id": "123"
}, - "event_timestamp": "2022-11-10T00:00:00Z",
- "event_type": "processing-dataset-ingestion",
- "idempotency_key": "882e0a91-10a2-47c7-8e70-69344d725a6f",
- "measures": {
- "rows": 8212837
}, - "sku": "general-purpose-processing-aws-us-east-1",
- "usage": {
- "unit": "gigabytes",
- "value": 181.281
}
}
Get a query.
query_id required | string <uuid> Query identifier. |
{- "name": "query1",
- "id": "7409b999-2a9a-40cd-89dc-8430d85e0391",
- "display_name": "Query One",
- "owner": {
- "company_id": 456,
- "company_name": "ExampleCorp",
- "company_slug": "examplecorp"
}, - "tags": [
- "tag1",
- "tag2"
], - "collaborators": {
- "type": "inclusion",
- "company_ids": [
- 789
]
}, - "is_owned": true,
- "metadata": {
- "created_at": "2024-04-12T19:57:05.012908",
- "created_by_user_id": 321,
- "updated_at": "2024-04-12T20:03:48.031825",
- "updated_by_user_id": 321
}, - "ast": {
- "type": "select",
- "nql": "SELECT age FROM narrative.rosetta_stone",
- "budget": null,
- "columns": [
- {
- "type": "table",
- "nql": "age",
- "db": null,
- "schema": null,
- "table": "age"
}
], - "from": {
- "type": "table",
- "nql": "narrative.rosetta_stone",
- "db": null,
- "schema": "narrative",
- "table": "rosetta_stone"
}, - "group_by": [ ],
- "having": null,
- "is_distinct": false,
- "limit": null,
- "order_by": [ ],
- "qualify": null,
- "where": null,
- "windows": [ ],
- "with": [ ]
}
}
Updates a query
query_id required | string <uuid> Query identifier. |
name | string (QueryName) It should be unique. Must be <= 256 characters and consist of only alphanumeric characters and underscores. |
display_name | string (DisplayName) Optional. Display Name must be non-empty and less than 1000 chars. |
description | string (Description) A human-friendly description of the query. |
tags | Array of strings (Tags) Optional. Each tag must be less than 256 chars. |
object (Collaborators) A constraint describing which companies have read access to the query. | |
ast | object (AST) The AST representing the query. |
{- "name": "updated name",
- "tags": [
- "tag3"
]
}
{- "name": "query1",
- "id": "7409b999-2a9a-40cd-89dc-8430d85e0391",
- "display_name": "Query One",
- "owner": {
- "company_id": 456,
- "company_name": "ExampleCorp",
- "company_slug": "examplecorp"
}, - "tags": [
- "tag1",
- "tag2"
], - "collaborators": {
- "type": "inclusion",
- "company_ids": [
- 789
]
}, - "is_owned": true,
- "metadata": {
- "created_at": "2024-04-12T19:57:05.012908",
- "created_by_user_id": 321,
- "updated_at": "2024-04-12T20:03:48.031825",
- "updated_by_user_id": 321
}, - "ast": {
- "type": "select",
- "nql": "SELECT age FROM narrative.rosetta_stone",
- "budget": null,
- "columns": [
- {
- "type": "table",
- "nql": "age",
- "db": null,
- "schema": null,
- "table": "age"
}
], - "from": {
- "type": "table",
- "nql": "narrative.rosetta_stone",
- "db": null,
- "schema": "narrative",
- "table": "rosetta_stone"
}, - "group_by": [ ],
- "having": null,
- "is_distinct": false,
- "limit": null,
- "order_by": [ ],
- "qualify": null,
- "where": null,
- "windows": [ ],
- "with": [ ]
}
}
Get all accessible queries.
is_owned | boolean If |
tag | string Filters queries that are tagged with |
page | integer Number of page. Stars from the first (1) page. |
per_page | integer Number of records to return. |
{- "prev_page": null,
- "current_page": 1,
- "next_page": null,
- "total_records": 1,
- "total_pages": 1,
- "records": [
- {
- "name": "query1",
- "id": "7409b999-2a9a-40cd-89dc-8430d85e0391",
- "display_name": "Query One",
- "owner": {
- "company_id": 456,
- "company_name": "ExampleCorp",
- "company_slug": "examplecorp"
}, - "tags": [
- "tag1",
- "tag2"
], - "collaborators": {
- "type": "inclusion",
- "company_ids": [
- 789
]
}, - "is_owned": true,
- "metadata": {
- "created_at": "2024-04-12T19:57:05.012908",
- "created_by_user_id": 321,
- "updated_at": "2024-04-12T20:03:48.031825",
- "updated_by_user_id": 321
}, - "ast": {
- "type": "select",
- "nql": "SELECT age FROM narrative.rosetta_stone",
- "budget": null,
- "columns": [
- {
- "type": "table",
- "nql": "age",
- "db": null,
- "schema": null,
- "table": "age"
}
], - "from": {
- "type": "table",
- "nql": "narrative.rosetta_stone",
- "db": null,
- "schema": "narrative",
- "table": "rosetta_stone"
}, - "group_by": [ ],
- "having": null,
- "is_distinct": false,
- "limit": null,
- "order_by": [ ],
- "qualify": null,
- "where": null,
- "windows": [ ],
- "with": [ ]
}
}
]
}
Any number of properties can be updated on the same request. If a property is not sent on the payload, the value won't be updated.
name required | string (QueryName) It should be unique. Must be <= 256 characters and consist of only alphanumeric characters and underscores. |
display_name | string (DisplayName) Optional. Display Name must be non-empty and less than 1000 chars. |
description | string (Description) A human-friendly description of the query. |
tags | Array of strings (Tags) Optional. Each tag must be less than 256 chars. |
required | object (Collaborators) A constraint describing which companies have read access to the query. |
ast required | object (AST) The AST representing the query. |
{- "name": "query1",
- "display_name": "Query One",
- "tags": [
- "tag1",
- "tag2"
], - "collaborators": {
- "type": "inclusion",
- "company_ids": [
- 789
]
}, - "ast": {
- "type": "select",
- "nql": "SELECT age FROM narrative.rosetta_stone",
- "budget": null,
- "columns": [
- {
- "type": "table",
- "nql": "age",
- "db": null,
- "schema": null,
- "table": "age"
}
], - "from": {
- "type": "table",
- "nql": "narrative.rosetta_stone",
- "db": null,
- "schema": "narrative",
- "table": "rosetta_stone"
}, - "group_by": [ ],
- "having": null,
- "is_distinct": false,
- "limit": null,
- "order_by": [ ],
- "qualify": null,
- "where": null,
- "windows": [ ],
- "with": [ ]
}
}
{- "name": "query1",
- "id": "7409b999-2a9a-40cd-89dc-8430d85e0391",
- "display_name": "Query One",
- "owner": {
- "company_id": 456,
- "company_name": "ExampleCorp",
- "company_slug": "examplecorp"
}, - "tags": [
- "tag1",
- "tag2"
], - "collaborators": {
- "type": "inclusion",
- "company_ids": [
- 789
]
}, - "is_owned": true,
- "metadata": {
- "created_at": "2024-04-12T19:57:05.012908",
- "created_by_user_id": 321,
- "updated_at": "2024-04-12T20:03:48.031825",
- "updated_by_user_id": 321
}, - "ast": {
- "type": "select",
- "nql": "SELECT age FROM narrative.rosetta_stone",
- "budget": null,
- "columns": [
- {
- "type": "table",
- "nql": "age",
- "db": null,
- "schema": null,
- "table": "age"
}
], - "from": {
- "type": "table",
- "nql": "narrative.rosetta_stone",
- "db": null,
- "schema": "narrative",
- "table": "rosetta_stone"
}, - "group_by": [ ],
- "having": null,
- "is_distinct": false,
- "limit": null,
- "order_by": [ ],
- "qualify": null,
- "where": null,
- "windows": [ ],
- "with": [ ]
}
}
Get a view.
query_id required | string <uuid> View identifier. |
{- "name": "view1",
- "id": "7409b999-2a9a-40cd-89dc-8430d85e0391",
- "display_name": "Query One",
- "owner": {
- "company_id": 456,
- "company_name": "ExampleCorp",
- "company_slug": "examplecorp"
}, - "tags": [
- "tag1",
- "tag2"
], - "collaborators": {
- "type": "inclusion",
- "company_ids": [
- 789
]
}, - "is_owned": true,
- "metadata": {
- "created_at": "2024-04-12T19:57:05.012908",
- "created_by_user_id": 321,
- "updated_at": "2024-04-12T20:03:48.031825",
- "updated_by_user_id": 321
}, - "nql": "SELECT age FROM narrative.rosetta_stone",
- "schema": {
- "type": "object",
- "properties": {
- "age": {
- "display_name": "age",
- "type": "double"
}
}, - "required": [
- "id"
]
}
}
Updates a view
query_id required | string <uuid> View identifier. |
name | string (ViewName) It should be unique. Must be <= 256 characters and consist of only alphanumeric characters and underscores. |
display_name | string (DisplayName) Optional. Display Name must be non-empty and less than 1000 chars. |
tags | Array of strings (Tags) Optional. Each tag must be less than 256 chars. |
object (shared_Collaborators) A constraint describing which companies have read access to the view. | |
nql | string |
{- "name": "updated name",
- "tags": [
- "tag3"
]
}
{- "name": "view1",
- "id": "7409b999-2a9a-40cd-89dc-8430d85e0391",
- "display_name": "Query One",
- "owner": {
- "company_id": 456,
- "company_name": "ExampleCorp",
- "company_slug": "examplecorp"
}, - "tags": [
- "tag1",
- "tag2"
], - "collaborators": {
- "type": "inclusion",
- "company_ids": [
- 789
]
}, - "is_owned": true,
- "metadata": {
- "created_at": "2024-04-12T19:57:05.012908",
- "created_by_user_id": 321,
- "updated_at": "2024-04-12T20:03:48.031825",
- "updated_by_user_id": 321
}, - "nql": "SELECT age FROM narrative.rosetta_stone",
- "schema": {
- "type": "object",
- "properties": {
- "age": {
- "display_name": "age",
- "type": "double"
}
}, - "required": [
- "id"
]
}
}
Get all accessible views.
is_owned | boolean If |
tag | string Filters views that are tagged with |
page | integer Number of page. Stars from the first (1) page. |
per_page | integer Number of records to return. |
{- "prev_page": null,
- "current_page": 1,
- "next_page": null,
- "total_records": 1,
- "total_pages": 1,
- "records": [
- {
- "name": "view1",
- "id": "7409b999-2a9a-40cd-89dc-8430d85e0391",
- "display_name": "View One",
- "owner": {
- "company_id": 456,
- "company_name": "ExampleCorp",
- "company_slug": "examplecorp"
}, - "tags": [
- "tag1",
- "tag2"
], - "collaborators": {
- "type": "inclusion",
- "company_ids": [
- 789
]
}, - "is_owned": true,
- "metadata": {
- "created_at": "2024-04-12T19:57:05.012908",
- "created_by_user_id": 321,
- "updated_at": "2024-04-12T20:03:48.031825",
- "updated_by_user_id": 321
}, - "nql": "SELECT age FROM narrative.rosetta_stone",
- "schema": {
- "type": "object",
- "properties": {
- "age": {
- "display_name": "age",
- "type": "double"
}
}, - "required": [
- "id"
]
}
}
]
}
Any number of properties can be updated on the same request. If a property is not sent on the payload, the value won't be updated.
name required | string (ViewName) It should be unique. Must be <= 256 characters and consist of only alphanumeric characters and underscores. |
display_name | string (DisplayName) Optional. Display Name must be non-empty and less than 1000 chars. |
tags | Array of strings (Tags) Optional. Each tag must be less than 256 chars. |
required | object (shared_Collaborators) A constraint describing which companies have read access to the view. |
nql required | string |
{- "name": "view 1",
- "display_name": "View One",
- "tags": [
- "tag1",
- "tag2"
], - "collaborators": {
- "type": "inclusion",
- "company_ids": [
- 789
]
}, - "nql": "SELECT age FROM narrative.rosetta_stone"
}
{- "name": "view1",
- "id": "7409b999-2a9a-40cd-89dc-8430d85e0391",
- "display_name": "Query One",
- "owner": {
- "company_id": 456,
- "company_name": "ExampleCorp",
- "company_slug": "examplecorp"
}, - "tags": [
- "tag1",
- "tag2"
], - "collaborators": {
- "type": "inclusion",
- "company_ids": [
- 789
]
}, - "is_owned": true,
- "metadata": {
- "created_at": "2024-04-12T19:57:05.012908",
- "created_by_user_id": 321,
- "updated_at": "2024-04-12T20:03:48.031825",
- "updated_by_user_id": 321
}, - "nql": "SELECT age FROM narrative.rosetta_stone",
- "schema": {
- "type": "object",
- "properties": {
- "age": {
- "display_name": "age",
- "type": "double"
}
}, - "required": [
- "id"
]
}
}
company_id required | integer <int64> Example: 345 The id of an existing company |
{- "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",
- "image_url": null,
- "visibility": "visible",
- "status": "active",
- "website": null
}
company_id required | integer <int64> Example: 345 The id of an existing company |
{- "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",
- "image_url": null,
- "visibility": "visible",
- "status": "active",
- "website": null,
- "created_at": "2016-06-09T02:00:47Z",
- "last_updated_at": "2023-08-17T16:18:10.386058Z",
- "last_updated_by": "[email protected]"
}
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.
company_id required | integer <int64> Example: 345 The id of an existing company |
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" |
{- "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",
- "image_url": null,
- "visibility": "visible",
- "status": "active",
- "website": null
}
{- "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",
- "image_url": null,
- "visibility": "visible",
- "status": "active",
- "website": null,
- "created_at": "2016-06-09T02:00:47Z",
- "last_updated_at": "2023-08-17T16:18:10.386058Z",
- "last_updated_by": "[email protected]"
}
user_id required | integer <int64> (schemas_UserId) Example: 20 The user id |
name | string User name |
{- "name": "string"
}
{- "name": "string",
- "id": 20
}
{- "records": [
- {
- "metadata": {
- "revision": 42,
- "timestamp": "2021-11-23T20:37:32.452Z"
}, - "payload_type": "PerformDelivery",
- "payload": {
- "subscriptionId": "0889d6d0-d31b-4196-b2fd-66e219f2e5e4",
- "transactionBatchId": "4202d94d-41eb-4e45-9468-fd75d47804ac",
- "profileId": "d13867f7-a6c0-4f83-b129-f6c6f2de7c15",
- "quickSettings": {
- "bucketprefix": "/mydelivery"
}
}
}
]
}
Lists delivery files for a particular delivery command.
delivery_id required | integer Unique identifier for an delivery record. |
[- {
- "company_id": 1,
- "file": "part-00001-cefc489b-7d3b-4409-8632-19122002bbd3-c000.json",
- "size": 8022466827,
- "subscription_id": "31ebdb17-6799-4447-a99c-6e3aa8da3237",
- "transaction_batch_id": "f6eeafa3-d599-4469-825c-bf0da93f68af",
- "timestamp": "2022-04-20T23:37:39Z"
}, - {
- "company_id": 1,
- "file": "part-00002-cefc489b-7d3b-4409-8632-19122002bbd3-c000.json",
- "size": 8022349030,
- "subscription_id": "31ebdb17-6799-4447-a99c-6e3aa8da3237",
- "transaction_batch_id": "f6eeafa3-d599-4469-825c-bf0da93f68af",
- "timestamp": "2022-04-20T23:36:52Z"
}
]
Generates a download url for a particular delivery file
delivery_id required | integer Unique identifier for an delivery record. |
filename required | string Name of a delivery file. |
{- "records": [
- {
- "metadata": {
- "revision": 42,
- "timestamp": "2021-11-23T20:37:32.452Z"
}, - "payload_type": "PerformDelivery",
- "payload": {
- "subscriptionId": "0889d6d0-d31b-4196-b2fd-66e219f2e5e4",
- "transactionBatchId": "4202d94d-41eb-4e45-9468-fd75d47804ac",
- "profileId": "d13867f7-a6c0-4f83-b129-f6c6f2de7c15",
- "quickSettings": {
- "bucketprefix": "/mydelivery"
}
}
}
]
}
Create a new permission
resource required | string Resource type associated with a permissions |
required | object Status of a permission |
required | object Verb (action) associated with a permissions |
{- "resource": "test_resource",
- "status": {
- "type": "active"
}, - "verb": {
- "type": "admin"
}
}
{- "error": "Unauthorized",
- "error_description": "You are not authorized to use this endpoint."
}
{- "user_id": 407,
- "name": "John Doe",
- "company_access_list": [
- 1
], - "current_company_scope": {
- "company_id": 1,
- "slug": "narrative",
- "name": "Narrative, Inc (id 1!)",
- "short_description": "Another New Short Description",
- "long_description": "Narrative Long Description",
- "contact_email": null,
- "image_url": null,
- "status": "active",
- "visibility": "visible"
}, - "created_at": "2022-11-29T21:42:24.978707Z",
- "created_by": null,
- "last_updated_at": null,
- "last_updated_by": null
}