NAV

Introduction

Welcome to the Polymer Public API documentation! Our API enables you to interact with Polymer's endpoints, providing access to various functionalities available on our platform.

On the left, you'll find detailed information about each endpoint, including descriptions, methods, URLs, and request/response schemas. The right side features example requests (via cURL) and corresponding JSON responses. We plan to expand this documentation with additional endpoints to offer comprehensive access to the Polymer database.

If this is your first time using our API, start by reviewing the Authentication section to learn how to obtain and use API keys.

For updates and changes, refer to the Changelog section.

Authentication

Polymer API uses API keys to authenticate access to its endpoints. You can generate a new API key within your user settings under the "API Keys" section.

You can create multiple API keys, each with a custom name. If you no longer need an API key, you can disable it via the dashboard.

Include your API key in all requests to the Polymer API. There are two supported methods for passing the API key:

As a query parameter: ?api_key=&your_api_key

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

The "workspace-id" header is optional. It is required only when you need to perform operations in a workspace other than the default one associated with your API key.

Rate Limiting

All Polymer APIs enforce rate limiting. Each API key is allowed up to 100 requests per hour. Once the rate limit is reached, the server will respond with HTTP Status 429 - Too Many Requests.

Rate-limiting details are included in the response headers:

Currently, rate limiting is not applied on a per-user basis, but this 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 incorrect.
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 requests.
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",
    "settings": {
        "disable_share_button": true
    }
}'

HTTP Request

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

Body content

Field Mandatory Data Type Description
name true String Name of the workspace.
slug true String Slug to be used in custom URLs. Alphanumeric characters, underscores, and dashes are allowed. It cannot end with an underscore or a dash.
settings.disable_share_button false Boolean Set this flag to disable the share button on the board.
settings.disable_email_report false Boolean Set this flag to disable the Email Report section in share section.
settings.enable_polyai_in_read_only_permission false Boolean Set this flag to enable PolyAI on read-only permissions.
notifications.board_digest_emails.disabled false Boolean Set this flag to disable all board digest emails.
notifications.board_digest_emails.enabled_by_default false Boolean Set this flag to enable weekly digest emails on boards created.
notifications.board_digest_emails.exclude_workspace_members false Boolean Set this flag to send board digest emails only to the board owner.

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,
            "settings": {
                "disable_share_button": false,
                "disable_email_report": true
            },
            "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",
    "settings": {
        "disable_share_button": true,
        "enable_polyai_in_read_only_permission": true
    }
}'

HTTP Request

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

Body content

Field Mandatory Data Type Description
name false String Name of the workspace.
slug false String Slug to be used in custom URLs. Alphanumeric characters, underscores, and dashes are allowed. It cannot end with an underscore or a dash.
settings.disable_share_button false Boolean Set this flag to disable the share button on the board.
settings.disable_email_report false Boolean Set this flag to disable the Email Report section in share section.
settings.enable_polyai_in_read_only_permission false Boolean Set this flag to enable PolyAI on read-only permissions.
notifications.board_digest_emails.disabled false Boolean Set this flag to disable all board digest emails.
notifications.board_digest_emails.enabled_by_default false Boolean Set this flag to enable weekly digest emails on boards created.
notifications.board_digest_emails.exclude_workspace_members false Boolean Set this flag to send board digest emails only to the board owner.

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 Data Type Description
members true List List of members to invite.
members[].email true String A valid email ID.
members[].role true String Valid values: Editor, Read-only.
skip_invite_email false Boolean If true, the invitation email will not be sent.

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

Source

Get all connected sources

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

HTTP Request

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

The above command returns JSON structured like this:

{
    "data": [
        {
            "_id": "671a1e74a8de3b2575aa9053",
            "type": "snowflake",
            "name": "Staging",
            "updated_at": "2024-10-28T07:25:42.693Z",
            "created_at": "2024-10-24T10:16:20.765Z"
        },
        {
            "_id": "671f403c3a1b4f32cd64d421",
            "type": "snowflake",
            "name": "Prod",
            "updated_at": "2024-10-28T07:41:48.090Z",
            "created_at": "2024-10-28T07:41:48.090Z"
        }
    ]
}

Delete an existing source

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

HTTP Request

DELETE https://v3.polymersearch.com/api/v1/sources/:sourceid

The above command returns JSON structured like this:

{
    "success": true
}

URL Params

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

Connect a new Snowflake connector

curl --location --request POST 'https://v3.polymersearch.com/api/auth/snowflake/connection' \
--header 'accept: application/json, text/plain, */*' \
--header 'x-api-key: {{apikey}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Prod Instance",
    "account": "pjiigbt-tl75318",
    "username": "snowflake-username",
    "password": "snowflake-password"
}'

HTTP Request

POST https://v3.polymersearch.com/api/auth/snowflake/connection

Body content

Field Mandatory Data Type Description
name true String Desired name of the connector.
account true String Account of the Snowflake instance.
username true String Username of the Snowflake instance.
password true String Password of the Snowflake instance.

Edit an Existing Snowflake connector

curl --location --request PATCH 'https://v3.polymersearch.com/api/auth/snowflake/:sourceid/connection' \
--header 'x-api-key: {{apikey}}' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Staging Instance",
    "account": "pjiigbt-tl76209",
    "username": "snowflake-username",
    "password": "snowflake-password"
}'

HTTP Request

PATCH https://v3.polymersearch.com/api/auth/snowflake/:sourceid/connection

Body content

Field Mandatory Data Type Description
name false String Desired name of the connector.
account false String Account of the Snowflake instance.
username false String Username of the Snowflake instance.
password false String Password of the Snowflake instance.

Import data using newly connected Snowflake

curl --location 'https://v3.polymersearch.com/api/snowflake/671a1e74a8de3b2575aa9053' \
--header 'x-api-key: {{apikey}}' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Orders",
    "query": "SELECT * FROM DB1.PUBLIC.ORDERS ",
    "table_name": "ORDERS",
    "fetch_size": 50,
    "schema_name": "PUBLIC",
    "update_settings": {
        "type": "merge",
        "update_at_column": {
            "name": "ORDER_DATE"
        },
        "merge_column_name": "ORDER_ID"
    }
}'

HTTP Request

POST https://v3.polymersearch.com/api/snowflake/:sourceid

Body content

Field Mandatory Data Type Description
name true String Desired name of the imported dataset.
query true String Query to execute for data retrieval.
fetch_size true String Maximum number of rows to fetch per pull.
update_settings true String Settings for data updates.
update_settings.type true String Type of update: replace, merge, or append.
update_settings.merge_column_name true String Column name for merging if type is set to merge.
update_settings.update_at_column. name false String Column for tracking last pulled data; if provided, system fetches data only after the most recent record.

The above command returns JSON structured like this:

{
    "sync_id": "672b2e74a8de3b2585aa9154"
}

Snowflake - Sync Data (Manually)

curl --location 'https://v3.polymersearch.com/api/snowflake/sync' \
--header 'x-api-key: {{apikey}}' \
--header 'Content-Type: application/json' \
--data '{
    "source_id": "671a1e74a8de3b2575aa9053",
    "file_id": "671b644ebdcabe4bdd1282b6",
    "full_sync": true
}'

HTTP Request

POST https://v3.polymersearch.com/api/snowflake/sync

Body content

Field Mandatory Data Type Description
source_id true String Source ID of the dataset to sync.
file_id true String File ID of the dataset to sync
full_sync false String This will override the update_settings provided with dataset and will fully refresh the data

The above command returns JSON structured like this:

{
    "sync_id": "672b2e74a8de3b2585aa9154"
}

Connect a new Google BigQuery connector

curl --location --request POST 'https://v3.polymersearch.com/api/auth/googlebigquery/connection' \
--header 'accept: application/json, text/plain, */*' \
--header 'x-api-key: {{apikey}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Prod Instance",
    "keyfilejson": {
        "type": "service_account",
        "project_id": "big-query-prod",
        "private_key_id": "XXe9cXX420ff6fb15XX8e8c182ebecb7XXd986XX",
        "private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvQIXXDANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDF5P97cajuuShb\nHYipN28BEmVb5/CTR2PspHcZjmMZagUz9CYY8eXlW27G+mPJP0NlP/SIeC4AnfV6XXXA0pnE6Sce9DquBDMGKA0ceisT8i6+DipZrLOwMS+TZhvKa73z7Lhm6QxzpeYfXV0\nXTDPZtyO6eK7UUSj1X+u6/1kSMPJfuGzJ4AP/KISeVyde+lCt/7CChfPzdlY5YfW\nuExA3xxqab8M9JPc+vK0S1aBpdJ+Q4ueczeVJRyb0bxR+zVREGSOLyjWcgvpT+xW\n1C4C52vvtRZ8YISvd29PFzuFxqNGVn9TwfQ98Cp6zo0gzFODtwzf7uaDk/bsNU7c\nQKqLtZ8LAgMBAAECggEAEJDAyiaTi5g4RphMTk3zntVZYr4hp1J8jNyfk6YVqZT0\nZorzfXcSVYa32TQwkjIXhCw8XgghYa/XUqVf3w0H5ImAzYUm8s7E6l72qSXsmaoZ\npCSSpzf/wCZisjt9CAV85eHPdtPiYMNvx5PdeB8WK2hssF13L3e5vnzGs1Rb/0vX\n8jDxZN4HOGm+kxQgQWpmb3ear4vtRot67QC0Ih3oZg71AWvjeTSZVXqGPF/a60HX\nwj7b7UceNNxop8JdRKm3AgmEH23en2kPUPCNlKD696cD5D3ffn8bs27ZL6Bv2k+T\nYe6rr9AdBn/gb5yUwzv8vjqxc+FEfMTtFmLcz5E5sQKBgQDy2L+pB2UvT9Gg7PKW\n/1XmpBZAbla5plvMxIVtiCKRSwPGlpPT5NxcoqdJ1h2s1igM2+AtPRMYXw5cxIaS\nCiSHmcFqTrvAKUqMYgN00tar9jSf5BgE4E/MVxcKbkCQ6fZnmVb417P36Xvuw2De\notB37sMOoKBVABDPE5HNGAbOPQKBgQDQnPQ5sMvlETFYuRcGaJc0frt2u2fHksVk\ncJIy3ZltigJuyQZ1oPKCj0R+lQkREo9EtKO89+Su18DIWkOXqAfInupUjuYT4ULA\XXRXUM8QrjmLiTMCO9eXXXv7KzQ0/3Ktg4gmsX14uUuHqFAOI/CV7KOPeYHc7v8X1a\nw70uiMX+5wKBgQDjOHrcJNdAFWcHM60oK3CshQts7dCnlEiAp8BQY/g0CgRWY72d\nnZ2x716nb3gEp7yBi5mNun+LZiWCFz/ylRro5axbU5XXXNoD0BF71WqXK57BnCH9\nLgR8JWChmdc/wCmVdZwy6WCyrfwPwXXX4IM796KEJprFd1tnjZ2QcikaT4QKBgE+Z\nxDsLMhH7CHhRT+7bE+8s+H0qr0Pgxj84ESElm3jHs3vwau2Rd1fIMRuX5LjF+zL9\nNolRkcoBe4c3ohkJPccYlFOlnzcwuhbBqhNBGqWTzcIkGU8g+xv6DccHRUkL6StO\n4Gxdi944sk9z8eCZw7ioGhnKLf8yh2GN1O8fs2U7AoGAfgPaYo1dHKz2R39SB6iz\nMv48I+oREuMC/3lU3YXLmDgyl1zx5ZhoJGeJ8deqLeomW+rhK02G7XXIApuA5pcrh\nl+R7N0jd/J1byQvcO+wXXXX6rvmF+UoDzdpzd9cCorj/WCVKysk60D8m1mukD4Gi\nbfgX2aIe5N5NIkvZUh7b1v0=\n-----END PRIVATE KEY-----\n",
        "client_email": "[email protected]",
        "client_id": "1XX14060XX125196033XX",
        "auth_uri": "https://accounts.google.com/o/oauth2/auth",
        "token_uri": "https://oauth2.googleapis.com/token",
        "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
        "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/tXXXcount-1%40big-quXXy-teXX-4456XX.iam.gserviceaccount.com",
        "universe_domain": "googleapis.com"
    }
}'

HTTP Request

POST https://v3.polymersearch.com/api/auth/googlebigquery/connection

Body content

Field Mandatory Data Type Description
name true String Desired name of the connector.
keyfilejson true String Key file JSON for service account.

Edit an Existing Google BigQuery connector

curl --location --request PATCH 'https://v3.polymersearch.com/api/auth/googlebigquery/:sourceid/connection' \
--header 'x-api-key: {{apikey}}' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Staging Instance",
    "keyfilejson": {
        "type": "service_account",
        "project_id": "big-query-prod",
        "private_key_id": "XXe9cXX420ff6fb15XX8e8c182ebecb7XXd986XX",
        "private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvQIXXDANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDF5P97cajuuShb\nHYipN28BEmVb5/CTR2PspHcZjmMZagUz9CYY8eXlW27G+mPJP0NlP/SIeC4AnfV6XXXA0pnE6Sce9DquBDMGKA0ceisT8i6+DipZrLOwMS+TZhvKa73z7Lhm6QxzpeYfXV0\nXTDPZtyO6eK7UUSj1X+u6/1kSMPJfuGzJ4AP/KISeVyde+lCt/7CChfPzdlY5YfW\nuExA3xxqab8M9JPc+vK0S1aBpdJ+Q4ueczeVJRyb0bxR+zVREGSOLyjWcgvpT+xW\n1C4C52vvtRZ8YISvd29PFzuFxqNGVn9TwfQ98Cp6zo0gzFODtwzf7uaDk/bsNU7c\nQKqLtZ8LAgMBAAECggEAEJDAyiaTi5g4RphMTk3zntVZYr4hp1J8jNyfk6YVqZT0\nZorzfXcSVYa32TQwkjIXhCw8XgghYa/XUqVf3w0H5ImAzYUm8s7E6l72qSXsmaoZ\npCSSpzf/wCZisjt9CAV85eHPdtPiYMNvx5PdeB8WK2hssF13L3e5vnzGs1Rb/0vX\n8jDxZN4HOGm+kxQgQWpmb3ear4vtRot67QC0Ih3oZg71AWvjeTSZVXqGPF/a60HX\nwj7b7UceNNxop8JdRKm3AgmEH23en2kPUPCNlKD696cD5D3ffn8bs27ZL6Bv2k+T\nYe6rr9AdBn/gb5yUwzv8vjqxc+FEfMTtFmLcz5E5sQKBgQDy2L+pB2UvT9Gg7PKW\n/1XmpBZAbla5plvMxIVtiCKRSwPGlpPT5NxcoqdJ1h2s1igM2+AtPRMYXw5cxIaS\nCiSHmcFqTrvAKUqMYgN00tar9jSf5BgE4E/MVxcKbkCQ6fZnmVb417P36Xvuw2De\notB37sMOoKBVABDPE5HNGAbOPQKBgQDQnPQ5sMvlETFYuRcGaJc0frt2u2fHksVk\ncJIy3ZltigJuyQZ1oPKCj0R+lQkREo9EtKO89+Su18DIWkOXqAfInupUjuYT4ULA\XXRXUM8QrjmLiTMCO9eXXXv7KzQ0/3Ktg4gmsX14uUuHqFAOI/CV7KOPeYHc7v8X1a\nw70uiMX+5wKBgQDjOHrcJNdAFWcHM60oK3CshQts7dCnlEiAp8BQY/g0CgRWY72d\nnZ2x716nb3gEp7yBi5mNun+LZiWCFz/ylRro5axbU5XXXNoD0BF71WqXK57BnCH9\nLgR8JWChmdc/wCmVdZwy6WCyrfwPwXXX4IM796KEJprFd1tnjZ2QcikaT4QKBgE+Z\nxDsLMhH7CHhRT+7bE+8s+H0qr0Pgxj84ESElm3jHs3vwau2Rd1fIMRuX5LjF+zL9\nNolRkcoBe4c3ohkJPccYlFOlnzcwuhbBqhNBGqWTzcIkGU8g+xv6DccHRUkL6StO\n4Gxdi944sk9z8eCZw7ioGhnKLf8yh2GN1O8fs2U7AoGAfgPaYo1dHKz2R39SB6iz\nMv48I+oREuMC/3lU3YXLmDgyl1zx5ZhoJGeJ8deqLeomW+rhK02G7XXIApuA5pcrh\nl+R7N0jd/J1byQvcO+wXXXX6rvmF+UoDzdpzd9cCorj/WCVKysk60D8m1mukD4Gi\nbfgX2aIe5N5NIkvZUh7b1v0=\n-----END PRIVATE KEY-----\n",
        "client_email": "[email protected]",
        "client_id": "1XX14060XX125196033XX",
        "auth_uri": "https://accounts.google.com/o/oauth2/auth",
        "token_uri": "https://oauth2.googleapis.com/token",
        "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
        "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/tXXXcount-1%40big-quXXy-teXX-4456XX.iam.gserviceaccount.com",
        "universe_domain": "googleapis.com"
    }
}'

HTTP Request

PATCH https://v3.polymersearch.com/api/auth/googlebigquery/:sourceid/connection

Body content

Field Mandatory Data Type Description
name false String Desired name of the connector.
keyfilejson false String Key file JSON for service account.

Import data using newly connected Google BigQuery

curl --location 'https://v3.polymersearch.com/api/googlebigquery/67861f640bd21e00099d0cc8' \
--header 'x-api-key: {{apikey}}' \
--header 'Content-Type: application/json' \
--data '{
    "name": "D-13-jan-2025-1",
    "query": "SELECT * FROM big-query-test-445609.dataset_test_1.table_test_1",
    "fetch_size": 100,
    "update_settings": {
        "type": "replace"
    }
}'

HTTP Request

POST https://v3.polymersearch.com/api/googlebigquery/:sourceid

Body content

Field Mandatory Data Type Description
name true String Desired name of the imported dataset.
query true String Query to execute for data retrieval.
fetch_size true String Maximum number of rows to fetch per pull.
update_settings true String Settings for data updates.
update_settings.type true String Type of update: replace.

The above command returns JSON structured like this:

{
    "sync_id": "672b2e74a8de3b2585aa9154"
}

Google BigQuery - Sync Data (Manually)

curl --location 'https://v3.polymersearch.com/api/googlebigquery/sync' \
--header 'x-api-key: {{apikey}}' \
--header 'Content-Type: application/json' \
--data '{
    "source_id": "671a1e74a8de3b2575aa9053",
    "file_id": "671b644ebdcabe4bdd1282b6",
    "full_sync": true
}'

HTTP Request

POST https://v3.polymersearch.com/api/googlebigquery/sync

Body content

Field Mandatory Data Type Description
source_id true String Source ID of the dataset to sync.
file_id true String File ID of the dataset to sync
full_sync false String This will override the update_settings provided with dataset and will fully refresh the data

The above command returns JSON structured like this:

{
    "sync_id": "672b2e74a8de3b2585aa9154"
}

Dataset

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

Upload a Dataset

This endpoint initiates the processing of the provided CSV file.

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 publicly downloadable CSV.
file false Type: file. The file to upload.
name true Name of the dataset/file.
description false Description 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"
}'

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 '{
    "url": "https://test-csv-datasets.s3.us-east-2.amazonaws.com/Test+-+Bank+Loans.csv",
    "incremental_update": true,
    "primary_key": "column1"
}'

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 '{
    "ingestion_type": "json",
    "delete": true,
    "primary_key": "column1",
    "records": [
        {
            "column1": "ID100"
        }
    ]
}'

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 publicly downloadable CSV.
file false Type: file. The file to upload.
name false Name of the dataset/file.
description false Description of the dataset/file.
incremental_update false Indicates if the data being passed is for incremental updates only.
delete false Indicates if the data being passed contains row IDs to delete.
primary_key false if incremental_update = true or delete = true

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",
        "description": "For Report 1",
        "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 Maximum number of records per page.
page false Page number to retrieve.
sort_key false name, created_at, num_rows
sort_order false Allowed values: desc, asc.

Create a merged dataset

This endpoint creates a merged dataset with given definition

curl --location 'https://v3.polymersearch.com/api/v1/datasets/merged' \
--header 'x-api-key: XXeca66c-21f3-XX39-b407-64e00c62XXXX' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Merged dataset name here",
    "original_file_id": "66bcaafdde015d4d43494a45",
    "relations": [
        {
            "left_file_column": "r__opportunitystage",
            "file_id": "66bcaafdde015d4d43494a41",
            "right_file_column": "cp__oppstageid",
            "columns": [
                "cp__oppstageid"
            ],
            "prefix": "opportunitystage"
        },
        {
            "left_file_column": "r__company",
            "file_id": "66bcaafdde015d4d43494a68",
            "right_file_column": "cp__companyid",
            "columns": [
                "a__companyname",
                "a__companyowner",
                "a__companystate"
            ]
        },
        {
            "left_file_column": "cp__oppid",
            "file_id": "66bcaafdde015d4d43494a49",
            "right_file_column": "r__opportunity",
            "columns": '*'
        },
        {
            "left_file_id": "66bcaafdde015d4d43494a49",
            "left_file_column": "r__person",
            "file_id": "66bcaafdde015d4d43494a44",
            "right_file_column": "cp__personid",
            "columns": [
                "a__personcountry",
                "a__personname"
            ]
        }
    ],
    "columns": [
        "l__opppipelineid__opppipelinename",
        "a__oppsource",
        "d__oppcreatedat",
        "f__oppusdvalue",
        "f__oppvalue",
        "r__lead"
    ],
    "cadence_in_minutes": 5
}'

The above command returns JSON structured like this:

{
    "task_id": "66eac9e101888863e554ae86"
}

HTTP Request

POST https://v3.polymersearch.com/api/v1/datasets/merged

Body content

Field Mandatory Description
name true Must be a string with a minimum length of 3 characters and a maximum of 80 characters. Represents the name of the dataset.
description false A string providing a description of the dataset.
original_file_id true Dataset ID of the main file
relations true An array of relation objects. Each object must contain left_file_column, file_id, right_file_column, and either a string or an array of columns.
relations.left_file_id false The ID of the left file in the relation
relations.left_file_column true The column from the left file that will be used in the relation.
relations.file_id true The ID of the left file in the relation
relations.right_file_column true The column from the right file that will be used in the relation.
relations.columns true Either a string ('*') to represent all columns, or an array of strings representing the specific columns to be used. Columns must be unique.
relations.prefix true A string that only contains alphabetic characters. It acts as a prefix for related columns.
columns true Either a string * representing all columns, or an array of unique strings specifying the columns to be included in the result.
cadence_in_minutes true An integer value representing the cadence in minutes, which must be at least 1.

Update column settings

This endpoint updates the column settings of a specified dataset

curl --location --request PUT 'https://v3.polymersearch.com/api/v1/datasets/6703d9aa853d23000845bfed/column_settings' \
--header 'x-api-key: XXeca66c-21f3-XX39-b407-64e00c62XXXX' \
--header 'Content-Type: application/json' \
--data '{
    "STAGE_NAME": {
        "caption": "Pipeline Stage Name",
        "type": "string",
        "original_type": "string",
        "tag_details": {
            "num_decimal_places": null,
            "date_bucket_size": "",
            "buckets_manual": null,
            "bucket_size": 0
        },
        "pipeline_settings": {
            "PIPELINES_NAME": {
                "values": {
                    "Projects": {
                        "stages": [
                            "Requirements Gathering",
                            "Kickoff Scheduled",
                            "Post-Kickoff",
                            "In Production",
                            "Stakeholder Feedback",
                            "Stakeholder Signoff"
                        ],
                        "default_value": 0
                    },
                    "Sales": {
                        "stages": [
                            "New Lead",
                            "Demo",
                            "Post-demo Follow Up",
                            "Contract Negotiation",
                            "Closing"
                        ],
                        "default_value": 0
                    }
                }
            }
        }
    }
}'

HTTP Request

PUT https://v3.polymersearch.com/api/v1/datasets/:id/column_settings

Note: STAGE_NAME and PIPELINES_NAME refer to the names of the columns. Projects and Sales represent pipeline values. Requirements Gathering, Kickoff Scheduled, Post-Kickoff, New Lead, Closing, and others are examples of stage names.

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 Indicates the current status of the task. If set to 'done', the task is completed and you can find the file_id. If set to 'inprogress', please poll again in 5 seconds.
- error String Provides details if any processing error is encountered.

Board

The Boards API enables the creation of boards and blocks, each containing charts and visualizations that can be shared independently. You can embed specific visualizations into your site. Boards can be composed of multiple blocks, with each block representing a distinct visualization. Blocks can be created manually, or you can utilize the auto-generated blocks feature to assemble a board with a single click.

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
description false Type: String
Description of the board
file_ids true Type: List[String]
Dataset IDs to be associated with the board.
blocks true Type: List [Blocks Object]
sharing false Desired sharing status for the board (public, private). Default: private
advanced_sharing false Controls sharing settings for the board.
advanced_sharing.allow_global_filters_for_viewers false Type: Boolean
Allows viewers to apply global filters.
advanced_sharing.allow_block_based_filters_for_viewers false Type: Boolean
Allows viewers to apply block-based filters.
branding.logoUrl false URL of the logo.
branding.logoLink false URL to redirect when the logo is clicked.
colors false Type: List
List of color codes to be used in view preview mode.
auto_generated false Type: Boolean
Auto generate the board (populate with blocks based on our AI engine)
slug false Used for constructing a custom board URL. Length must be between 3 and 32 characters.
background_color false Valid CSS color name (eg. white, blue), or valid hexadecimal color code (eg. #ff5733)
notifications false Type: notifications Object
Settings for board digest email
filter_settings false Type: filter_settings Object
Columns to be shown on global filters per dataset

notifications Object

Example 1

{
    "schedule":
    {
        "cadence": "daily",
        "hours": 9,
        "day": 1
    },
    "recipients": ["[email protected]"],
    "disabled": false
}

Notes

filter_settings Object

Example 1

{
    "65b50541d83d1e4d42c7fbe0":
    {
        "columns":
        {
            "spend":
            {},
            "campaign_status":
            {
                "allowed_values": [
                    "active",
                    "pending"
                ]
            }
        }
    }
}

Exemple 2

{
    "65b50541d83d1e4d42c7fbe0":
    {
        "allow_all_columns": true,
        "columns":
        {
            "campaign_status":
            {
                "allowed_values": [
                    "active",
                    "pending"
                ]
            }
        }
    }
}

Notes

Filters Object

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": "BEGINS_WITH" }] } }

The following filter will be read as

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

Possible dynamic date ranges:

Possible operations:

Blocks Object

Header Block

{
    "type": "header",
    "heading": "Ads Dashboard",
    "subheading": "Facebook ads for last 30 days vs Google ads for last 30 days",
    "alignment": "left",
    "size": "large",
    "background": "gradient-f"
}
Field Datatype Mandatory Desc
type String Yes header
heading String Yes Mainheading on the block
subheading String Yes Subheading on the block
alignment String No Any value from left, center, right
size String No Any value from small, medium, large
background String No Any value from transparent, white, grey, black, gradient-a, gradient-b, gradient-c, gradient-d, gradient-e, gradient-f

Bar Chart

{
    "type": "bar",
    "x_axis_multiple": [
    {
        "name": "spend",
        "operation": "SUM"
    },
    {
        "name": "Clicks (all)",
        "operation": "COUNT"
    }],
    "y_axis": "campaign_status",
    "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 Dataset 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, COUNT_UNIQUE, SUM, AVERAGE, STDDEV, VARIANCE, MAX, MIN
y_axis String Yes Valid column name
operation String No Any value from COUNT, COUNT_UNIQUE, 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_in_columns Integer No Any value from 1 to 6. Default: 3
height Integer No Any value from 2 to 3. Default: 2
filters Object No Filter Object
title String No Custom heading
show_explanation Boolean No Show explanation under title

Column Chart

{
    "type": "column",
    "x_axis": "campaign_status",
    "y_axis_multiple": [
    {
        "name": "spend",
        "operation": "SUM"
    },
    {
        "name": "Clicks (all)",
        "operation": "COUNT"
    }],
    "show_annotations": true,
    "show_stacked": false,
    "file_id": "65b50541d83d1e4d42c7fbe0"
}
Field Datatype Mandatory Desc
type String Yes column
file_id String Yes Dataset 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, COUNT_UNIQUE, SUM, AVERAGE, STDDEV, VARIANCE, MAX, MIN
operation String No Any value from COUNT, COUNT_UNIQUE, 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_in_columns Integer No Any value from 1 to 6. Default: 3
height Integer No Any value from 2 to 3. Default: 2
filters Object No Filter Object
title String No Custom heading
show_explanation Boolean No Show explanation under title

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 Dataset 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, COUNT_UNIQUE, 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_in_columns Integer No Any value from 1 to 6. Default: 3
height Integer No Any value from 2 to 3. Default: 2
filters Object No Filter Object
title String No Custom heading
show_explanation Boolean No Show explanation under title

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 Dataset 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, COUNT_UNIQUE, 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_in_columns Integer No Any value from 1 to 6. Default: 3
height Integer No Any value from 2 to 3. Default: 2
filters Object No Filter Object
title String No Custom heading
show_explanation Boolean No Show explanation under title

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 Dataset 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, COUNT_UNIQUE, SUM, AVERAGE, STDDEV, VARIANCE, MAX, MIN
metric 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_in_columns Integer No Any value from 1 to 6. Default: 3
height Integer No Any value from 2 to 3. Default: 2
filters Object No Filter Object
title String No Custom heading
show_explanation Boolean No Show explanation under title

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 Dataset 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, COUNT_UNIQUE, SUM, AVERAGE, STDDEV, VARIANCE, MAX, MIN
x_axis String Yes Valid column name
operation String Yes Any value from COUNT, COUNT_UNIQUE, 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_in_columns Integer No Any value from 1 to 6. Default: 3
height Integer No Any value from 2 to 3. Default: 2
filters Object No Filter Object
title String No Custom heading
show_explanation Boolean No Show explanation under title

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 Dataset 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, COUNT_UNIQUE, 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_in_columns Integer No Any value from 1 to 6. Default: 3
height Integer No Any value from 1 to 3. Default: 2
filters Object No Filter Object
title String No Custom heading
show_explanation Boolean No Show explanation under title

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 Dataset ID to drive this block
metric String Yes Valid number column name
operation String Yes Any value from COUNT, COUNT_UNIQUE, 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_in_columns Integer No Any value from 1 to 6. Default: 3
height Integer No Any value from 1 to 3. Default: 2
filters Object No Filter Object
title String No Custom heading
lower_better Boolean No Indicates if a lower value is better.
show_explanation Boolean No Show explanation under title

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 Dataset 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, COUNT_UNIQUE, 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, COUNT_UNIQUE, 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_in_columns Integer No Any value from 1 to 6. Default: 3
height Integer No Any value from 1 to 3. Default: 2
filters Object No Filter Object
title String No Custom heading
lower_better Boolean No Indicates if a lower value is better.
show_explanation Boolean No Show explanation under title

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 Dataset ID to drive this block
metrics List Yes Object, Min length: 1, Max length: 10.
metric: Valid column
operation: Any value from COUNT, COUNT_UNIQUE, 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_in_columns Integer No Any value from 1 to 6. Default: 3
height Integer No Any value from 1 to 3. Default: 2
filters Object No Filter Object
title String No Custom heading
pin_totals Boolean No Pin Totals
show_explanation Boolean No Show explanation under title

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 Dataset ID to drive this block
metric List Yes Valid date column name
operation String Yes Any value from COUNT, COUNT_UNIQUE, 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', 'week from monday', 'this quarter', 'this year', 'week to date', 'month to date', 'quarter to date', 'year to date', 'previous week', 'previous month', 'previous quarter', 'previous year', custom
comp_date_range String No Any value from 'previous period', 'previous week', 'previous month', 'previous querter', 'previous year', 'custom'
goal Number No
exclude_empty_string Boolean No Exclude [EMPTY] strings
width_in_columns Integer No Any value from 1 to 6. Default: 1
height Integer No Any value from 1 to 3. Default: 1
filters Object No Filter Object
show_explanation Boolean No Show explanation under title

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 Dataset 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, COUNT_UNIQUE, 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_in_columns Integer No Any value from 1 to 6. Default: 3
height Integer No Any value from 1 to 3. Default: 2
filters Object No Filter Object
title String No Custom heading
show_explanation Boolean No Show explanation under title
hide_title Boolean No Hide title 
{
    "type": "gallery",
    "is_aggregate": true,
    "aggregate":
    {
        "metrics": [
        {
            "name": "Checkouts initiated",
            "operation": "VARIANCE"
        }],
        "base_column": "Ad name"
    },
    "image_column": "Media url",
    "layout": "expanded",
    "appearance": "fit",
    "enable_card_modal": true,
    "sections": [
    {
        "columns": [
            "Impressions"
        ],
        "title": "Section 1"
    }],
    "file_id": "66e3f70cb399ce00086ba8b9"
}

{
    "type": "gallery",
    "is_aggregate": false,
    "card_columns": [
        "Reach",
        "Thruplays"
    ],
    "image_column": "Media url",
    "layout": "expanded",
    "appearance": "fit",
    "enable_card_modal": true,
    "link_label": "Click here to visit",
    "file_id": "66e3f70cb399ce00086ba8b9"
}
Field Datatype Mandatory Desc
type String Yes gallery
file_id String Yes Dataset ID to drive this block
is_aggregate Boolean Yes true for Summarized, false for Raw
aggregate.metrics List No Object, Min length: 1, Max length: 10.
name: Valid column
operation: Any value from COUNT, COUNT_UNIQUE, SUM, AVERAGE, STDDEV, VARIANCE, MAX, MIN, MEDIAN, MODE
aggregate.base_column Boolean Yes for Summarized Valid column
card_columns List No Valid column
image_column String Yes Valid image/video column
layout String No Any value from expanded, normal, condensed
appearance String No Any value from fit, fill
headline_column String No Valid column
description_column String No Valid column
link_column String No Valid column
link_label String No Link label
enable_card_modal Boolean No Enable modal on click
sections Yes No Object, Min length: 1, Max length: 10.
columns: Valid column name
title: Section title
title String No Custom heading
width_in_columns Integer No Any value from 1 to 6. Default: 3
height Integer No Any value from 1 to 3. Default: 2
filters Object No Filter Object
enable_search_sort Boolean No Enable searching and sorting
hide_title Boolean No Hide title

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_in_columns Integer No Any value from 1 to 6. Default: 3
height Integer No Any value from 1 to 3. Default: 1
hide_title Boolean No Hide title

IMAGE BLOCK

{
    "type": "image",
    "appearance": "fit",
    "url": "https://cdn-v3-dev.polymerdev.com/assets/logo-4743e3c9.svg"
}
Field Datatype Mandatory Desc
type String Yes image
appearance String Yes Any value from fit,fill
url String Yes Any valid public image URL
width_in_columns Integer No Any value from 1 to 6. Default: 3
height Integer No Any value from 1 to 3. Default: 2
title String No Custom heading

MAP BLOCK

{
    "type": "map",
    "base_column": "country",
    "metrics": [
        {
            "name": "annual_revenue",
            "operation": "AVERAGE"
        }
    ],
    "file_id": "66b9d4ece653ad0008f8ce90"
}
Field Datatype Mandatory Desc
type String Yes map
file_id String Yes Dataset ID to drive this block
base_column String Yes Valid column name that can be used for plotting on map
metrics List Yes Object, Min length: 1, Max length: 10.
name: Valid column
operation: Any value from COUNT, COUNT_UNIQUE, SUM, AVERAGE, STDDEV, VARIANCE, MAX, MIN
width_in_columns Integer No Any value from 1 to 6. Default: 3
height Integer No Any value from 2 to 3. Default: 2
title String No Custom heading
hide_title Boolean No Hide title

LOOM BLOCK

{
    "type": "loom",
    "title": "Product Tour",
    "url": "https://www.loom.com/share/XX31ba9b6fdf4ebXX3cafbc63ef10654?sid=XX1ea111-f614-XXXX-a3XX-fce1b8b0XXXX"
}
Field Datatype Mandatory Desc
type String Yes loom
width_in_columns Integer No Any value from 1 to 6. Default: 3
height Integer No Any value from 1 to 3. Default: 2
url String Yes loom URL. Note: URL should start with https://www.loom.com
title String No Custom heading
hide_title Boolean No Hide title

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
description false Type: String
Description 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
Allows viewers to apply global filters.
advanced_sharing.allow_block_based_filters_for_viewers false Type: Boolean
Allows viewers to apply block-based filters.
branding.logoUrl false URL of the logo.
branding.logoLink false URL to redirect when the logo is clicked.
colors false Type: List
List of color codes to be used in view preview mode.
slug false Used for constructing a custom board URL. Length must be between 3 and 32 characters.
background_color false Valid CSS color name (eg. white, blue), or valid hexadecimal color code (eg. #ff5733 )
notifications false Type: notifications Object
Settings for board digest email
filter_settings false Type: filter_settings Object
Columns to be shown on global filters per dataset

Blocks Object

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

notifications Object

Same as described on Create Board request Note: Make sure you pass all the blocks inside notifications 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",
            "description": "For Daily reporting on Ads",
            "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

A Polymer-generated app can be embedded to create new boards and to browse or edit existing ones.

Generate an auth token

This endpoint generates a token to provide authenticated access to embedded 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: Grants permission to read data from the specified board ID.

board_edit: Grants permission to read and edit data from the specified board ID.

workspace_read_only: Authorizes read-only access to 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: Grants permission to read, add, and edit all board data within the workspace.
board_id false Grants permission to read data from the specified block on the board.

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}

Changelog

Sep 23, 2024 - V3 APIs

Sep 15, 2024 - V3 APIs

August 21, 2024 - V3 APIs

July 7, 2024 - V3 APIs

June 5, 2024 - V3 Board API

May 5, 2024 - V3 Dataset API

May 4, 2024 - V3 Workspace APIs

March 5, 2024 - V3 Board APIs Improvement

January 5, 2024 - V3 Workspace APIs

October 5, 2023 - V3 Workspace APIs

August 28, 2023 - V3 Workspace APIs

July 15, 2023 - V3 Workspace APIs

January 6, 2023 - V3 Initial Release

February 5, 2022 - Feature Addition

September 28, 2021 - Feature Addition

September 13, 2021 - Feature Addition

July 21, 2021 - Initial Release