Quick Start

Step 1. Get your project API key

If you’re a user in your team, just ask your admin to give you a project API key.

Sign in to Powerdrill with the email that you’ve used to join our waitlist.
Visit https://powerdrill.ai/teamspace.
On the displayed page, enter your organization name, review and accept our Terms of Service and Privacy Notice, then click Continue.
Connect to your credit card as prompted. You will then be directed to the Teamspace page.
Your credit card won’t be charged unless you purchase a subscription.
Navigate to the API tab, click + API access key to generate an API key, and make sure to save it securely, as it will only be displayed once on the Powerdrill platform.

Keep your API key SECRET. Never share it or include it in client-side code, such as browsers or apps. For production use, ensure all requests are routed through your backend server, where the API key can be securely accessed from an environment variable or a key management service.

Step 2. Create a dataset and a data source

This step is optional but highly recommended, as it allows you to receive insights tailored to your own data.

Data sources are the data you upload to Powerdrill for embedding, indexing, knowledge extraction, and vectorized storage and retrieval, while datasets are collections of data sources that help organize and categorize them. You can create data sources and datasets in two ways:

Method 1: Create a dataset first, then add data sources to it.
Method 2: Upload data sources directly without specifying a dataset, and Powerdrill will automatically create a default dataset for them.

Method 1
Method 2

Make a request to POST /v1/team/datasets endpoint to create a dataset. Example request:

curl --location 'https://ai.data.cloud/api/v1/team/datasets' \
  --header 'x-pd-api-key: $PD_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "description": "My dataset",
    "name": "My dataset"
}'

Replace $PD_API_KEY with the API key you’ve obtained in Step 1.

Example response:

{
    "code": 0,
    "data": {
        "id": "cm3my37en3q36017q7x3hyyf4"
    }
}

Obtain the id value (dataset ID) from the response and save it for later use.

Make a request to the POST /v1/team/datasets/{datasetId}/datasources endpoint. Example request:

curl --location 'https://ai.data.cloud/api/v1/team/datasets/cm3my37en3q36017q7x3hyyf4/datasources' \
  --header 'x-pd-api-key: $PD_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "test.pdf",
  "fileName": "test.pdf",
  "type": "FILE",
  "url": "https://arxiv.org/pdf/2406.12660v1.pdf"
}'

When making a request:

Replace the datasetId value with the ID of the dataset you’ve created in the previous sub-step.
Specify either url or fileKey, but not both. Use url to upload a file through a publicly accessible URL. For privately accessible files, use fileKey (this feature will be supported soon).

Example response:

{
    "code": 0,
    "data": {
        "id": "cm3myfsfc03jn011csb8wah6p",
        "datasetId": "cm3my37en3q36017q7x3hyyf4",
        "name": "test.pdf",
        "fileName": "test.pdf",
        "type": "FILE",
        "status": "pending"
    }
}

Repeat this sub-step to create multiple data sources in the same dataset.

Make a request to the POST /v1/team/datasources endpoint.Example request:

curl --location 'https://ai.data.cloud/api/v1/team/datasets/cm3my37en3q36017q7x3hyyf4/datasources' \
  --header 'x-pd-api-key: $PD_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "test.pdf",
  "fileName": "test.pdf",
  "type": "FILE",
  "url": "https://arxiv.org/pdf/2406.12660v1.pdf"
}'

Specify either url or fileKey, but not both. Use url to upload a file through a publicly accessible URL. For privately accessible files, use fileKey (this feature will be supported soon).

Example response:

{
   "code": 0,
   "data": {
       "id": "cm3myfsfc03jn011csb8wah6p",
       "datasetId": "cm3my37en3q36017q7x3hyyf4",
       "name": "test.pdf",
       "fileName": "test.pdf",
       "type": "FILE",
       "status": "pending"
   }
}

Obtain the datasetId value (dataset ID) from the response and save it for later use.

When the data source created,

Step 3. Create a session

To create a session, make a request to the POST /v1/team/sessions endpoint. Sessions are essential for running jobs on Powerdrill, as each job must be linked to a session using its session ID. Example request:

curl --location 'https://ai.data.cloud/api/v1/team/sessions' \
  --header 'x-pd-api-key: $PD_API_KEY' \
  --header 'x-pd-api-agent-id: GENERAL' \
  --header 'Content-Type: application/json' \
  --data '{
  "title": "New Title",
  "languageType": "EN",
  "jobMode": "AUTO",
  "maxMessagesInContext": 10
}'

When making a request:

Replace $PD_API_KEY with the API key you’ve obtained in Step 1.
Since this topic covers running a general job and no data agent is used, set the x-pd-api-agent-id header to GENERAL (uppercase).

Example response:

{
    "code": 0,
    "data": {
        "id": "4440ab38-3df0-465b-a66c-bf6acb0f1bc2"
    }
}

Obtain the id value (session ID) from the response and save it for use in the following step.

Step 4. Create a job

Now, after you’ve prepared a session and probably a dataset stuffed with data sources, you can create a job to start conversing with Powerdrill.

For the definition of job, see What Is Job?.

Make a request to the POST /v1/team/jobs endpoint. Powerdrill provides the ability to stream responses, controlled by the stream parameter. For more details about how to understand the streaming mode, see Streaming.

If stream is set to true, streaming is enabled.
If stream is set to false, streaming is disabled.

Set stream to true:
Set stream to false:

Example request:

curl --location 'https://ai.data.cloud/api/v1/team/jobs' \
  --header 'x-pd-api-key: $PD_API_KEY' \
  --header 'x-pd-api-agent-id: GENERAL' \
  --header 'Content-Type: application/json' \
  --data '{
  "datasetId": "cm3my37en3q36017q7x3hyyf4",
  "datasourceIdList": [
    "cm3myfsfc03jn011csb8wah6p"
  ],
  "languageType": "EN",
  "question": "How do '\''Digital Services for Taxpayers'\'' scores vary across economies, and which economy has the most advanced digital services?",
  "sessionId": "4440ab38-3df0-465b-a66c-bf6acb0f1bc2",
  "stream": true
}'

Example response:

event:JOB_ID
data:job-cm3ik4yhz01vg01l17yk4467y

event:TITLE_GENERATION
data:test session

id:2b5cba4a-d8a5-4beb-aef9-a8612828c405
event:TASK
data:{"id":"2b5cba4a-d8a5-4beb-aef9-a8612828c405","model":"","choices":[{"delta":{"content":{"name":"Analyze","id":"2b5cba4a-d8a5-4beb-aef9-a8612828c405","status":"running","stage":"Analyze","properties":{}}},"index":0}],"created":1731664172,"groupId":"2b5cba4a-d8a5-4beb-aef9-a8612828c405","groupName":"Analyze","stage":"Analyze"}

id:2b5cba4a-d8a5-4beb-aef9-a8612828c405
event:TASK
data:{"id":"2b5cba4a-d8a5-4beb-aef9-a8612828c405","model":"","choices":[{"delta":{"content":{"name":"Analyze","id":"2b5cba4a-d8a5-4beb-aef9-a8612828c405","status":"running","stage":"Analyze","properties":{"files":""}}},"index":0}],"created":1731664172,"groupId":"2b5cba4a-d8a5-4beb-aef9-a8612828c405","groupName":"Analyze","stage":"Analyze"}

...
...
...


id:ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3
event:IMAGE
data:{"id":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","model":"","choices":[{"delta":{"content":{"url":"https://static.powerdrill.ai/tmp_datasource_cache/code_result/cm37bchx106e301l1v9yf67yc/5e3a766c-8d16-4fc0-b06f-7a337196186d.png","name":"Trends of Deaths from Different Disaster Types Over the Years","expiredAt":"2024-11-21T09:50:00.026476Z"}},"index":0}],"created":1731664200,"groupId":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","groupName":"Conclusions","stage":"Respond"}

id:ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3
event:MESSAGE
data:{"id":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","model":"","choices":[{"delta":{"content":"\n\n"},"index":0}],"created":1731664200,"groupId":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","groupName":"Conclusions","stage":"Respond"}

id:ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3
event:MESSAGE
data:{"id":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","model":"","choices":[{"delta":{"content":"- **Chart Description**: The chart illustrates the trend of death tolls over time for various types of disasters.\n"},"index":0}],"created":1731664200,"groupId":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","groupName":"Conclusions","stage":"Respond"}

id:ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3
event:MESSAGE
data:{"id":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","model":"","choices":[{"delta":{"content":"- **Key Trends**:\n"},"index":0}],"created":1731664200,"groupId":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","groupName":"Conclusions","stage":"Respond"}

id:ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3
event:MESSAGE
data:{"id":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","model":"","choices":[{"delta":{"content":"  - Droughts and floods had high death tolls in the early 20th century.\n"},"index":0}],"created":1731664200,"groupId":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","groupName":"Conclusions","stage":"Respond"}

id:ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3
event:MESSAGE
data:{"id":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","model":"","choices":[{"delta":{"content":"  - Droughts and floods had higher death tolls in the early 20th century. \n"},"index":0}],"created":1731664200,"groupId":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","groupName":"Conclusions","stage":"Respond"}

id:ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3
event:MESSAGE
data:{"id":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","model":"","choices":[{"delta":{"content":"  - Death tolls from other disaster types remained relatively low and stable. \n\n"},"index":0}],"created":1731664201,"groupId":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","groupName":"Conclusions","stage":"Respond"}

id:ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3
event:MESSAGE
data:{"id":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","model":"","choices":[{"delta":{"content":"#### Conclusions and Insights\n"},"index":0}],"created":1731664201,"groupId":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","groupName":"Conclusions","stage":"Respond"}

id:ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3
event:MESSAGE
data:{"id":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","model":"","choices":[{"delta":{"content":"- **Significant Impact of Droughts and Floods**: In the early 20th century, droughts and floods caused significantly higher death tolls compared to other disasters.\n"},"index":0}],"created":1731664201,"groupId":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","groupName":"Conclusions","stage":"Respond"}

id:ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3
event:MESSAGE
data:{"id":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","model":"","choices":[{"delta":{"content":"- **Fluctuations in Earthquakes and Extreme Weather**: These disasters had significant impacts on death tolls in certain years, highlighting the need for enhanced preventive measures."},"index":0}],"created":1731664202,"groupId":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","groupName":"Conclusions","stage":"Respond"}

id:ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3
event:QUESTIONS
data:{"id":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","model":"","choices":[{"delta":{"content":["Please analyze the distribution of deaths caused by different types of natural disasters across various countries and regions, and generate a corresponding ECharts map chart.","Please compare the changes in death tolls caused by natural disasters across different decades, and generate a corresponding ECharts line chart.","Please analyze the global death toll trend of a specific natural disaster (e.g., earthquakes) and generate a corresponding ECharts bar chart."]},"index":0}],"created":1731664202,"groupId":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","groupName":"Conclusions","stage":"Respond"}

id:ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3
event:TRIGGER
data:{"id":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","model":"","choices":[{"delta":{"content":{"name":"conclusion_slice","arguments":{"answer":"$answer"}}},"index":0}],"created":1731664202,"groupId":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","groupName":"Conclusions","stage":"Respond"}

id:ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3
event:TASK
data:{"id":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","model":"","choices":[{"delta":{"content":{"name":"Conclusions","id":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","status":"done","stage":"Respond","properties":{}}},"index":0}],"created":1731664202,"groupId":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","groupName":"Conclusions","stage":"Respond"}

id:-1
event:SOURCES
data:{"id":"-1","model":"","choices":[{"delta":{"content":[{"id":"1","source":"makeovermonday-a-century-of-global-deaths-from-disasters_decadal-deaths-disasters-type.csv","datasourceId":"clxin6l9200oo01l1457bolx3","datasetId":"clxin6l8400ok01l1ff2m0s25","fileType":"csv","externalId":"clxin6l0h001901hzxhjaae6q"}]},"index":0}],"created":1731664202,"groupId":"-1","groupName":"","stage":"Analyze"}

event:END_MARK
data:[DONE]

Example request:

curl --location 'https://ai.data.cloud/api/v1/team/jobs' \
  --header 'x-pd-api-key: $PD_API_KEY' \
  --header 'x-pd-api-agent-id: GENERAL' \
  --header 'Content-Type: application/json' \
  --data '{
  "datasetId": "cm3my37en3q36017q7x3hyyf4",
  "datasourceIdList": [
    "cm3myfsfc03jn011csb8wah6p"
  ],
  "languageType": "EN",
  "question": "How do '\''Digital Services for Taxpayers'\'' scores vary across economies, and which economy has the most advanced digital services?",
  "sessionId": "4440ab38-3df0-465b-a66c-bf6acb0f1bc2",
  "stream": false
}'

Example response:

{
"code": 0,
"data": {
    "jobId": "job-cm3ikdeuj02zk01l1yeuirt77",
    "blocks": [
        {
            "type": "CODE",
            "content": "```python\n\nimport pandas as pd\n\ndef invoke(input_0: pd.DataFrame) -> pd.DataFrame:\n    '''\n    input_0: pd.DataFrame  makeovermonday-a-century-of-global-deaths-from-disasters_decadal-deaths-disasters-type.csv\n    '''\n    # Group by 'Year' and sum the deaths for each type of disaster\n    aggregated_data = input_0.groupby('Year').sum().reset_index()\n    \n    # Select only the columns related to deaths\n    death_columns = [\n        'Deaths - Drought (decadal)', 'Deaths - Flood (decadal)', \n        'Deaths - Earthquake (decadal)', 'Deaths - Extreme weather (decadal)', \n        'Deaths - Extreme temperature (decadal)', 'Deaths - Volcanic activity (decadal)', \n        'Deaths - Wildfire (decadal)', 'Deaths - Glacial lake outburst flood (decadal)', \n        'Deaths - Dry mass movement (decadal)', 'Deaths - Wet mass movement (decadal)', \n        'Deaths - Fog (decadal)'\n    ]\n    \n    # Create a new DataFrame with the aggregated results\n    output = aggregated_data[['Year'] + death_columns]\n    \n    # Rename columns to be more descriptive\n    output.columns = ['Decade'] + [col.replace('Deaths - ', '').replace(' (decadal)', '') for col in death_columns]\n    \n    return output\n\n```",
            "groupId": "33063572-6e88-4912-8e2d-4166bcc8caee",
            "groupName": "Analyze the dataset to observe the trend of deaths caused by different types of natural disasters over the past century. This involves aggregating the data by decade and calculating the total number of deaths for each type of disaster to identify any changes in trends.",
            "stage": "Analyze"
        },
        {
            "type": "TABLE",
            "content": {
                "url": "https://static.powerdrill.ai/tmp_datasource_cache/code_result/cm37bchx106e301l1v9yf67yc/e24b6a5f-fdb8-48ca-ae35-dc91ac8e8ef7.csv",
                "name": "trend_data.csv",
                "expiredAt": "2024-11-21T09:56:34.290544Z"
            },
            "groupId": "33063572-6e88-4912-8e2d-4166bcc8caee",
            "groupName": "Analyze the dataset to observe the trend of deaths caused by different types of natural disasters over the past century. This involves aggregating the data by decade and calculating the total number of deaths for each type of disaster to identify any changes in trends.",
            "stage": "Analyze"
        },
        {
            "type": "IMAGE",
            "content": {
                "url": "https://static.powerdrill.ai/tmp_datasource_cache/code_result/cm37bchx106e301l1v9yf67yc/81b75a33-a223-4954-9680-9f397872c8ad.png",
                "name": "Trend of Deaths from Natural Disasters Over the Century",
                "expiredAt": "2024-11-21T09:56:34.290544Z"
            },
            "groupId": "7501680b-5879-441b-bd96-f58b1029ae17",
            "groupName": "Visualize the trend data to show how the number of deaths from different types of natural disasters has changed over the past century. Use line charts to represent the trends for each disaster type, which will help in understanding the impact of measures and technological advancements on reducing deaths.",
            "stage": "Analyze"
        },
        {
            "type": "MESSAGE",
            "content": "\n\n`Analyzing Conclusions` \n\n### Analysis of Trends in Natural Disaster Fatalities\n\n#### Data Analysis\n\n",
            "groupId": "b842aca7-6fd5-4190-85fa-97085e473877",
            "groupName": "Conclusions",
            "stage": "Respond"
        },
        {
            "type": "TABLE",
            "content": {
                "url": "https://static.powerdrill.ai/tmp_datasource_cache/code_result/cm37bchx106e301l1v9yf67yc/e24b6a5f-fdb8-48ca-ae35-dc91ac8e8ef7.csv",
                "name": "trend_data.csv",
                "expiredAt": "2024-11-21T09:56:34.290544Z"
            },
            "groupId": "b842aca7-6fd5-4190-85fa-97085e473877",
            "groupName": "Conclusions",
            "stage": "Respond"
        },
        {
            "type": "MESSAGE",
            "content": "\n\n- **Droughts and Floods**: In the early 20th century, droughts and floods caused extremely high death tolls, particularly in the 1920s and 1930s.\n- **Earthquakes and Extreme Weather**: Earthquakes and extreme weather also led to significant fatalities throughout the century, especially in the 1970s and 1990s.\n- **Extreme Temperatures and Volcanic Activity**: These disasters had relatively lower death tolls, but in certain decades, such as the 2000s, deaths caused by extreme temperatures increased.\n\n#### Trend Visualization\n\n",
            "groupId": "b842aca7-6fd5-4190-85fa-97085e473877",
            "groupName": "Conclusions",
            "stage": "Respond"
        },
        {
            "type": "IMAGE",
            "content": {
                "url": "https://static.powerdrill.ai/tmp_datasource_cache/code_result/cm37bchx106e301l1v9yf67yc/81b75a33-a223-4954-9680-9f397872c8ad.png",
                "name": "Trend of Deaths from Natural Disasters Over the Century",
                "expiredAt": "2024-11-21T09:56:34.290544Z"
            },
            "groupId": "b842aca7-6fd5-4190-85fa-97085e473877",
            "groupName": "Conclusions",
            "stage": "Respond"
        },
        {
            "type": "MESSAGE",
            "content": "\n\n- **Overall Trend**: The chart shows that, despite spikes in death tolls caused by natural disasters in certain decades, the overall trend is declining.\n- **Impact of Technology and Measures**: Over time, advancements in technology and the strengthening of disaster prevention measures are likely key factors contributing to the reduction in fatalities.\n\n#### Conclusions and Insights\n- **Technological Advancements**: Progress in modern technology, such as improved early warning systems and construction techniques, may have reduced deaths caused by earthquakes and extreme weather.\n- **Disaster Prevention Measures**: The enhancement of global disaster prevention efforts and emergency response capabilities has likely played a crucial role in mitigating the fatality rates of natural disasters.",
            "groupId": "b842aca7-6fd5-4190-85fa-97085e473877",
            "groupName": "Conclusions",
            "stage": "Respond"
        },
        {
            "type": "SOURCES",
            "content": [
                {
                    "source": "makeovermonday-a-century-of-global-deaths-from-disasters_decadal-deaths-disasters-type.csv",
                    "datasourceId": "clxin6l9200oo01l1457bolx3",
                    "datasetId": "clxin6l8400ok01l1ff2m0s25",
                    "fileType": "csv",
                    "externalId": "clxin6l0h001901hzxhjaae6q"
                }
            ],
            "groupId": "",
            "groupName": "",
            "stage": "Respond"
        },
        {
            "type": "QUESTIONS",
            "content": [
                "Analyze the changes in death toll trends for different types of natural disasters over the past century and explore which types of disasters have experienced the most significant reductions in fatalities.",
                "Study the differences in technological advancements and measures for responding to natural disasters across various regions globally, and analyze how these differences have influenced changes in death tolls in each region.",
                "Explore how potential future technological advancements and policy measures could further reduce fatalities caused by natural disasters, and assess their feasibility and potential impacts."
            ],
            "groupId": "-1",
            "stage": "Respond"
        }
    ]
}
}

When making a request:

Replace $PD_API_KEY with the API key you’ve obtained in Step 1.
Since this topic covers running a general job and no data agent is used, set the x-pd-api-agent-id header to GENERAL (uppercase).
Replace the sessionId value with the ID of the session you’ve created in Step 3.
To enable Powerdrill to retrieve information from your own data and provide responses specific to it, set the datasetId to the ID of the dataset obtained in Step 2.

Overview

Developer Guides

Datasets

Data sources

Files

Sessions

Jobs

Step 1. Get your project API key

Step 2. Create a dataset and a data source

Step 3. Create a session

Step 4. Create a job

Overview

Developer Guides

Datasets

Data sources

Files

Sessions

Jobs

​Step 1. Get your project API key

​Step 2. Create a dataset and a data source

​Step 3. Create a session

​Step 4. Create a job

Step 1. Get your project API key

Step 2. Create a dataset and a data source

Step 3. Create a session

Step 4. Create a job