Versions API

The Versions API lets you programmatically manage saved versions of a dashboard (Embeddable) in your workspace. You can list the last thirty saved versions of a specific dashboard (Embeddable) in your workspace, and fetch the full Dashboard as Code definition of any saved version. This is useful for managing deployments, rolling back changes, or promoting versions through your development workflow. You can also publish a specific version to an environment tag (development, staging, or production). This is the foundation for fully automated, CI/CD-driven deployment workflows.

List Saved Versions

Endpoint

GET https://api.<region>.embeddable.com/api/v1/embeddables/{embeddableId}/saved-versions

Example Request

// Important: Always call this server-side, never from client-side code
fetch('https://api.<region>.embeddable.com/api/v1/embeddables/{embeddableId}/saved-versions', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'Authorization': `Bearer ${apiKey}` // Keep your API key secure
  }
})
  .then((res) => res.json())
  .then(console.log);

Example Response

{
  "tags": {
    "development": { "version": "v3", "updated-at": "2025-06-27T09:32:10.004Z" },
    "production": { "version": "v2", "updated-at": "2025-06-21T16:12:53.542Z" }
  },
  "saved-versions": [
    {
      "version": "v1",
      "saved-by": "sina@embeddable.com",
      "description": "Our first publish!!",
      "saved-at": "2025-06-19T09:01:03.023523Z",
      "components-version": "2025-02-11T18:53:03.527633Z",
      "models-version": "2025-02-11T18:53:03.527633Z", // cube-internal only
      "cube-version": "1.3.22" // cube-internal only
    }
    // ... up to last 30
  ]
}

Field Reference

• tags.development / staging / production: Present only if the embeddable has been published to that tag. updated-at is when the tag last changed.
• saved-versions[]: Each saved version, newest first.
  • version: The generated version label (v1, v2, ...).
  • saved-by: Email of the user who saved it.
  • description: The Save version note. Also appears in the builder and publish modal.
  • saved-at: When the snapshot was taken.
  • components-version / models-version / cube-version: The underlying versions that this saved version references.

Notes

• Version values are per embeddable and are not shared across different dashboards.
• The API returns the last 30 saved versions, ordered by the saved-at timestamp.

Publish a Version to an Environment

Use this endpoint to assign an environment tag (development, staging, or production) to a specific saved version. This replaces the need to manually click Publish in the UI, making it suitable for fully automated CI/CD pipelines.

Endpoint

POST https://api.<region>.embeddable.com/api/v1/embeddables/{embeddableId}/saved-versions/{version}/publish

• {version} — the saved version number to publish, e.g. v3. Must be a version number, not a tag name.
• {embeddableId} — the UUID of the dashboard.

Request Body

{
  "tags": ["staging"]
}

• tags — an array of one or more environment tags to assign this version to. Valid values: "development", "staging", "production". Must not be empty.
• You can promote to multiple tags in a single call, e.g. ["staging", "production"].

Example Request

// Important: Always call this server-side, never from client-side code
fetch('https://api.<region>.embeddable.com/api/v1/embeddables/{embeddableId}/saved-versions/v3/publish', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'Authorization': `Bearer ${apiKey}` // Keep your API key secure
  },
  body: JSON.stringify({
    tags: ['staging']
  })
})
  .then((res) => res.json())
  .then(console.log);

Example Response

Returns the updated tag map for the dashboard:

{
  "tags": {
    "development": { "version": "v1", "updatedAt": "2025-10-15T09:15:33.396135Z" },
    "staging":     { "version": "v3", "updatedAt": "2026-09-24T09:15:45.216583Z" },
    "production":  { "version": "v5", "updatedAt": "2026-07-08T10:39:59.997373Z" }
  }
}

Error Responses

Notes

• The call is idempotent — publishing the same version to the same tag repeatedly is safe, which makes it suitable for CI retries.
• Only one saved version can be assigned to a given tag at a time. Publishing a new version to a tag moves the tag; other tags are unaffected.
• The endpoint only accepts explicit version numbers (e.g. v3). You cannot pass a tag name in the {version} position.
• Any token that references a tag (e.g. "savedVersion": "staging") will automatically resolve to the newly published version — no token regeneration needed.

CI/CD Example

A typical automated workflow using this API:

1. Code is merged to main — your CI pushes a new components build to Embeddable.
2. CI calls the List Saved Versions endpoint to find the latest v{N} that corresponds to that build.
3. CI calls Publish to move staging to that version:

   curl -X POST "https://api.<region>.embeddable.com/api/v1/embeddables/{embeddableId}/saved-versions/v3/publish" \
     -H "Authorization: Bearer $EMBEDDABLE_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"tags":["staging"]}'
4. After QA sign-off, the same call is repeated targeting production.

Get version metadata

Fetch the full Dashboard as Code definition of a specific saved version, as JSON.

Endpoint

GET https://api.<region>.embeddable.com/api/v1/embeddables/{embeddableId}/saved-versions/{version}/metadata

Example Request

// Important: Always call this server-side, never from client-side code
fetch('https://api.<region>.embeddable.com/api/v1/embeddables/{embeddableId}/saved-versions/{version}/metadata', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'Authorization': `Bearer ${apiKey}` // Keep your API key secure
  }
})
  .then((res) => res.json())
  .then(console.log);

{version} is one of the version labels returned by the list saved versions endpoint (e.g. v1).

Example Response

Returns the dashboard's definition in the same JSON shape as its YAML dashboards-as-code source — variables, datasets, and widgets — as it existed at that saved version.

{
  "name": "my-embeddable",
  "title": "My Embeddable",
  "variables": [
    { "name": "date-range", "type": "timeRange", "defaultValue": { "from": "2024-01-01", "to": "2024-12-31" } }
  ],
  "datasets": [
    {
      "name": "filtered-data",
      "model": "daily_listens",
      "filters": [
        { "member": "daily_listens.date", "operator": "inDateRange", "value": "date-range", "valueType": "VARIABLE" }
      ]
    }
  ],
  "widgets": [
    {
      "component": "BarChart",
      "position": { "x": 0, "y": 0 },
      "dimensions": { "width": 12, "height": 6 },
      "inputs": [
        { "input": "metric", "inputType": "measure", "value": "daily_listens.count" }
      ]
    }
  ]
}

Related Topics

• Token Targeting: How to use saved versions in your Embeddable tokens.
• Promotion Strategies: Best practices for managing and promoting dashboard