Skip to main content

Response JMESPath

Note API Connector includes a built-in JMESPath interactive editor that allows you to transform JSON responses from an API.

JMESPath is a powerful query language for JSON that enables you to:

tip

Paste the copied JSON into an AI assistant (like ChatGPT, Claude, Gemini) and ask for a JMESPath that produces a table.

For example, you can ask:

“From this data, make a JMESPath query that returns an array of objects with id and subscription_id fields.”

This ensures your query produces a tabular output (array of objects) that maps cleanly into Notion.

Using JMESPath in Note API Connector​

To access the JMESPath editor:

1️⃣ Open the Response Field Mapping view.
2️⃣ Open Transform API Response → JMESPath.
3️⃣ In the editor on the right, enter your JMESPath query to choose and shape the data you need.

JMESPath Editor
tip

You can explore the official JMESPath tutorial to learn about writing JMESPath queries.

Keep Only Specific Fields​

You can filter an API response to retain only relevant fields.

Example: Extracting Employee Names and IDs

Suppose an API returns the following JSON with employee details:

{
  "employees": [
    {
      "id": 101,
      "name": "Alice Johnson",
      "department": "Engineering",
      "salary": 75000,
      "location": "New York"
    },
    {
      "id": 102,
      "name": "Bob Smith",
      "department": "Marketing",
      "salary": 68000,
      "location": "San Francisco"
    },
    {
      "id": 103,
      "name": "Charlie Adams",
      "department": "Finance",
      "salary": 72000,
      "location": "Chicago"
    }
  ]
}

If we only want to keep the id and name fields, we can use this JMESPath expression:

employees[].{id: id, name: name}

Explanation:

  • employees[] → Selects all objects inside the employees array.
  • {id: id, name: name} → Extracts only the id and name fields.

✅ Transformed JSON Output:

[
  {
    "id": 101,
    "name": "Alice Johnson"
  },
  {
    "id": 102,
    "name": "Bob Smith"
  },
  {
    "id": 103,
    "name": "Charlie Adams"
  }
]
Copy-paste prompt for AI to get this JMESPath

Write a JMESPath expression that uses the employees array and returns an array of objects with exactly these fields: id, name.

JSON: <PASTE YOUR EMPLOYEES JSON HERE>

This is useful when an API returns extra data you don’t need, and you want to import only relevant fields into Notion.

Transform Field Names​

JMESPath allows renaming fields to make data easier to work with.

Example: Renaming full_name to name

{
  "users": [
    {
      "id": 1,
      "full_name": "Jane Doe",
      "email": "[email protected]"
    },
    {
      "id": 2,
      "full_name": "John Smith",
      "email": "[email protected]"
    }
  ]
}

JMESPath Expression:

users[].{id: id, name: full_name}

✅ Transformed JSON Output:

[
  {
    "id": 1,
    "name": "Jane Doe"
  },
  {
    "id": 2,
    "name": "John Smith"
  }
]
Copy-paste prompt for AI to get this JMESPath

Write a JMESPath expression that uses the users array and returns an array of objects with exactly these fields: id, name (rename full_name to name).

JSON: <PASTE YOUR EMPLOYEES JSON HERE>

Filter Data Based on Conditions​

You can filter data dynamically using conditions like ==, >, <, and &&.

Example: Filtering Orders Above $50

{
  "orders": [
    {
      "order_id": 1001,
      "customer": "Alice",
      "total": 75.5
    },
    {
      "order_id": 1002,
      "customer": "Bob",
      "total": 42.0
    },
    {
      "order_id": 1003,
      "customer": "Charlie",
      "total": 120.0
    }
  ]
}

JMESPath Expression:

orders[?total > `50`]

✅ Transformed JSON Output:

[
  {
    "order_id": 1001,
    "customer": "Alice",
    "total": 75.5
  },
  {
    "order_id": 1003,
    "customer": "Charlie",
    "total": 120.0
  }
]
Copy-paste prompt for AI to get this JMESPath

Write a JMESPath expression that uses the orders array and returns only the items where total > 50. Keep the original fields.

JSON: <PASTE YOUR EMPLOYEES JSON HERE>

Extract Nested Data​

Many APIs return nested JSON objects, and JMESPath allows extracting values efficiently. Note API Connector has built-in Data Select feature that allows you to drill into deeply nested JSON fields and select exactly the data you want—no coding required.

Example: Extracting Usernames from Nested Profiles

{
  "users": [
    {
      "profile": {
        "username": "janedoe",
        "age": 28
      }
    },
    {
      "profile": {
        "username": "johnsmith",
        "age": 35
      }
    }
  ]
}

JMESPath Expression:

users[].profile.username

✅ Transformed JSON Output:

[
  "janedoe",
  "johnsmith"
]
Copy-paste prompt for AI to get this JMESPath

Write a JMESPath expression that uses the users array and returns an array of usernames from profile.username.

JSON: <PASTE YOUR EMPLOYEES JSON HERE>

Select a Specific Top-Level Array​

If an API returns multiple arrays, you can choose which array to process.

Example: Selecting Products Instead of Customers

{
  "customers": [
    { "id": 1, "name": "Alice" },
    { "id": 2, "name": "Bob" }
  ],
  "products": [
    { "id": "A1", "name": "Laptop" },
    { "id": "B2", "name": "Phone" }
  ]
}

JMESPath Expression:

products[]

✅ Transformed JSON Output:

[
  {
    "id": "A1",
    "name": "Laptop"
  },
  {
    "id": "B2",
    "name": "Phone"
  }
]
Copy-paste prompt for AI to get this JMESPath

Write a JMESPath expression that selects the products array (ignore other arrays) and returns all product objects as an array.

JSON: <PASTE YOUR EMPLOYEES JSON HERE>

This is useful when an API returns multiple arrays, and you only need data from one of them.

Summary​

JMESPath allows powerful JSON transformations, helping you filter, rename, and extract data before sending it to Notion.

📌 Key Takeaways:

✅ Use [].{} syntax to extract only needed fields.
✅ Rename fields using new_name: existing_field syntax.
✅ Filter data using [?condition] expressions.
✅ Navigate nested structures with object.field syntax.
✅ Select a specific top-level array using array_name[].

For more advanced queries, check the official JMESPath documentation.

Leave a Comment