# Changelog Version v2.1.0 ## v2.1.0 ### New endpoints #### Dashboards - `GET /v2/dashboards` — Retrieves a paginated list of dashboards in the organization. - `PATCH /v2/dashboards/{id}` — Renames a specific dashboard. - `GET /v2/dashboards/{id}/metrics` — Retrieves the Datablocks and associated metric configurations for a specific dashboard. The two read endpoints replace their `databoards` equivalents and behave identically; see [Deprecations](#deprecations). Renaming is new. A dashboard name is trimmed of leading and trailing whitespace before it's validated and stored, must be between 1 and 65 characters once trimmed, and can't contain control characters such as tabs or line breaks. Dashboards that belong to a template can't be renamed through the API. #### Metrics - `POST /v2/metrics/{id}/data` — Retrieves a metric's values over a date range, grouped by a granularity, with an optional breakdown by dimensions and optional filters. The endpoint works for integration, custom, calculated, and pushed metrics. If the metric is due by its sync schedule, or has never synced, it is synced before it is read; otherwise stored data is returned. The `syncInfo` property reports which happened and how current the values are, and is `null` for a metric that never syncs, such as a constant or media metric. `dateRange.granularity` is required and accepts `daily`, `weekly`, `monthly`, `quarterly`, `yearly`, or `allTime`. `sourceId` is required unless the metric ID is prefixed with its data source or dataset ID. Filter conditions accept the `ANY_OF`, `NONE_OF`, `EQ`, `NEQ`, `CONTAINS`, and `NOT_CONTAINS` operators. The first call on a metric that has never synced can take up to about two minutes. The endpoint is limited to 30 calls per account per minute, beyond which it returns `429` with a `Retry-After` header giving the number of seconds to wait. When the metric is defined on a dataset whose saved modification is still being applied, the endpoint returns `409` with a `Retry-After` header instead of serving values that do not yet reflect the modification. A `409` does not count against the rate limit. ### Enhancements #### Dataset type and merged datasets `GET /v2/datasets` and `GET /v2/datasets/{id}` now return a `type` for every dataset: `dataset` for one that holds its own data, whether ingested through the API or synced from a data source, and `mergedDataset` for one assembled from other datasets. `GET /v2/datasets` takes a matching `type` filter. It defaults to `dataset`, so a request that doesn't send it returns the same datasets it returned before. A merged dataset has no data source of its own, so `dataSourceId` is `null` for it. Clients that read `dataSourceId` from a dataset response should handle null. #### Custom metric descriptions `GET /v2/metrics` and `GET /v2/metrics/{id}` now return a `description` for every metric, and `PATCH /v2/metrics/{id}` sets it on custom metrics built on a dataset. Send an empty string to clear it; a `null` value isn't treated as a value at all, so a body whose only field is `description: null` is rejected as empty. A description can only be set through `PATCH /v2/metrics/{id}`. `POST /v2/metrics` ignores the field, so a metric created with a description is stored without one. Updating a metric through the API no longer clears a description set in the app. Previously any update, including a rename, discarded it. #### Consistent errors for unmatched routes and methods A request to a `/v2` path that matches no endpoint now returns the standard error envelope with `not_found`, instead of an empty body. An unsupported method on an endpoint that does exist returns `405` with `method_not_allowed` and an `Allow` header listing the methods that are supported. Routes that take an ID now report a missing resource identically. `GET /v2/dashboards/{id}/metrics`, and its `databoards` alias, return the same `Dashboard not found` on `id` as the rename endpoint. #### Clearer request body validation errors A body field of the wrong type now produces a single error rather than two, and `field` no longer carries a `$.` prefix — `name`, not `$.name`. A field nested inside the body is reported as a dotted path, such as `measure.id`, and messages no longer expose serializer internals. ### Deprecations #### `/v2/databoards` is now `/v2/dashboards` Databoards are called dashboards throughout the API and its documentation. The dashboard endpoints are the same operations under the new name: identical parameters, response envelope, and payload — only the path segment changed. The old paths continue to work: - `GET /v2/databoards` - `GET /v2/databoards/{id}/metrics` They're deprecated and no longer listed in the [API Reference](/docs/api/api.databox.com). Renaming is available only under the new path; `PATCH /v2/databoards/{id}` returns `404`. To migrate, replace `databoards` with `dashboards` in the path — nothing else needs to change. ### Breaking changes #### Dataset modifications are applied asynchronously A modification saved with `PUT /v2/datasets/{id}/modifications` is now built in the background after the request returns. While that build is in progress, endpoints that read or update the dataset's rows, schema, or columns, along with metric endpoints that read from or are defined on that dataset, return `409` with a `Retry-After` header rather than answering with data that does not yet reflect the saved modification: - `GET /v2/datasets/{id}/data` - `GET /v2/datasets/{id}/schema` - `GET /v2/datasets/{id}/metadata` - `PATCH /v2/datasets/{id}/metadata` - `GET /v2/datasets/{id}/column-metadata` - `PATCH /v2/datasets/{id}/column-metadata` - `DELETE /v2/datasets/{id}/modifications` - `POST /v2/metrics` - `PATCH /v2/metrics/{id}` - `POST /v2/metrics/{id}/data` - `POST /v2/metrics/dimensions/values` - `POST /v2/metrics/drilldown` Two error codes are returned. `modification_in_progress` means the modification is still being applied — wait the number of seconds given in `Retry-After`, then send the same request again. `modification_failed` means the modification could not be applied; this is final, and retrying will not help. A build usually completes within a few seconds, so only clients that read or update a dataset immediately after saving a modification are affected. Previously, reads in that window returned `200` with an empty schema or no rows, and updates that named a column returned `400` reporting a real column as unknown. `GET /v2/datasets/{id}`, the dataset list, and `GET /v2/datasets/{id}/modifications` are never refused during a build. #### `hourly` is no longer listed in `availableGranularities` `GET /v2/metrics/{id}`, and the metric returned by `POST /v2/metrics` and `PATCH /v2/metrics/{id}`, no longer include `hourly` in `availableGranularities`. This affects only clients that build a granularity picker from this list. `hourly` is still accepted everywhere it was before, such as on dashboards. v2.0.0 ## v2.0.0 ### Initial release This is the first release of the Databox API v2. It replaces the ingestion-focused v1 API with a much broader surface: full organization, billing, account, connection, Databoard, integration, metric, profile, and user management, alongside significantly deeper control over data sources and datasets. Every successful response now nests its payload under a `data` field, and list responses use a generic `items` array with zero-indexed `page`/`pageSize` pagination. POST endpoints that create a resource or trigger a side effect accept an optional `Idempotency-Key` header, so retrying a request after a timeout or dropped connection is safe: supply a client-generated unique value (a UUID is recommended), and if the same key is sent again within 24 hours, the API returns the original response instead of re-executing the operation. Supported on account, data source, dataset, and metric creation; dataset ingestion and duplication; and data source and dataset purge. See [Rate limits → Idempotent retries](/docs/api/rate-limits#idempotent-retries). See the [migration guide](/docs/api/migration-guide) for a full breakdown of what changed for teams moving from v1. ### Available endpoints #### Accounts - `GET /v2/accounts` — Retrieves a paginated list of accounts in the organization associated with the authenticated user. - `POST /v2/accounts` — Creates an account in the organization associated with the authenticated user. - `GET /v2/accounts/{id}` — Retrieves details about a specific account. - `PATCH /v2/accounts/{id}` — Updates information for a specific account. - `DELETE /v2/accounts/{id}` — Deletes a specific account from the organization associated with the authenticated user. #### Auth - `GET /v2/auth/validate-key` — Validates the API key supplied in the `x-api-key` header. #### Billing - `GET /v2/billing` — Retrieves billing and subscription details for the organization associated with the authenticated user. - `GET /v2/billing/invoices` — Retrieves a paginated list of invoices for the organization associated with the authenticated user. #### Connections - `GET /v2/connections` — Retrieves a paginated list of connections in the organization. - `GET /v2/connections/{id}` — Retrieves details about a specific connection. - `PATCH /v2/connections/{id}` — Updates information for a specific connection. - `DELETE /v2/connections/{id}` — Deletes a specific connection from the organization. - `GET /v2/connections/{id}/permissions` — Retrieves the permissions configured for a specific connection. - `PUT /v2/connections/{id}/permissions` — Updates the permissions for a specific connection. #### Data Sources - `GET /v2/data-sources` — Retrieves a paginated list of data sources in the organization. - `POST /v2/data-sources` — Creates a data source for sending custom data to Databox through the API. - `GET /v2/data-sources/{id}` — Retrieves details about a specific data source. - `PATCH /v2/data-sources/{id}` — Updates information for a specific data source. - `DELETE /v2/data-sources/{id}` — Permanently deletes a specific data source from the organization, including all datasets it contains. - `GET /v2/data-sources/{id}/permissions` — Retrieves the permissions configured for a specific data source. - `PUT /v2/data-sources/{id}/permissions` — Updates the permissions for a specific data source. - `POST /v2/data-sources/{id}/purge` — Permanently deletes all data stored in a specific data source. - `PUT /v2/data-sources/{id}/sync-frequency` — Updates the sync frequency for a specific data source. - `GET /v2/data-sources/{id}/sync-frequency-options` — Retrieves the sync frequencies available for a specific data source. - `PUT /v2/data-sources/{id}/timezone` — Updates the time zone for a specific data source. #### Databoards - `GET /v2/databoards` — Retrieves a paginated list of Databoards in the organization. - `GET /v2/databoards/{id}/metrics` — Retrieves the Datablocks and associated metric configurations for a specific Databoard. #### Datasets - `GET /v2/datasets` — Retrieves a paginated list of datasets available to the authenticated user. - `POST /v2/datasets` — Creates a dataset in the specified data source. - `GET /v2/datasets/{id}` — Retrieves details about the specified dataset. - `PATCH /v2/datasets/{id}` — Updates the properties of the specified dataset. - `DELETE /v2/datasets/{id}` — Permanently deletes the specified dataset and its stored data. - `GET /v2/datasets/{id}/column-metadata` — Retrieves metadata configured for the columns in the specified dataset. - `PATCH /v2/datasets/{id}/column-metadata` — Updates metadata for one or more columns in the specified dataset. - `GET /v2/datasets/{id}/data` — Retrieves a paginated list of records stored in the specified dataset. - `POST /v2/datasets/{id}/data` — Submits records for ingestion into the specified dataset. - `POST /v2/datasets/{id}/duplicate` — Creates a copy of the specified dataset. - `GET /v2/datasets/{id}/ingestion-statistics` — Retrieves ingestion performance statistics for the specified dataset. - `GET /v2/datasets/{id}/ingestions` — Retrieves a paginated list of ingestion attempts for the specified dataset. - `GET /v2/datasets/{id}/ingestions/{ingestionId}` — Retrieves details about the specified dataset ingestion. - `GET /v2/datasets/{id}/lineage` — Retrieves the specified dataset's lineage, including upstream data sources and datasets and downstream datasets and metrics. - `GET /v2/datasets/{id}/metadata` — Retrieves metadata configured for the specified dataset. - `PATCH /v2/datasets/{id}/metadata` — Updates metadata for the specified dataset. - `GET /v2/datasets/{id}/modifications` — Retrieves the modification configured for the specified dataset. - `PUT /v2/datasets/{id}/modifications` — Replaces the modification configured for the specified dataset. - `DELETE /v2/datasets/{id}/modifications` — Deletes the modification configured for the specified dataset. - `POST /v2/datasets/{id}/modifications/preview` — Applies the supplied modification settings and returns a preview without saving the changes. - `GET /v2/datasets/{id}/permissions` — Retrieves the permissions configured for the specified dataset. - `PUT /v2/datasets/{id}/permissions` — Replaces the permissions configured for the specified dataset. - `POST /v2/datasets/{id}/purge` — Permanently removes all stored records from the specified dataset without deleting the dataset. - `GET /v2/datasets/{id}/schema` — Retrieves the column definitions for the specified dataset. - `PUT /v2/datasets/{id}/sync-frequency` — Updates the scheduled sync frequency for the specified dataset. - `GET /v2/datasets/{id}/sync-frequency-options` — Retrieves the sync frequencies available for the specified dataset. - `GET /v2/datasets/{id}/sync-history` — Retrieves a paginated history of sync attempts for the specified dataset. - `GET /v2/datasets/{id}/sync-history/statistics` — Retrieves sync performance statistics for the specified dataset. - `PUT /v2/datasets/{id}/timezone` — Updates the time zone used by the specified dataset. - `GET /v2/datasets/{id}/verification` — Retrieves the verification status of the specified dataset. - `PUT /v2/datasets/{id}/verification` — Updates the verification status of the specified dataset. - `GET /v2/datasets/modifications/functions` — Retrieves the functions available for calculated columns in dataset modifications. - `GET /v2/datasets/modifications/rules` — Retrieves the rules available for configuring dataset modifications. #### Integrations - `GET /v2/integrations` — Retrieves a paginated list of all available integrations. - `GET /v2/integrations/{id}` — Retrieves details about a specific integration. #### Metrics - `GET /v2/metrics` — Retrieves a paginated list of metrics in the organization. - `POST /v2/metrics` — Creates a metric from the specified dataset and metric configuration. - `GET /v2/metrics/{id}` — Retrieves details about a specific metric. - `PATCH /v2/metrics/{id}` — Updates the configuration of a specific metric. - `DELETE /v2/metrics/{id}` — Deletes a specific metric from the organization. - `GET /v2/metrics/{id}/lineage` — Retrieves the specified metric's lineage, including upstream data sources, datasets, and metrics. - `GET /v2/metrics/{id}/usages` — Retrieves the locations where a specific metric is used. - `GET /v2/metrics/{id}/verification` — Retrieves the verification status and details for a specific metric. - `PUT /v2/metrics/{id}/verification` — Updates the verification status of a specific metric. - `POST /v2/metrics/dimensions/values` — Retrieves the available dimension values for one or more metrics. - `POST /v2/metrics/drilldown` — Retrieves the underlying records for a metric within a specified period. #### Organization - `GET /v2/organization` — Retrieves details about the organization associated with the authenticated user. - `PATCH /v2/organization` — Updates details and settings for the organization associated with the authenticated user. - `GET /v2/organization/activity-log` — Retrieves a paginated list of activity recorded within the organization. - `GET /v2/organization/countries` — Retrieves the list of available countries and their country codes. - `GET /v2/organization/metadata-options` — Retrieves the available business classification, industry, company size, and annual revenue options for populating the organization's metadata. - `GET /v2/organization/timezones` — Retrieves the list of all time zones supported by Databox, including their UTC offsets and IANA identifiers. - `GET /v2/organization/usage` — Retrieves current usage and limits for resources within the organization associated with the authenticated user. #### Profile - `GET /v2/profile` — Retrieves profile information for the authenticated user. - `PATCH /v2/profile` — Updates profile information for the authenticated user. - `GET /v2/profile/metadata-options` — Retrieves the available department and role options for populating a user's profile metadata. #### Users - `GET /v2/users` — Retrieves a paginated list of users associated with the organization. - `POST /v2/users` — Creates a user in the organization. - `GET /v2/users/{id}` — Retrieves details about a specific user. - `PATCH /v2/users/{id}` — Updates information for a specific user. - `DELETE /v2/users/{id}` — Deletes a specific user from the organization.