Migrate from Legacy API (v0) to Databox API (v1)

Why migrate from Legacy API (v0)

We're transitioning from the Legacy API (v0) to the Databox API (v1). With this transition, the process for sending custom data to Databox has changed, so you'll need to update your existing integration code. Databox cannot automatically modify external scripts, applications, or third-party tools that send data to via API.

The Databox API introduces a dataset-based architecture that separates data ingestion from metric creation. Instead of sending pre-aggregated metric values, you send raw records to datasets and define metrics later in the Databox UI. This approach provides greater flexibility, improved performance, and more powerful analytics.

By working with datasets, you can:

• Reuse the same data across multiple metrics
• Analyze data across multiple dimensions
• Apply filters and drill-downs in visualizations
• Create custom calculated columns
• Merge datasets from multiple data sources
• Export raw data when needed
• Benefit from faster refresh times and easier long-term maintenance
• Use AI-powered insights with Genie and Databox MCP

Key considerations for migration

What's changing

The Databox API changes how requests are authenticated, which endpoint is used, and how data is structured. Instead of sending metric-value pairs, you send records that conform to a dataset schema and may include primary keys.

What stays the same

Existing data and account structure remain unchanged. Historical data, metric definitions, and existing content are preserved and remain accessible.

Manual migration steps

Step 1: Prepare the Databox API and dataset

Begin by setting up the Databox API. Generate an API key and create a new data source using the Databox API. Then define a dataset that reflects the structure of the data you currently send through the Legacy API (v0). This includes creating columns for values and dimensions and selecting appropriate primary keys.

Before finalizing the schema, review how your existing integration sends data. Understanding the current data format helps you design a dataset that supports filtering, drill-downs, and future metric flexibility. Many teams create a test dataset first to validate the structure before migrating production data.

Step 2: Update your integration and create metrics

Next, update your integration code to use the Databox API. Update the authentication settings and base URL, and refactor the payload to send records that match the dataset schema. Testing these changes in a staging environment or controlled setup helps catch formatting or authentication issues early.

Once records appear in the dataset, create new metrics based on that dataset. Metrics can be configured manually by selecting the dataset and defining aggregations, dimensions, and filters, or generated using Genie with natural language prompts. Comparing results between legacy metrics and new dataset-based metrics at this stage helps confirm data accuracy.

Step 3: Replace legacy metrics and verify the migration

After metrics are created, replace Legacy API metrics wherever they’re used in your account. Swap each legacy metric for the dataset-based version and verify that values display as expected. Some teams temporarily run legacy and new integrations in parallel to validate results before fully switching over.

Continue monitoring data flow over several data cycles. Confirm that new records continue to arrive and that metrics update consistently. Once the migration is verified, delete custom data sources/tokens and update any internal documentation that references the Legacy API (v0). This final step helps prevent accidental usage and ensures a clean transition.

Common migration scenarios

Simple periodic data send

For scheduled values such as daily totals:

• Use a dataset with a date and value column
• Set the date as the primary key
• Send one record per period

Multi-dimensional data

For data broken down by attributes such as region or product:

• Create a column for each dimension
• Include date and all dimensions in the primary key
• Send one record per unique combination 

This enables filtering and drill-downs not available with the Legacy API (v0).

Metrics with units

If your legacy metrics include units, such as USD or lbs:

• Send only the numeric value in the dataset, even if the metric has a unit.
• Define the unit when configuring the metric in Databox, or store it in a separate column in the dataset.
• When all records use the same unit, set the unit at the metric level instead of sending it with each record.
• If values are reported in multiple units, include a unit column in the dataset and add it to the primary key. 

This ensures values aggregate correctly while still allowing filtering and analysis by unit.

Frequently Asked Questions

Can I keep using the Legacy API (v0) until it is deprecated?

Yes. The Legacy API (v0) will continue accepting data until the transition is complete. We recommend migrating early so you have time to test your new integration and ensure uninterrupted reporting.

What happens if I don’t migrate before deprecation?

After the transition, the Legacy API (v0) will no longer accept new data. Metrics that rely on it will continue to display their last recorded values until you complete the migration. All historical data will remain available and no data will be lost.

Still need help?

Visit our community, send us an email, or start a chat in Databox.