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

Why migrate from Legacy API (v0)

The Legacy API (v0) is being deprecated and will stop accepting data, so you must migrate to the Databox API (v1) to continue sending custom data. This migration requires updating your existing integration code, as Databox cannot automatically update external scripts, applications, or third-party tools.

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.

Aspect	Legacy API (v0)	Databox API (v1)
Architecture	Pre-aggregated metrics	Dataset-based raw data
Authentication	Basic (<empty>:<token>)	API key (x-api-key header)
Base URL	push.databox.com	api.databox.com/v1/...
Data format	Metric-value pairs {"data": [{"$metric": value}]}	Records with schema and primary keys {"records": [{...}]}

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 it is officially deprecated. Migrating early reduces risk, allows time for testing, and helps avoid disruptions to reporting.

What happens if I don’t migrate before deprecation?

Once the Legacy API (v0) is deprecated, it will stop accepting new data. Any metrics that rely on it will stop updating and continue to display their last recorded values. Historical data will remain available, but no new data will be accepted until you complete the migration to the Databox API.

Still need help?

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