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:
- X-RateLimit-Limit: The maximum number of requests allowed per hour.
- X-RateLimit-Remaining: The number of requests remaining in the current time window.
- X-RateLimit-Reset: The time remaining before the rate limit resets, in UTC epoch seconds.
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
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. |
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"
}
]
}
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. |
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 |
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"
}
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"
}
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
schedule.cadence
: Defines the frequency of the schedule, which can bedaily
,weekly
, ormonthly
.schedule.hours
: Specifies the hour of the day for the schedule, ranging from0
to23
.schedule.day
: Defines the day of the week, with values from0
(Sunday) to6
(Saturday).schedule.monthly_schedule
: Required only for amonthly
cadence. Acceptslast_day_of_month
orfirst_day_of_month
.recipients
: A list of email addresses to which notifications will be sent.disabled
: A flag that, when set, disables the email notifications.
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
65b50541d83d1e4d42c7fbe0
is thefile_id
.65b50541d83d1e4d42c7fbe0.columns
refers to the list of columns that can be included in global filters.65b50541d83d1e4d42c7fbe0.columns.spend
indicates that all values from the spend column are permitted in the global filters.65b50541d83d1e4d42c7fbe0.columns.campaign_status.allowed_values
specifies that only theactive
andpending
values from thecampaign_status
column are allowed in global filters.65b50541d83d1e4d42c7fbe0.allow_all_columns
means all columns from the dataset will be available in global filters, except for thecampaign_status
column, which will only displayactive
andpending
values.
Filters Object
Allowed values: object
The following filters can be applied
- Date Columns: Filter using dynamic date ranges, such as "last 30 days," "last year," etc.
- Numerical Columns: Filter using ranges, such as "amount between 25 to 45."
- Categorical Columns (Text Search):
- Include specific values, e.g., "payment mechanism including cash and demand draft."
- Exclude specific values, e.g., "payment mechanism excluding cash."
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:
- last day
- last 7 days
- last 14 days
- last 30 days
- last 90 days
- last 6 months
- last 12 months
- last week
- this week
- this month
- 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
Possible operations:
- INCLUDING
- EXCLUDING
- CONTAINS
- BEGINS_WITH
- ENDS_WITH
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 |
Gallery Block
{
"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
- Add support for
CONTAINS
,BEGINS_WITH
,ENDS_WITH
in global filters
Sep 15, 2024 - V3 APIs
- Added support for header block, loom block and gallery block
- Added support for merged datasets
August 21, 2024 - V3 APIs
- Added support for background color on boards.
- Introduced control for board digest emails at the workspace level.
- Added control for PolyAI in read-only permissions at the workspace level.
July 7, 2024 - V3 APIs
- Added support for disabling the share button at the workspace level.
- Introduced support for Image and Map blocks.
- Enhanced board-level advanced sharing options.
- Added timezone support at both the workspace and board levels.
June 5, 2024 - V3 Board API
- Introduced support for slugs in board and workspace-level APIs.
May 5, 2024 - V3 Dataset API
- Added support for incremental updates.
- Introduced a skip email flag for workspace invites.
May 4, 2024 - V3 Workspace APIs
- Added support for custom DNS.
March 5, 2024 - V3 Board APIs Improvement
- Added support for embed permissions:
board_read_only
,board_edit
,workspace_read_only
,workspace_edit
,block_level_read_only
.
January 5, 2024 - V3 Workspace APIs
- Added support for board CRUD APIs with basic chart types: Bar, Column, Pivot, Pie, Timeseries.
October 5, 2023 - V3 Workspace APIs
- Added support for V3 board embedding via token.
August 28, 2023 - V3 Workspace APIs
- Added support for workspace members CRUD.
July 15, 2023 - V3 Workspace APIs
- Added support for workspace CRUD.
January 6, 2023 - V3 Initial Release
- Released V3 APIs for dataset and board creation.
February 5, 2022 - Feature Addition
- Added support for JSON and Excel formats in the
/v1/dataset
API.
September 28, 2021 - Feature Addition
- Added support for the force flag in the
/v1/dataset
API. - Introduced the Update Dataset API -
PUT /v1/dataset/:id
.
September 13, 2021 - Feature Addition
- Added support for starting row.
July 21, 2021 - Initial Release
- Launched the first version of the Polymer public API, including two endpoints to create a Polymer website from a CSV file.