I’ve been working a lot with REST APIs recently from the terminal and I’ve upped my bash-foo a little so let me share it with you. Ofcourse you can always escape to a programming language like ruby or node. But for basic things these are fine too.

Le tool-shed

The tools I come back to basically are:

  • bash - For scripting
  • curl - For doing HTTP requests
  • jq - For parsing and colorizing Json output and generating CSV’s
  • csvkit - Work with CSVs for easier parsing (which comes in another blog)


Curl, the old trusty steed will be used with the -H to supply the headers and the tokens from a file. As a convention the header file is the same name as the domain. Don’t forget to add to your .gitignore.

You can also use -d @mybody.txt to add body data. The f param is to fail with an error if the return isn’t status code 200.

Lets make a header file notion.txt first. You will need to replace the XXX with your notion token, and dont forget to share the page with the integration under the share button.

The notion.txt:

Authorization: Bearer XXXX
Content-Type: application/json
Notion-Version: 2021-07-27

And to query:

curl -fH @notion.txt https://api.notion.com/v1/pages/cce9a48b-2a29-4ed7-8a1b-ed0cbd2ba5ac

Doing a POST to query the DB:

curl -fH @notion.txt -X POST \
https://api.notion.com/v1/databases/849170c3ebcb4015aa6c6f935d4cf768/query | jq


Often times the JSON you get back is not in the shape you want it or just way to bloated or unformatted. You can use JQ to slim it down or format things.

To format the JQ and save it in a file:

curl -fH @myapi.txt -X GET https://myapi.com/customers | jq > data.json

Or you can use it to slice up some data:

curl -fH @notion.txt https://api.notion.com/v1/databases/849170c3ebcb4015aa6c6f935d4cf768 \
  | jq '.properties'

You can also use the @csv to function in jq to generate CSV files.


More about this a future post!

More vintage REST? Subscribe below!

Would you like to stay up to date on ? Subscribe here! I'll only use your email to keep u up to date on new technology and software development tips. It wont be shared. Feel free to unsubscribe anytime!