NAV

Introduction

Welcome to the Polymer public API documentation! You can use our API to access Polymer API endpoints, that provide various functionality present on our website.

Endpoints description, method, URL, request/response schema, and their description are presented on the left. The right side contains example requests (via curl) and responses (in JSON). In the future, more endpoints will be added to provide complete access to Polymer database.

If this is your first time reading the docs, check out the Authentication section for obtaining and using API keys.

The Changelog section contains all updates related to this API.

Authentication

Polymer API uses API keys to allow access to our endpoints. You can register a new API key as a user, inside user settings, on the API Keys section.

Currently you can create as many API Keys as you want and give them a name. Once you don't want to use it you can disable it from the dashboard.

Polymer API expects the API key to be included in all API requests to the server. There are two ways to include it in requests:

As a query parameter: ?api_key=&your_api_key

As a header: X-API-KEY: &your_api_key

Please note that the "workspace-id" header is optional. It is only necessary when you intend to execute an operation within a workspace other than the default one defined by the APIKEY.

Rate Limiting

All Polymer APIs have rate limiting implemented. A single API key can make up to 100 requests per hour. After reaching the rate limit, HTTP Status 429 - Too Many Requests will be returned.

Response headers contain rate-limiting details:

Currently there is no rate limiting per user, but it may be introduced in future updates.

Errors

The Polymer API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
404 Not Found -- The specified item could not be found.
405 Method Not Allowed -- You tried to access the API with an invalid method.
429 Too Many Requests -- You're making too many request.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Workspace

Create a new workspace

curl --location --request POST 'https://v3.polymersearch.com/api/v1/workspace' \
--header 'accept: application/json, text/plain, */*' \
--header 'x-api-key: {{apikey}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "My Workspace Name",
    "slug": "workspace-slug"
}'

HTTP Request

POST https://v3.polymersearch.com/api/v1/workspace

Body content

Field Mandatory Description
name true Name of the workspace.
slug true slug to be used in custom URLs. Alphanumeric characters, underscores, and dashes are allowed. It cannot end with an underscore or a dash.

Get workspaces

curl --location --request GET 'https://v3.polymersearch.com/api/v1/workspaces' \
--header 'accept: application/json, text/plain, */*' \
--header 'x-api-key: {{apikey}}'

HTTP Request

GET https://v3.polymersearch.com/api/v1/workspaces

The above command returns JSON structured like this:

{
    "data": [
        {
            "_id": "636e0856759be73b280cfa11",
            "slug": "api-demo",
            "name": "Polymer's Workspace",
            "default_name_unedited": true,
            "user_role": "Creator",
            "default": true,
            "members": [
                {
                    "_id": "636e0856759be7e1f00cfa0f",
                    "name": "Polymer Search",
                    "email": "[email protected]"
                }
            ]
        },
        {
            "_id": "638850663e5ca0629efc34ed",
            "name": "Marketing",
            "slug": "polymer-marketing",
            "user_role": "Creator",
            "default": false,
            "members": [
                {
                    "_id": "636e0856759be7e1f00cfa0f",
                    "name": "Polymer Search",
                    "email": "[email protected]"
                },
                {
                    "_id": "638b60eb3dc9fa2645946403",
                    "name": "Remo",
                    "email": "[email protected]"
                },
                {
                    "_id": "6390cdea9a51cd0743387a6e",
                    "name": "Ras",
                    "email": "[email protected]"
                }
            ]
        }
    ]
}

Edit workspace

curl --location --request PATCH 'https://v3.polymersearch.com/api/v1/workspace/64c25eae9797258e69dff54d' \
--header 'x-api-key: {{apikey}}' \
--header 'Content-Type: application/json' \
--data '{
    "name": "My Workspace Edited name"
}'

HTTP Request

PATCH https://v3.polymersearch.com/api/v1/workspace/:id

Body content

Field Mandatory Description
name false Name of the workspace.
slug false slug to be used in custom URLs. Alphanumeric characters, underscores, and dashes are allowed. It cannot end with an underscore or a dash.

Delete workspace

curl --location --request DELETE 'https://v3.polymersearch.com/api/v1/workspace/638da37174ea61d5d9b9a6c7' \
--header 'accept: application/json, text/plain, */*' \
--header 'x-api-key: {{apikey}}'

HTTP Request

DELETE https://v3.polymersearch.com/api/v1/workspace/:id

The above command returns JSON structured like this:

{
    "success": true
}

URL Params

Field Mandatory Description
id true Type: String
_id field from '/v1/workspaces' response

Users

Fetch existing & invited workspace users

curl --location --request GET 'https://v3.polymersearch.com/api/v1/workspace/users' \
--header 'accept: application/json, text/plain, */*' \
--header 'x-api-key: {{apikey}}'

HTTP Request

GET https://v3.polymersearch.com/api/v1/workspace/users

The above command returns JSON structured like this:

{
    "data": [
        {
            "_id": "636e0856759be7e1f00cfa0f",
            "name": "Polymer Search",
            "email": "[email protected]",
            "role": "Creator"
        },
        {
            "_id": "6389db43daeaa35b76482b14",
            "name": "Name User",
            "email": "[email protected]",
            "role": "Editor"
        },
        {
            "_id": "638da37174ea61d5d9b9a6c7",
            "name": "Sam Title",
            "email": "[email protected]",
            "role": "Read-only"
        },
        {
            "role": "Read-only",
            "_id": "63ec8c9a41f84c7d02ee344e",
            "email": "[email protected]",
            "pending": true,
            "invitation_id": "63ec8c9a41f84c7d02ee344e"
        }
    ]
}

Invite a new member to workspace

curl --location --request POST 'https://v3.polymersearch.com/api/v1/workspace/invite' \
--header 'accept: application/json, text/plain, */*' \
--header 'x-api-key: {{apikey}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "members": [
        {
            "email": "[email protected]",
            "role": "Read-only"
        }
    ]
}'

HTTP Request

POST https://v3.polymersearch.com/api/v1/workspace/invite

The above command returns JSON structured like this:

{
    "success": true,
    "invited": true
}

Body content

Field Mandatory Description
members true List of members to invite
members[].email true valid email ID
members[].role true Valid values: Editor, Read-only
skip_invite_email false Boolean

Delete existing or invited workspace user

curl --location --request DELETE 'https://v3.polymersearch.com/api/v1/workspace/user/638da37174ea61d5d9b9a6c7' \
--header 'accept: application/json, text/plain, */*' \
--header 'x-api-key: {{apikey}}'

HTTP Request

DELETE https://v3.polymersearch.com/api/v1/workspace/user/:wuid

The above command returns JSON structured like this:

{
    "message": "user deleted successfully"
}

URL Params

Field Mandatory Description
wuid true Type: String
_id field from '/v1/workspace/users' response

Dataset

The Dataset API allows the creation of new Polymer sites from your CSV files.

Upload a Dataset

This endpoint starts processing provided CSV.

curl --location --request POST 'https://v3.polymersearch.com/api/v1/dataset' \
--header 'x-api-key: XXd5c7f6-XXf9-4320-XX4d-5673d8XXd5bb' \
--header 'Content-Type: application/json' \
--data-raw '{
    "url": "https://abcc.s3.amazonaws.com/myfile.csv",
    "name": "Payment yearly.csv",
    "starting_row": 10,
    "update": true
}'

curl --location --request POST 'https://v3.polymersearch.com/api/v1/dataset' \
--header 'x-api-key: XXd5c7f6-feXX-43XX-XX4d-5673d8f0d5XX' \
--header 'Content-Type: application/json' \
--data-raw '{
    "url": "https://abcc.s3.amazonaws.com/myfile.csv",
    "name": "Payment yearly2.csv"
}'

curl --location --request POST 'https://v3.polymersearch.com/api/v1/dataset' \
--header 'x-api-key: XXd5c7f6-feXX-43XX-XX4d-5673d8f0d5XX' \
--header 'Content-Type: application/json' \
--data-raw '{
    "ingestion_type": "json",
    "name": "Payment yearly3.csv",
    "records": [
        {
            "ticket_id": "ID2",
            "created_at": "2022-10-21",
            "language": "Spanish",
            "number1": 14
        },{
            "ticket_id": "ID2",
            "created_at": "2022-10-21",
            "language": "Spanish",
            "number1": 14
        }
    ]
}'

curl --location --request POST 'https://v3.polymersearch.com/api/v1/dataset' \
--header 'x-api-key: XXd5c7f6-feXX-43XX-XX4d-5673d8f0d5XX' \
--form 'name="Payment yearly 2022 920.csv"' \
--form 'file=@"/local_file_path/file_name.csv"'

The above command returns JSON structured like this:

{
    "task_id": "65c3249d63a20b6727a11127"
}

HTTP Request

POST https://v3.polymersearch.com/api/v1/dataset

Body content

Field Mandatory Description
url false URL to a valid public downloadable CSV.
file false Type: file. The file to upload.
name true Name of the dataset/file.
starting_row false Desired row number where Polymer should start processing your file.
update false Boolean. Force update dataset in case a dataset already exists with the given name.

Note: Either 'url' or 'file' parameter is required.

Update a Dataset

This endpoint updates the content and metadata of an existing dataset.

curl --location --request PUT 'https://v3.polymersearch.com/api/v1/dataset/6151754dfad3627deeb8f84b' \
--header 'x-api-key: XXeca66c-21f3-XX39-b407-64e00c62XXXX' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "FB Ad List Q2 C-uploaded.csv",
    "url": "https://test-csv-datasets.s3.us-east-2.amazonaws.com/Test+-+Bank+Loans.csv"
}'

The above command returns JSON structured like this:

{
    "task_id": "65c324f463a20b6727a1116b"
}

The above command returns JSON structured like this:

{
    "success": false,
    "errors": [
        {
            "message": "duplicate file name"
        }
    ]
}

HTTP Request

PUT https://v3.polymersearch.com/api/v1/dataset/:id

Params content

Field Mandatory Description
id true Dataset ID.

Body content

Field Mandatory Description
url false URL to a valid public downloadable CSV.
file false Type: file. The file to upload.
name false Name of the dataset/file.
incremental_update In case you are passing incremental updates only
primary_key Yes if incremental_update = true name of the column

Fetch Datasets

This endpoint returns list of datasets

curl --location --request PUT 'https://v3.polymersearch.com/api/v1/dataset' \
--header 'x-api-key: XXeca66c-21f3-XX39-b407-64e00c62XXXX' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "FB Ad List Q2 C-uploaded.csv",
    "url": "https://test-csv-datasets.s3.us-east-2.amazonaws.com/Test+-+Bank+Loans.csv"
}'

The above command returns JSON structured like this:

{
    "data": [
    {
        "_id": "65d775c6428356ae03b21b1f",
        "user": "65d775a24283563f98b21a75",
        "user_email": "[email protected]",
        "name": "11_payment 624 CSV copy 1114.csv",
        "source_type": "upload",
        "workspace_id": "65d775a24283564ab4b21a81",
        "created_at": "2024-02-22T16:26:46.352Z",
        "extension": "csv",
        "num_rows": 59626,
        "status": "success",
        "id": "65d775c6428356ae03b21b1f"
    },
    {
        "_id": "65d778bc4283568b69b221ef",
        "user": "65d775a24283563f98b21a75",
        "user_email": "[email protected]",
        "name": "DS1",
        "source_type": "api",
        "workspace_id": "65d775a24283564ab4b21a81",
        "extension": "csv",
        "created_at": "2024-02-22T16:39:24.358Z",
        "num_rows": 5,
        "status": "success",
        "id": "65d778bc4283568b69b221ef"
    },
    {
        "_id": "65ddabc9428356050bb89426",
        "user": "65d775a24283563f98b21a75",
        "user_email": "[email protected]",
        "name": "File upload demo dataset",
        "source_type": "api",
        "workspace_id": "65d775a24283564ab4b21a81",
        "extension": "csv",
        "created_at": "2024-02-27T09:30:49.830Z",
        "num_rows": 5,
        "status": "success",
        "id": "65ddabc9428356050bb89426"
    }],
    "limit": 100,
    "page": 1,
    "sort_key": "name",
    "sort_order": "asc"
}

HTTP Request

GET https://v3.polymersearch.com/api/v1/dataset

Query string

Field Mandatory Description
limit false Page limit.
page false Page number.
sort_key false name, created_at, num_rows
sort_order false desc,asc

Task

Fetch Status

curl --location --request GET 'https://v3.polymersearch.com/api/v1/task/65c324f463a20b6727a1116b' \
--header 'accept: application/json, text/plain, */*' \
--header 'x-api-key: {{apikey}}'

The above command returns JSON structured like this:

{
    "file_id": "65c32d8334632067c1d32d18",
    "status": "inprogress"
}

{
    "file_id": "65bc94d3cdb8f39435d3e21a",
    "status": "done"
}

{
    "status": "done",
    "error": "An error has occurred (processing timeout). Our team is looking into it."
}

HTTP Request

GET https://v3.polymersearch.com/api/v1/task/:id

Body content

Field Datatype Description
status String If set to 'done' then task is executed and you can find file_id. If set to 'inprogress' please poll again in 5 seconds
error String if we encounter any processing error

Board

With boards API you can create blocks and data segments and share them with the world instead of exposing the complete Polymer site. Embed in your site a manually selected block for your data, or let our powerful AI determine what are the best blocks for your data.

Create Board

Example 1: Create a basic board with 2 blocks

curl --location --request POST 'https://v3.polymersearch.com/api/v1/board' \
--header 'x-api-key: {{apikey}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Sample Board 1",
    "file_ids": [
        "65b50541d83d1e4d42c7fbe0"
    ],
    "sharing": "public",
    "advanced_sharing":
    {
        "allow_global_filters_for_viewers": false,
        "allow_block_based_filters_for_viewers": true
    },
    "filters":
    {},
    "blocks": [
    {
        "type": "kpi",
        "metric": "time_spent_in_days",
        "operation": "SUM",
        "date": "solved_at",
        "date_range": "last 90 days",
        "goal": 1000,
        "file_id": "65b50541d83d1e4d42c7fbe0",
        "comp_date_range": "previous month"
    },
    {
        "type": "data-table",
        "columns": [
            "ticket_group"
        ],
        "values": [
        {
            "column": "time_spent_in_minutes",
            "operation": "SUM"
        }],
        "sort":
        {
            "column": "time_spent_in_minutes",
            "order": "DESC"
        },
        "show_totals": false,
        "file_id": "65b50541d83d1e4d42c7fbe0"
    }
    ]
}'

The above command returns JSON structured like this:

{
    "launch_url": "https://v3.polymersearch.com/b/6409bc2ae761d55b4630989b",
    "id": "6409bc2ae761d55b4630989b"
}

HTTP Request

POST https://v3.polymersearch.com/api/v1/board

Body content

Field Mandatory Description
name true Type: String
Name of the board
file_ids true Type: List[String]
Dataset IDs of the board
blocks true Type: List [Blocks Object]
sharing false Desired sharing status for the dataset (public, private). Default: private
advanced_sharing false control sharing settings for board
advanced_sharing.allow_global_filters_for_viewers false Type: Boolean
Viewers would be able to apply global filters
advanced_sharing.allow_block_based_filters_for_viewers false Type: Boolean
Viewers would be able to apply block based filters
branding.logoUrl false Logo URL
branding.logoLink false Link to redirect when clicked on logo URL
colors false Type: List
List of color codes to be used in view preview mode.
auto_generated false Type: Boolean
Auto generted board

Blocks Object

Bar Chart

{
    "type": "bar",
    "x_axis_multiple": [
    {
        "name": "spend",
        "operation": "SUM"
    },
    {
        "name": "Clicks (all)",
        "operation": "COUNT"
    }],
    "y_axis": "campaign_status",
    "operation": "SUM",
    "y_axis_log": true,
    "show_annotations": true,
    "show_stacked": false,
    "file_id": "65b50541d83d1e4d42c7fbe0"
}
Field Datatype Mandatory Desc
type String Yes bar
file_id String Yes file ID to drive this block
x_axis List one of the x_axis or x_axis_multiple is required valid column name
x_axis_multiple List one of the x_axis or x_axis_multiple is required Object, Min length: 2, Max length: 10.
name: valid column
operation: Any value from COUNT, SUM, AVERAGE, STDDEV, VARIANCE, MAX, MIN
y_axis String Yes valid column name
operation String No Any value from COUNT, SUM, AVERAGE, STDDEV, VARIANCE, MAX, MIN
sort Object No type: total (Total), raw (Raw Order), count (Count), value (x-axis tags)
operation: Any value from asc, desc
slice String No valid column name
show_annotations Boolean No Annotate each segment by its value
show_stacked Boolean No Show as stack. Default: true
is_percentage Boolean No Show as percentage
y_axis_log Boolean No Use logarithmic scale for Y-Axis
exclude_empty_string Boolean No Exclude [EMPTY] strings. Default: true
width Boolean No Any value from one-third , two-thirds, full. Default: full
filters Object No Filter Object
title String No Custom heading

Column Chart

{
    "type": "column",
    "x_axis": "campaign_status",
    "y_axis_multiple": [
    {
        "name": "spend",
        "operation": "SUM"
    },
    {
        "name": "Clicks (all)",
        "operation": "COUNT"
    }],
    "operation": "SUM",
    "show_annotations": true,
    "show_stacked": false,
    "file_id": "65b50541d83d1e4d42c7fbe0"
}
Field Datatype Mandatory Desc
type String Yes column
file_id String Yes file ID to drive this block
x_axis String Yes valid column name
y_axis String one of the y_axis or y_axis_multiple is required valid column name
y_axis_multiple List one of the y_axis or y_axis_multiple is required Object, Min length: 2, Max length: 10.
name: valid column
operation: Any value from COUNT, SUM, AVERAGE, STDDEV, VARIANCE, MAX, MIN
operation String No Any value from COUNT, SUM, AVERAGE, STDDEV, VARIANCE, MAX, MIN
sort Object No type: total (Total), raw (Raw Order), count (Count), value (x-axis tags)
operation: Any value from asc, desc
slice String No valid column name
show_annotations Boolean No Annotate each segment by its value
show_stacked Boolean No Show as stack. Default: true
is_percentage Boolean No Show as percentage
x_axis_log Boolean No Use logarithmic scale for X-Axis
exclude_empty_string Boolean No Exclude [EMPTY] strings. Default: true
width Boolean No Any value from one-third , two-thirds, full. Default: full
filters Object No Filter Object
title String No Custom heading

SCATTER PLOT Chart

{
    "type": "scatter",
    "x_axis": "spend",
    "y_axis": "cost_per_initiate_checkout",
    "operation": "SUM",
    "x_axis_log": true,
    "file_id": "65b50541d83d1e4d42c7fbe0"
}
Field Datatype Mandatory Desc
type String Yes scatter
file_id String Yes file ID to drive this block
x_axis String Yes valid number column name
y_axis String Yes valid number column name
operation String Yes Any value from COUNT, SUM, AVERAGE, STDDEV, VARIANCE, MAX, MIN
slice String No valid column name
x_axis_log Boolean No Use logarithmic scale for X-Axis
y_axis_log Boolean No Use logarithmic scale for Y-Axis
exclude_empty_string Boolean No Exclude [EMPTY] strings. Default: true
width Boolean No Any value from one-third , two-thirds, full. Default: full
filters Object No Filter Object
title String No Custom heading

TIMESERIES Chart

{
    "type": "timeseries",
    "x_axis": "date",
    "operation": "SUM",
    "y_axis_log": true,
    "exclude_empty_string": false,
    "group_by": "quarter",
    "is_area": true,
    "file_id": "65b50541d83d1e4d42c7fbe0"
}
Field Datatype Mandatory Desc
type String Yes timeseries
file_id String Yes file ID to drive this block
x_axis String Yes valid date column name
y_axis String No valid number column name
y_axis_multiple List No Object, Min length: 2, Max length: 10.
name: valid number column
operation: Any value from COUNT, SUM, AVERAGE, STDDEV, VARIANCE, MAX, MIN
slice String No valid column name
is_area Boolean No Use area chart
y_axis_log Boolean No Use logarithmic scale for Y-Axis
exclude_empty_string Boolean No Exclude [EMPTY] strings. Default: true
group_by String No Any value from day, week, month, quarter, year
width Boolean No Any value from one-third , two-thirds, full. Default: full
filters Object No Filter Object
title String No Custom heading

HEATMAP Chart

{
    "type": "heatmap",
    "y_axis": "account_currency",
    "operation": "SUM",
    "exclude_empty_string": false,
    "show_annotations": true,
    "file_id": "65b50541d83d1e4d42c7fbe0"
}
Field Datatype Mandatory Desc
type String Yes heatmap
file_id String Yes file ID to drive this block
y_axis String Yes valid column name
x_axis String No valid column name
operation String Yes Any value from COUNT, SUM, AVERAGE, STDDEV, VARIANCE, MAX, MIN
slice String No valid column name
show_annotations Boolean No Annotate each segment by its value
exclude_empty_string Boolean No Exclude [EMPTY] strings. Default: true
width Boolean No Any value from one-third , two-thirds, full. Default: full
filters Object No Filter Object
title String No Custom heading

LINEPLOT Chart

{
    "type": "lineplot",
    "x_axis": "spend",
    "y_axis": "link_click",
    "operation": "SUM",
    "file_id": "65b50541d83d1e4d42c7fbe0"
}
Field Datatype Mandatory Desc
type String Yes lineplot
file_id String Yes file ID to drive this block
y_axis String one of the y_axis or y_axis_multiple is required valid column name
y_axis_multiple List one of the y_axis or y_axis_multiple is required Object, Min length: 2, Max length: 10.
name: valid column
operation: Any value from COUNT, SUM, AVERAGE, STDDEV, VARIANCE, MAX, MIN
x_axis String Yes valid column name
operation String Yes Any value from COUNT, SUM, AVERAGE, STDDEV, VARIANCE, MAX, MIN
slice String No valid column name
y_axis_log Boolean No Use logarithmic scale for Y-Axis
exclude_empty_string Boolean No Exclude [EMPTY] strings. Default: true
width Boolean No Any value from one-third , two-thirds, full. Default: full
filters Object No Filter Object
title String No Custom heading

PIE Chart

{
    "type": "pie",
    "x_axis_multiple": [
    {
        "name": "status"
    }],
    "exclude_empty_string": false,
    "show_annotations": true,
    "file_id": "65b50541d83d1e4d42c7fbe0"
}
Field Datatype Mandatory Desc
type String Yes pie
file_id String Yes file ID to drive this block
x_axis_multiple List Yes Object, Min length: 1, Max length: 2.
name: valid column
y_axis_multiple List No Object, Min length: 1, Max length: 1.
name: valid number column
operation: Any value from COUNT, SUM, AVERAGE, STDDEV, VARIANCE, MAX, MIN
show_annotations Boolean No Annotate each segment by its value
exclude_empty_string Boolean No Exclude [EMPTY] strings. Default: true
width Boolean No Any value from one-third , two-thirds, full. Default: full
filters Object No Filter Object
title String No Custom heading

OUTLIER

{
    "type": "outlier",
    "metric": "spend",
    "operation": "COUNT",
    "exclude_empty_string": false,
    "influencing_columns": [
        "ad_name"
    ],
    "file_id": "65b50541d83d1e4d42c7fbe0"
}
Field Datatype Mandatory Desc
type String Yes outlier
file_id String Yes file ID to drive this block
metric String Yes valid number column name
operation String Yes Any value from COUNT, SUM, AVERAGE, STDDEV, VARIANCE, MAX, MIN
influencing_columns List Yes Influencing Columns - list of valid column names. Min length: 1, Max length: 6
results_type String No Show results - Any value from count, below_average_only, above_average_only, top_and_bottom_outliers, above_and_below_average
show_results_column Boolean No Show Results Column
exclude_empty_string Boolean No Exclude [EMPTY] strings
width Boolean No Any value from one-third , two-thirds, full. Default: full
filters Object No Filter Object
title String No Custom heading
lower_better Boolean No Lower Better

ROI CALCULATOR

{
    "type": "roi",
    "max_metric": "impressions",
    "max_operation": "AVERAGE",
    "min_metric": "spend",
    "min_operation": "MAX",
    "influencing_columns": [
        "ad_name",
        "campaign_name"
    ],
    "show_results_column": false,
    "file_id": "65b50541d83d1e4d42c7fbe0"
}
Field Datatype Mandatory Desc
type String Yes roi
file_id String Yes file ID to drive this block
max_metric String Yes Metric to Maximize (Return) - valid number column name
max_operation String Yes Any value from COUNT, SUM, AVERAGE, STDDEV, VARIANCE, MAX, MIN
min_metric String Yes Metric to Minimize (Investment) - valid number column name
min_metric String Yes Any value from COUNT, SUM, AVERAGE, STDDEV, VARIANCE, MAX, MIN
influencing_columns List Yes Influencing Columns - list of valid column names. Min length: 1, Max length: 6
show_results_column Boolean No Show Results Column
show_percentage Boolean No Show ROI as Percentage
exclude_empty_string Boolean No Exclude [EMPTY] strings
width Boolean No Any value from one-third , two-thirds, full. Default: full
filters Object No Filter Object
title String No Custom heading
lower_better Boolean No Lower Better

PIVOT TABLE

{
    "type": "pivot",
    "metrics": [
    {
        "metric": "spend",
        "operation": "SUM"
    }],
    "rows": [
        "account_currency"
    ],
    "columns": ["ad_name"],
    "file_id": "65b50541d83d1e4d42c7fbe0"
}
Field Datatype Mandatory Desc
type String Yes pivot
file_id String Yes file ID to drive this block
metrics List Yes Object, Min length: 1, Max length: 10.
metric: valid column
operation: Any value from COUNT, SUM, AVERAGE, STDDEV, VARIANCE, MAX, MIN
rows List Yes Rows - list of valid column names. Min length: 1, Max length: 1
columns List Yes Columns - list of valid column names. Min length: 1, Max length: 1
show_row_totals Boolean No Show Row Totals
show_column_totals Boolean No Show Column Totals
show_percentage Boolean No Show Percentage, Default: True
sort_by_row_tags String No Sort rows by tag value. Any value from ASC, DESC
column_manual_order List No Sort columns by column tags. List of tag values
sort_by_counts Object No column_index: index of the column given in columns
metric_index: index of the column given in metrics
order: Any value from ASC, DESC
width Boolean No Any value from one-third , two-thirds, full. Default: full
filters Object No Filter Object
title String No Custom heading
pin_totals Boolean No Pin Totals

KPI BLOCK

{
    "type": "kpi",
    "metric": "impressions",
    "operation": "SUM",
    "date": "date",
    "date_range": "last 90 days",
    "goal": 4000000,
    "file_id": "65b50541d83d1e4d42c7fbe0"
}
Field Datatype Mandatory Desc
type String Yes kpi
file_id String Yes file ID to drive this block
metric List Yes valid date column name
operation String Yes Any value from COUNT, SUM, AVERAGE, STDDEV, VARIANCE, MAX, MIN
date String No valid date column name
date_range String No Any value from 'last day', 'last 7 days', 'last 14 days', 'last 30 days', 'last 90 days', 'last 6 months', 'last 12 months, 'this month', 'this week', 'last week', custom
comp_date_range String No Any value from 'previous period', 'custom'
goal Number No
exclude_empty_string Boolean No Exclude [EMPTY] strings
width Boolean No Any value from one-third , two-thirds, full. Default: full
filters Object No Filter Object

DATA TABLE

{
    "type": "data-table",
    "columns": [
        "ticket_group"
    ],
    "values": [
    {
        "column": "time_spent_in_minutes",
        "operation": "SUM"
    }],
    "sort":
    {
        "column": "time_spent_in_minutes",
        "order": "DESC"
    },
    "file_id": "65b50541d83d1e4d42c7fbe0"
}
Field Datatype Mandatory Desc
type String Yes data-table
file_id String Yes file ID to drive this block
columns List Yes valid column name
values List Yes Object, Min length: 1, Max length: 10.
column: valid column
operation: Any value from COUNT, SUM, AVERAGE, STDDEV, VARIANCE, MAX, MIN
sort Object Yes Object
column: valid column
order: Any value from ASC, DESC
exclude_empty_string Boolean No Exclude [EMPTY] strings
show_totals Boolean No Show Column Totals
width Boolean No Any value from one-third , two-thirds, full. Default: full
filters Object No Filter Object
title String No Custom heading

RICH TEXT

{
    "type": "rich-text-insight",
    "html": "<p><strong>This is just a header</strong></p><p><i>Add blocks of <u>your choice</u></i></p>"
}
Field Datatype Mandatory Desc
type String Yes rich-text-insight
html String Yes HTML text
width Boolean No Any value from one-third , two-thirds, full. Default: full

Field: filters

Allowed values: object

The following filters can be applied

Example payload { "65b50541d83d1e4d42c7fbe0": { "Submission Date": [ { "value": "last 30 days" }], "amount": [ { "value": [ 10, 20 ] }], "Payment Mechanism": [ { "value": "cash", "operation": "INCLUDING" }] } }

The following filter will be read as

Submission Date within last 30 days AND amount between range 10 to 20 AND Payment Mechanism INCLUDING cash

Possible dynamic date ranges:

Possible operations:

Edit Board

Example 1: Edit board with blocks

curl --location --request PUT 'https://v3.polymersearch.com/api/v1/board/63f36125bfc81986e3cbd2c3' \
--header 'x-api-key: {{apikey}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "blocks": [
    {
        "type": "timeseries",
        "x_axis": "payment_mechanism",
        "y_axis": "Submission Date",
        "slice": "amount"
    },
    {
        "type": "bar",
        "x_axis": "Fee Month",
        "y_axis": "amount",
        "slice": "Submission Date",
        "operation": "MIN"
    }]
}'

Example 2: Edit board with blocks and name

curl --location --request PUT 'https://v3.polymersearch.com/api/v1/board/63f36125bfc81986e3cbd2c3' \
--header 'x-api-key: {{apikey}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Edited Board Name",
    "blocks": [
    {
        "type": "bar",
        "x_axis": "payment_mechanism",
        "y_axis": "Submission Date",
        "slice": "amount",
        "operation": "SUM"
    },
    {
        "type": "bar",
        "x_axis": "Fee Month",
        "y_axis": "amount",
        "slice": "Submission Date",
        "operation": "MIN"
    }]
}'

The above command returns JSON structured like this:

{
    "launch_url": "https://v3.polymersearch.com/b/6409bc2ae761d55b4630989b",
    "id": "6409bc2ae761d55b4630989b"
}

HTTP Request

PUT https://v3.polymersearch.com/api/v1/board/:board_id

URL Params

Field Mandatory Description
board_id true Type: String
Board ID

Body content

Field Mandatory Description
name false Type: String
Name of the board
blocks false Type: List [Blocks Object]
sharing false Desired sharing status for the dataset (public, private). Default: private
advanced_sharing false control sharing settings for board
advanced_sharing.allow_global_filters_for_viewers false Type: Boolean
Viewers would be able to apply global filters
advanced_sharing.allow_block_based_filters_for_viewers false Type: Boolean
Viewers would be able to apply block based filters
branding.logoUrl false Logo URL
branding.logoLink false Link to redirect when clicked on logo URL
colors false Type: List
List of color codes to be used in view preview mode.

Blocks Object

Same as described on Create Board request Note: Make sure you pass all the blocks inside blocks key

Fetch Boards

Response

{
    "data": [
        {
            "_id": "63f36125bfc81986e3cbd2c3",
            "created_at": "2023-02-20T12:01:41.730Z",
            "updated_at": "2023-02-20T12:01:41.730Z",
            "uid": "abf3a195-4135-4471-9d24-ab2acde3e45a",
            "user_id": "636e0856759be7e1f00cfa0f",
            "file_id": "63d8248de061fa0d2023f20a",
            "name": "board - 1",
            "sharing": "public",
            "is_template": "false"
        },
        {
            "_id": "6409bb0be045c05b1fccb721",
            "created_at": "2023-03-09T10:55:07.578Z",
            "updated_at": "2023-03-09T10:55:07.578Z",
            "uid": "52f0ecfa-9545-4a0b-8e7f-8d47c1aefcb9",
            "user_id": "636e0856759be7e1f00cfa0f",
            "file_id": "6409b295e0eb635a29d8c8f7",
            "name": "Board with advanced_sharing",
            "sharing": "public",
            "advanced_sharing": {
                "allow_global_filters_for_viewers": false,
                "allow_block_based_filters_for_viewers": true
            }
        },
        {
            "_id": "6409bc2ae761d55b4630989b",
            "created_at": "2023-03-09T10:59:54.313Z",
            "updated_at": "2023-03-09T10:59:54.313Z",
            "uid": "7ce8918b-441e-4ee1-8977-970b47ea9b68",
            "user_id": "636e0856759be7e1f00cfa0f",
            "file_id": "6409b295e0eb635a29d8c8f7",
            "name": "Board with advanced_sharing11",
            "sharing": "public",
            "advanced_sharing": {
                "allow_global_filters_for_viewers": false,
                "allow_block_based_filters_for_viewers": true
            }
        }
    ],
    "limit": 10,
    "page": 1,
    "sort_key": "created_at",
    "sort_order": "asc"
}

HTTP Request

GET https://v3.polymersearch.com/api/v1/boards

Delete Board

Response

{
   "success": true
}

HTTP Request

DELETE https://v3.polymersearch.com/api/v1/board/:board_id

URL Params

Field Mandatory Description
board_id true Type: String
Board ID

Embed

Polymer generated app can be embed to create new boards (views), and browse/edit existing ones:

Generate an auth token

This endpoint generates token to give authenticated access to embeded apps:

HTTP Request

GET https://v3.polymersearch.com/api/v1/auth/token?access_level=${permission_level}

Query string

Field Mandatory Description
permission_level true board_read_only : Grant permission for reading data from the specified board ID.

board_edit : Grant permission for reading/editing data from the specified board ID.

workspace_read_only: Authorize access for reading (read-only) all board data within the workspace.

workspace_edit : Grant permission for reading, adding, and editing all board data within the workspace.

block_level_read_only : Grant permission for reading data from the specified block from board ID.
board_id false Required when granting board_read_only, block_level_read_only or board_edit permissions.

Request

curl --location 'https://v3.polymersearch.com/api/v1/auth/token?access_level=workspace_edit' \
--header 'x-api-key: XXd5c7f6-XXf9-4320-XX4d-5673d8XXd5bb' \
--header 'workspace-id: 64XX73dd2221f86XXbc934XX'

Note: workspace-id header is optional and only needed when you want to generate auth-token for a specific workspace which is different than default workspace defined with APIKEY

The above command returns JSON structured like this:

{
    "token": "XXXX72f4-df9c-XX6e-92XX-XXX09f41XX",
    "expires_at": "2023-07-20T12:15:40.741Z"
}

Generating an embed URL using an authentication token

https://v3.polymersearch.com/b/${board_id}?ptoken={token}