Update Definition Texts

Similar to the example for updating query texts, you can also use the Mode API to update a Definition’s text without going into the Definitions editor. You might use this script to bulk update a table name for all Definitions for a given data source.

Endpoints used

Supported method:

  • GET: returns a list of data sources in your organization

Supported methods:

  • GET: returns a list of Definitions in your organization
  • POST: creates a Definition

Supported methods:

  • GET: returns a Definition
  • PATCH: updates a Definition
  • DELETE: deletes a Definition

How this example works

This code example’s update_definition method first makes a GET request to{organization}/datasources to return a list of data sources in the organization. This helps find the data source matching the name you provide as an argument to the function, along with finding its respective data source ID. We then makes a GET request to{organization}/definitions to return a list of all Definitions in the organization. This helps us find the matching Definition name given as an argument to the function, and its respective Definition token. Lastly, we make a PATCH request to{organization}/definitions/{definition_token} to update the Definition texts.

To try it yourself

  • Download the example code to a .py file
  • Input your API token, API secret, organization name, and other custom information as needed. An API token and secret can be generated here
  • Save the .py file in your desired directory
  • Open the terminal and navigate to that directory
  • Run the command python3 {file_name}.py
  • All of our Python recipes require Python 3
import json
import requests

from requests.auth import HTTPBasicAuth

host = ''
org = 'org_name'
un = 'api_token'
pw = 'api_secret'

def update_definition(data_source_name, definition_name, definition_text):

  url_datasources = '%s/api/%s/data_sources' % (host, org)
  r = requests.get(url, auth=HTTPBasicAuth(un,pw))
  result = r.json()
  data_sources = result['_embedded']['data_sources']
  selected_data_source = [d['id'] for d in data_sources if d['name'] == data_source_name]

  url_definitions = '%s/api/%s/definitions' % (host, org)
  r = requests.get(url_all_definitions, auth=HTTPBasicAuth(un,pw))
  result = r.json()
  definitions = result['_embedded']['definitions']
  selected_definition = [d['token'] for d in definitions if d['name'] == definition_name]

  url = '%s/api/%s/definitions/%s' % (host, org, selected_definition[0])
  payload = {'definition': {'data_source_id': selected_data_source[0], 'description': '', 'name': definition_name, 'source': definition_text}}
  headers = {'Content-Type': 'application/json'}

  r = requests.patch(url, auth=HTTPBasicAuth(un,pw), json=payload, headers=headers)
  return r.status_code

update_definition('data_source_name', 'definition_name', 'definition_text')
const request = require('request-promise');

const host = '';
const org = 'orgName';
const username = 'apiToken';
const password = 'apiSecret';

const updateDefinition = async (dataSourceName, definitionName, definitionText) => {
  const dataSources = await request({
    url: `${host}/api/${org}/data_sources`,
    json: true,
    auth: { username, password },
  const dataSourceId = dataSources._embedded.data_sources.filter(ds => === dataSourceName)[0].id;
  const definitions = await request({
    url: `${host}/api/${org}/definitions`,
    json: true,
    auth: { username, password },
  const definitionToken = definitions._embedded.definitions.filter(d => === definitionName)[0].token;
  const payload = {
    definition: {
      data_source_id: dataSourceId,
      description: '',
      name: definitionName,
      source: definitionText,

  return await request({
    url: `${host}/api/${org}/definitions/${definitionToken}`,
    method: 'PATCH',
    json: true,
    auth: { username, password },
    body: payload,

updateDefinition('dataSourceName', 'definitionName', 'definitionText');