API Documentation

Create an API

To create an API select the "API" Spell on the Spells page. On the create API form you can choose which folder to associate with the API and whether the API is read-only.

If no folder is selected, all notes in your /tap account will be accessible from the API.

Once created you will receive an API URL and key shown on the main Spells page.

Access the API

All requests sent to the API must include an "x-api-key" header set to the API key provided on the Spells page.

View your notes

To retrieve notes from the API simply send a GET request along with the API key included in the "x-api-key" header to the URL provided on your Spells page.

curl -H "x-api-key: {{YOUR API KEY}}" \
-X GET https://api.tatatap.com/notes/v1/{{YOUR API ID}}

A typical response looks like this:

[{
    "id": "a2c9b7bb-b1d5-42e3-bda7-c479e32bc4df",
    "note_body": "Computer making sense alone in a dark room",
    "folder": "/log/",
    "date": "3333-05-11T02:00:00.000Z",
    "tags": [],
    "events": [],
    "beans": [],
    "bookmarks": [],
    "todo": "NONE",
    "full_note": "/log Computer making sense alone in a dark room"
  },

  {
    "id": "d90be409-4123-41dc-9c4c-0d45e15467a1",
    "note_body": "we are part of the recipe: +🧠 +⛲️7 +🌳100000 +🦩2 +👄 -🩸100",
    "folder": "/log/",
    "date": "2020-05-17T00:00:00.000Z",
    "tags": [],
    "events": [],
    "beans": [
      {
        "symbol": "🧠",
        "amount": 1,
        "tx_id": "f9af9979-ece7-4278-89df-0e480425b2f6"
      },
      {
        "symbol": "⛲️",
        "amount": 7,
        "tx_id": "120190fd-e43c-4620-bb54-b054fdbbcf08"
      },
      {
        "symbol": "🌳",
        "amount": 100000,
        "tx_id": "973ce3e5-fe4c-46a4-939b-4f26c3bf743b"
      },
      {
        "symbol": "🦩",
        "amount": 2,
        "tx_id": "b22e6eff-a2e8-4d96-ac1d-842fcd626d88"
      },
      {
        "symbol": "👄",
        "amount": 1,
        "tx_id": "74437896-a054-48d7-bade-22a69dbecdf2"
      },
      {
        "symbol": "🩸",
        "amount": -100,
        "tx_id": "a492dde2-9054-4dce-86de-1079372a514a"
      }
    ],
    "bookmarks": [],
    "todo": "NONE",
    "full_note": "/log we are part of the recipe: +🧠 +⛲️7 +🌳100000 +🦩2 +👄 -🩸100"
  }]

To retrieve a single note include the note ID after the API ID like this:

curl -H "x-api-key: {{YOUR API KEY}}" \
-X GET https://api.tatatap.com/notes/v1/{{YOUR API ID}}/d90be409-4123-41dc-9c4c-0d45e15467a1

Creating new notes

To create a new note POST to the API URL along with a "Content-Type" header and a request payload in JSON format with a single "note" property.

curl -d '{"note":"I sure did that thing"}' \
-H "Content-Type: application/json" \
-H "x-api-key: {{YOUR API KEY}}" \
-X POST https://api.tatatap.com/notes/v1/{{YOUR API ID}}

If your API is associated with a folder, the note will automatically appear in that folder. If a folder is included at the beginning of the note, such as:

curl -d '{"note":"/folder I sure did that thing"}' \
-H "Content-Type: application/json" \
-H "x-api-key: {{YOUR API KEY}}" \
-X POST https://api.tatatap.com/notes/v1/{{YOUR API ID}}

The "/folder" will be appended to the folder associated with the API, creating a nested folder.

Updating notes

To update an existing note, include the note ID in the URL following the API ID, along with the new note payload, as seen below.

curl -d '{"note":"What I actually meant was..."}' \
-H "Content-Type: application/json" \
-H "x-api-key: {{YOUR API KEY}}" \
-X POST https://api.tatatap.com/notes/v1/{{YOUR API ID}}/{{YOUR NOTE ID}}

Deleting Notes

To delete a note send a DELETE request to the API URL that includes both the API ID and the note ID.

curl -d -H "x-api-key: {{YOUR API KEY}}" \
-X DELETE https://api.tatatap.com/notes/v1/{{YOUR API ID}}/{{YOUR NOTE ID}}

Retrieving Beans

The Beans endpoint returns symbol totals for the beans in the folder associated with the API across several different ranges.

The different totals returned are:

  • All-time total including all beans
  • Yearly totals including all beans
  • Monthly totals including all beans
  • All-time total per-symbol
  • Yearly totals per symbol
  • Monthly totals per symbol
curl -H "x-api-key: {{YOUR API KEY}}" \
-X GET https://api.tatatap.com/notes/v1/{{YOUR API ID}}/beans

A typical response looks like this:

[
  {
    "net": 100,
    "incoming": 100,
    "outgoing": 0,
    "symbol": "⚡",
    "date": "2020"
  },
  {
    "net": 100,
    "incoming": 100,
    "outgoing": 0,
    "symbol": "⚡",
    "date": "2020-05"
  },
  {
    "net": 100,
    "incoming": 100,
    "outgoing": 0,
    "symbol": "⚡"
  },
  {
    "net": 100000,
    "incoming": 100000,
    "outgoing": 0,
    "symbol": "🌳"
  },
  {
    "net": 100000,
    "incoming": 100000,
    "outgoing": 0,
    "symbol": "🌳",
    "date": "2020"
  },
  {
    "net": 100000,
    "incoming": 100000,
    "outgoing": 0,
    "symbol": "🌳",
    "date": "2020-05"
  },
  ...
]

OpenAPI Specification